javax.microedition.pim
Interface Event

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 an
Event are retained. This reflects that some native Event
databases do not support all of the fields available in an 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 an
UnsupportedFieldException being thrown.

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.

RIM Implementation Notes

The RIM extension fields and attributes for Events are all defined in
BlackBerryEvent. Any instance of
Event that is retrieved from a
BlackBerryEventList will be an instance
of BlackBerryEvent and will support all RIM extension fields
and attributes defined therein. Casting such a Event to a
BlackBerryEvent is possible if use of any RIM extension
methods defined therein is desired.

Setting the NOTE field to the empty string has the same effect
as removing that value.

The value stored in the END field may be altered slightly when
committed. The field is stored with a granularity of one minute relative to
the START field. For example, suppose START is set to 5:20:15.005
and END is set to 5:30:55.123 of the same day; then after the event is
committed and reloaded getDate(Event.END, 0) will return either 5:30:15.005 or
5:31:15.005, which is an integral number of minutes after the START date.

ALARM

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
re-occurrences of the event, the alarm is calculated by subtracting 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).

RIM Implementation Note: The CLASS field of an
Event explicitly set to CLASS_PUBLIC is identical to it
not being set at all. The implementation considers Events as "public" by
default; therefore, when an Event is committed to this list and the
CLASS field has the value CLASS_PUBLIC then
the field value is discarded and will be unset when reloaded. If the
CLASS field is set to any other value then that value is
saved and will be set when the Event is reloaded.

CLASS_PRIVATE

CLASS_PUBLIC

static final int CLASS_PUBLIC

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

RIM Implementation Note: The CLASS_PUBLIC value in
the CLASS field is treated differently than other values
for that field. See the RIM implementation notes in the documentation for
Event.CLASS for details.

END

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
Date, which is milliseconds since the epoch (00:00:00
GMT, January 1, 1970).

If START and END are the same if 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.

RIM Implementation Note: The END date is
inclusive. An Event can be set as an all day event by setting
the the BOOLEAN field
BlackBerryEvent.ALLDAY to
true. In this case, the START and
END dates are treated differently. See the javadocs for
the ALLDAY constant for details.

REVISION

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 field 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
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.

START

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
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.

RIM Implementation Note: An Event can be set as an all day event
by setting the the BOOLEAN field
BlackBerryEvent.ALLDAY to
true. In this case, the START and
END dates are treated differently. See the javadocs for
the ALLDAY constant for details.

UID

static final int UID

Field specifying a unique ID for an Event. This field can be used to
check for identity using String.equals(Object). The 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;
this.countValues(UID) returns 0 (zero)
before a newly created Event object is committed to its
list. The field 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.

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 Event.setRepeat(RepeatRule) 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

Sets a 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.