javax.microedition.pim
Interface Event

All Superinterfaces:

PIMItem

public interface Event

extends PIMItem

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.

A single event may have multiple occurrences; i.e. the event may be a recurring event that is repeated at specified intervals. Each occurrence of an event is determined by using a RepeatRule to calculate when the event should have additional occurrences, besides the one defined by the Event.START field.

The Event class has many different fields 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 item. The methods PIMList.isSupportedField(int) and PIMList.getSupportedFields() can be used to determine if a particular Event field is supported by an 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 UnsupportedFieldException.

Data

The following table details the explicitly defined fields that may by in an Event. Implementations may extend the field set using extended fields as defined in PIMItem.

Table: Predefined Fields

Fields	Type of Data Associated with Field
LOCATION, NOTE, SUMMARY, UID	PIMItem.STRING
END, REVISION, START	PIMItem.DATE
ALARM, CLASS	PIMItem.INT

Required Field Support

All Event fields may or may not be supported by a particular list. This is due to the fact that underlying native databases may not support all of the fields defined in this API. Support for any of the fields can be determined by the method PIMList.isSupportedField(int).

Native Event databases may require some of the fields to have values assigned to them in order to be persisted. If an application does not provide values for these fields, default values are provided for the Event by the VM when the Event is persisted.

Examples

Explicit Field Use with Field Checking

This first example shows explicit field access in which each field and type ID is properly checked for support prior to use. This results in code that is more portable across PIM implementations regardless of which specific fields are supported on particular PIM list implementations. If one of the fields is not supported by the list, the field is not set in the Event.

 EventList events = null;
 try {
    events = (EventList) PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
 } catch (PIMException e) {
    // An error occurred
    return;
 }
 Event event = events.createEvent();
 if (events.isSupportedField(Event.SUMMARY))
      event.addString(Event.SUMMARY, PIMItem.ATTR_NONE, "Meeting with John");
 if (events.isSupportedField(Event.START))
      event.addDate(Event.START, PIMItem.ATTR_NONE, aDate.getTime());
 if (events.isSupportedField(Event.END))
      event.addDate(Event.END, PIMItem.ATTR_NONE, aDate.getTime());
 if (events.isSupportedField(Event.ALARM))
      event.addInt(Event.ALARM, PIMItem.ATTR_NONE, aDate.getTime() - 60000);
 if (events.isSupportedField(Event.NOTE))
      event.addString(Event.NOTE, PIMItem.ATTR_NONE, "I phoned on Monday to book this meeting");
 if (events.maxCategories() != 0 && events.isCategory("Work"))
      event.addToCategory("Work");
 }
 try {
      event.commit();
 } catch (PIMException e) {
      // An error occured
 }
 try {
      events.close();
 } catch (PIMException e) {
 }
 

Explicit Field Use with Exception Handling

This second example also shows explicit field access that properly handles optionally supported fields by use of a try catch block with UnsupportedFieldException. In this case, the setting of the whole Event is rejected if any of the fields are not supported in the particular list implementation.

  EventList events = null;
  try {
    events = (EventList) PIM.getInstance().openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);
  } catch (PIMException e) {
      // An error occurred
      return;
  }
  Event event = events.createEvent();

  try {
      Date aDate = new Date();
      event.addString(Event.SUMMARY, PIMItem.ATTR_NONE, "Meeting with John");
      event.addDate(Event.START, PIMItem.ATTR_NONE, aDate.getTime());
      event.addDate(Event.END, PIMItem.ATTR_NONE, aDate.getTime());
      event.addDate(Event.ALARM, PIMItem.ATTR_NONE, aDate.getTime() - 60000);
      event.addString(Event.NOTE, PIMItem.ATTR_NONE, "I phoned on Monday to book this meeting");
      event.addToCategory("Work");

  } catch (UnsupportedFieldException e) {
    // In this case, we choose not to save the contact at all if any of the
    // fields are not supported on this platform.
    System.out.println("Event not saved");
    return;
  }

  try {
      event.commit();
  } catch (PIMException e) {
      // An error occured
  }
  try {
      events.close();
  } catch (PIMException e) {
  }
 

Since:

PIM 1.0

See Also:

Internet Mail Consortium PDI, EventList

Field Summary

static int	ALARM Field specifying a relative time for an Alarm for this Event.
static int	CLASS Field specifying the desired access class for this contact.
static int	CLASS_CONFIDENTIAL Constant indicating this event's class of access is confidential.
static int	CLASS_PRIVATE Constant indicating this event's class of access is private.
static int	CLASS_PUBLIC Constant indicating this event's class of access is public.
static int	END Field specifying the non-inclusive date and time a single Event ends.
static int	LOCATION Field 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 specifying the last modification date and time of an Event item.
static int	START Field specifying the inclusive date and time a single Event starts.
static int	SUMMARY Field specifying the summary or subject for this Event.
static int	UID Field specifying a unique ID for an Event.

Fields inherited from interface javax.microedition.pim.PIMItem

