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 {@link javax.microedition.pim.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
{@link AbstractPIMList#isSupportedField}
and {@link AbstractPIMList#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
{@link javax.microedition.pim.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 {@link AbstractPIMList#isSupportedField}.
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) {
}
|
