PDAP Public Review Draft

javax.microedition.pim
Interface Event

All Superinterfaces:
PIMElement

public interface Event
extends PIMElement

Represents a single Event entry in a PIM Event database. The fields are a subset of the fields in the vEvent object defined by the vCalendar 1.0 specification from the Internet Mail Consortium (http://www.imc.org). The subset represents those fields necessary to provide the relevant information about an Event entry without compromising platform portability.

The Event class has many different field IDs that it can support. However, each individual Event object supports only fields valid for its associated list. Its EventList restricts what fields in a Event are retained. This reflects that some native Event databases do not support all of the fields available in a Event element. The methods PIMList.isSupportedField(int) and PIMList.getSupportedTypes(int) can be used to determine if a particular Event field is supported by a EventList and therefore persisted when the Event is committed to its list. Attempts to set or get data based on field IDs not supported in the Event's EventList result in a PIMException.

Data

An event contains three types of data:

Named fields are items that are referenced by the explicit field names defined in this class. Named fields appear only once in a single Event entry. The data items for fields are only retrieved and set by the get/set methods corresponding to the type of the data associated with the named field (e.g. PIMElement.getString(int) and PIMElement.setString(int, String) are used for Event.NOTE since a String value is associated with notes).

Extended fields are fields that does not have a specific field explicitly predefined in the API, but do have field ids assigned by the event list. These fields are implementation dependent and can vary. Users can find out a field id is is extended field through the method PIMList.isExtendedField(int). Users can also find out the data type for the field (PIMElement.getFieldDataType(int)) and the human readable label for the field (PIMElement.getFieldLabel(int)). Extended fields use the same get and set methods as named fields.

Categories are string items. There is no limit to the number of categories that an Event can be associated with.

Table: Named Fields

Field IDs Type of Data Associated with Field
LOCATION, NOTE, SUMMARY, UID PIMElement.STRING
ALARM, END, REVISION, START PIMElement.DATE

Required Field Support

START is the only field that is required to be supported in an Event and its List. All other fields may or may not be required by the list. Support for all fields can be determined by the method PIMList.isSupportedField(int).
  • Repeat Patterns:
  • Inherited Method Behavior

    Examples

      EventList events = null;
      try {
          events = PIM.openEventList(PIM.READ_WRITE);
      } catch (PIMException e) {
          // An error occured
          return;
      }
      
      Event event = events.createEvent();
      Date aDate = new Date(); 
      event.setString(Event.SUMMARY, "Meeting with John");
      event.setDate(Event.START, aDate.getTime());
      event.setDate(Event.END, aDate.getTime());
      event.setDate(Event.ALARM, aDate.getTime() - 60000); 
      event.setString(Event.NOTE, "I phoned on Monday to book this meeting");
      // Add a category for this Event
      event.addToCategory("Work");
      try {
          event.commit();
      } catch (PIMException e) {
          // An error occured
      }
      try {
          events.close();
      } catch (PIMException e) {
      }
     

    Since:
    PDAP 1.0
    See Also:
    http://www.imc.org/pdi/pdiproddev.html, EventList

    Field Summary
    static int ALARM
              Field ID specifying the date and time for an Alarm for this Event.
    static int END
              Field ID specifying the non-inclusive date and time a single Event ends.
    static int LOCATION
              Field ID identifying the venue for this Event.
    static int NOTE
              A String specifying a more complete description than the SUMMARY for this Event.
    static int REVISION
              Field ID specifying the last modification date and time of an Event element.
    static int START
              Field ID specifying the inclusive date and time a single Event starts.
    static int SUMMARY
              Field ID specifying the summary or subject for this Event.
    static int UID
              Field ID specifying a unique ID for a Event.
     
    Fields inherited from interface javax.microedition.pim.PIMElement
    BINARY, DATE, INT, STRING, TYPED_STRING
     
    Method Summary
     EventRepeat getRepeat()
              Retrieves a EventRepeat object specifying how often and when this event occurs.
     void setRepeat(EventRepeat value)
              Sets the EventRepeat specifying how often and when this event occurs.
     
    Methods inherited from interface javax.microedition.pim.PIMElement
    addToCategory, commit, fromSerialFormat, getBinary, getCategories, getDate, getFieldDataType, getFieldLabel, getFields, getInt, getPIMList, getString, getTypedString, isModified, maxCategories, removeFromCategory, setBinary, setDate, setInt, setString, setTypedString, supportedSerialVersions, toSerialFormat, toSerialFormat
     

    Field Detail

    START

    public static final int START
    Field ID specifying the inclusive date and time a single Event starts. If START and END are the same it is an all day event.

    Value 1 is assigned to START.


    END

    public static final int END
    Field ID specifying the non-inclusive date and time a single Event ends. If START and END are the same it is an all day event.

    Value 2 is assigned to END.


    ALARM

    public static final int ALARM
    Field ID specifying the date and time for an Alarm for this Event.

    Value 3 is assigned to ALARM.


    SUMMARY

    public static final int SUMMARY
    Field ID specifying the summary or subject for this Event. For example:
    "Meeting with John"

    Value 4 is assigned to SUMMARY.


    LOCATION

    public static final int LOCATION
    Field ID identifying the venue for this Event. This is a string value. For example:
    "Conference Room - F123, Bldg. 002"

    Value 5 is assigned to LOCATION.


    NOTE

    public static final int NOTE
    A String specifying a more complete description than the SUMMARY for this Event. For example:
    "I phoned John on Friday to book this meeting, he better show"

    Value 6 is assigned to NOTE.


    UID

    public static final int UID
    Field ID specifying a unique ID for a Event. This field can be used to check for identity. This is a read only attribute. The UID is valid only after the Event is added to an Event list and is valid for the persistent life of the Event. Once the Event is deleted from the list, the UID may be reused for other Events. getString(UID) returns null before the event object is added to a list.

    Value 7 is assigned to UID.


    REVISION

    public static final int REVISION
    Field ID specifying the last modification date and time of an Event element.
    This field cannot be set through the API (i.e. is a read-only field). This field is set automatically on adds, imports, and updates of an Event.

    Value 8 is assigned to REVISION.

    Method Detail

    getRepeat

    public EventRepeat getRepeat()
    Retrieves a EventRepeat object specifying how often and when this event occurs.
    Returns:
    the EventRepeat describing how often this Event occurs or null if a EventRepeat has not been set.

    setRepeat

    public void setRepeat(EventRepeat value)
    Sets the EventRepeat specifying how often and when this event occurs.
    Parameters:
    value - An EventRepeat describing how often this Event occurs or null to clear any EventRepeat.

    PDAP 1.0 Spec, Rev. 0.16