ATTR_NONE, BINARY, BOOLEAN, DATE, EXTENDED_ATTRIBUTE_MIN_VALUE, EXTENDED_FIELD_MIN_VALUE, INT, STRING, STRING_ARRAY

Method Summary

RepeatRule	getRepeat() Retrieves a RepeatRule object specifying how often and when this event occurs.
void	setRepeat(RepeatRule value) Sets the RepeatRule specifying how often and when this event occurs.

Methods inherited from interface javax.microedition.pim.PIMItem

addBinary, addBoolean, addDate, addInt, addString, addStringArray, addToCategory, commit, countValues, getAttributes, getBinary, getBoolean, getCategories, getDate, getFields, getInt, getPIMList, getString, getStringArray, isModified, maxCategories, removeFromCategory, removeValue, setBinary, setBoolean, setDate, setInt, setString, setStringArray

Field Detail

ALARM

public static final int ALARM

Field specifying a relative time for an Alarm for this Event. Data for this field is expressed with an int data type. The alarm is expressed in seconds and derived by subtracting the alarm value from every date/time occurrence of this Event. For example, if this field has a value of 600, then the alarm first occurs 600 seconds before the date/time value specified by Event.START. For reoccurrences of the event, the alarm is calculated by substracting the stored value from the date/time of the specific event occurrence.

Note that the value provided may be rounded-down by an implementation due to platform restrictions. For example, should a native Event database only support alarm values with granularity in terms of minutes, then the provided alarm value is rounded down to the nearest minute (e.g. 636 seconds would become 600 seconds).

See Also:

Constant Field Values

CLASS

public static final int CLASS

Field specifying the desired access class for this contact. Data associated with this field is of int type, and can be one of the values CLASS_PRIVATE, CLASS_PUBLIC, or CLASS_CONFIDENTIAL.

See Also:

Constant Field Values

END

public static final int END

Field specifying the non-inclusive date and time a single Event ends. Data for this field is expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

If START and END are the same this event is an all day event. If END is specified but START is not, the event occurs only at the instance specified by END.

Note that the value provided may be rounded-down by an implementation due to platform restrictions. For example, should a native Event database only support event date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.

See Also:

START, Constant Field Values

LOCATION

public static final int LOCATION

Field identifying the venue for this Event. Data for this field is a string value. For example:
"Conference Room - F123, Bldg. 002"

See Also:

Constant Field Values

NOTE

public static final int NOTE

A String specifying a more complete description than the SUMMARY for this Event. Data for this field is a string value. For example:
"I phoned John on Friday to book this meeting, he better show"

See Also:

Constant Field Values

REVISION

public static final int REVISION

Field specifying the last modification date and time of an Event item. If the Event has ever been committed to an EventList, then this attribute becomes read only. This field is set automatically on imports and commits of an Event. The data for this field is expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Note that the value provided may be rounded-down by an implementation due to platform restrictions. For example, should a native Event database only support event date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.

See Also:

Constant Field Values

START

public static final int START

Field specifying the inclusive date and time a single Event starts. The data for this field is expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

If START and END are the same this event is an all day event. If START is specified but END is not, the event occurs only at the instance specified by START.

Note that the value provided may be rounded-down by an implementation due to platform restrictions. For example, should a native Event database only support event date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.

See Also:

END, Constant Field Values

SUMMARY

public static final int SUMMARY

Field specifying the summary or subject for this Event. Data for this field is a string type. For example:
"Meeting with John"

See Also:

Constant Field Values

UID

public static final int UID

Field specifying a unique ID for an Event. This field can be used to check for identity using String.equals. UID is read only if the Event has been committed to an EventList at least once in its lifetime. The UID is not set if the Event has never been committed to an EventList; countValues(UID) returns 0 before a newly created Event object is committed to its list. The attribute is valid for the persistent life of the Event and may be reused by the platform once this particular Event is deleted. The data for this field is of string type.

See Also:

Constant Field Values

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL

Constant indicating this event's class of access is confidential.

See Also:

Constant Field Values

CLASS_PRIVATE

public static final int CLASS_PRIVATE

Constant indicating this event's class of access is private.

See Also:

Constant Field Values

CLASS_PUBLIC

public static final int CLASS_PUBLIC

Constant indicating this event's class of access is public.

See Also:

Constant Field Values

Method Detail

getRepeat

public RepeatRule getRepeat()

Retrieves a RepeatRule object specifying how often and when this event occurs. This method returns a copy of the RepeatRule object associated with the Event by the system. Modifications to the returned object must be saved back to the Event via the setRepeat method if they are to be persisted with the Event.

Returns:

the RepeatRule describing how often this Event occurs or null if a RepeatRule has not been set.

setRepeat

public void setRepeat(RepeatRule value)

Sets the RepeatRule specifying how often and when this event occurs. The RepeatRule parameter is a hint to the system indicating the repeat pattern, but does not have to be strictly enforced in the implementation. The provided RepeatRule object replaces any previously set RepeatRule object for the Event.

Parameters:

value - A RepeatRule describing how often this Event occurs or null to clear any RepeatRule.