javax.microedition.pim
Interface Event

All Superinterfaces:
PIMItem
All Known Subinterfaces:
BlackBerryEvent

public interface Event
extends PIMItem

Represents an Event entry in a PIM Event database.

While the Event object contains support for many different fields, the fields supported by a given instance of an Event object are defined in the EventList object associated with the event. The EventList restricts which fields are retained by an event database. If an EventList encounters an Event object that contains unsupported fields, those fields are dropped.

The method PIMList.isSupportedField(int) is used to determine if a specified field is supported by a list. The method PIMList.getSupportedFields() returns an integer array of all fields supported by a given list.

The fields supported by the Event object define a subset of the fields specified in the vEvent object defined by the vCalendar 1.0 specification from the Internet Mail Consortium (http://www.imc.org).

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.

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

Working with the Event object

The following examples demonstrate how to use the Event object.

Below, a new Event object is created.


         Event event = events.createEvent();
 

To remove an Event, use the remove method. The following example removes an Event from the calendar.


         events.removeEvent(event);
 

Adding data to an Event

When adding data to an event, you first need to ensure that the field and attribute you are adding are supported by the list. Below, the isSupportedField method is used to return whether or not the specified field is supported.

         if (events.isSupportedField(Event.SUMMARY)) {
                 event.addString(Event.SUMMARY, 0, "Meet with customer");
         }
         if (events.isSupportedField(Event.LOCATION)) {
                 event.addString(Event.LOCATION, 0, "Conference Center");
         }

         long start = System.currentTimeMillis() + 8640000;
         if (events.isSupportedField(Event.START)) {
                 event.addDate(Event.START, 0, start);
         }
         if (events.isSupportedField(Event.END)) {
                 event.addDate(Event.END, 0, start + 72000000);
         }
         if (events.isSupportedField(Event.ALARM)) {
                 event.addInt(Event.ALARM, 0, 900);
         }
 

Above, the start date, location, start, end and alarm are added to the event. Note that each field takes a different data type. An exception will be thrown if an incorrect data type is specified and added to the field. The integer value for the third parameter of the event.addInt() is in seconds, not milliseconds.

Creating a recurring event

You can use the RepeatRule object to create a recurring event by allowing you to specify a recurrence pattern for the event. The RepeatRule allows you to specify the frequency, interval and number of recurrences for each event.

Below, a RepeatRule is created and associated with a new event. The event will repeat on the 28th day of every month.

         RepeatRule recurring = new RepeatRule();
         recurring.setInt(RepeatRule.FREQUENCY, RepeatRule.MONTHLY); 
         recurring.setInt(RepeatRule.DAY_IN_MONTH, 28); 
 
         events = EventList.open(EventList.READ_WRITE);
         Event event = events.createEvent();
         event.setRepeat(recurring);
 

Saving an Event object

The commit method must be used to save the object to a list. Below, the isModified method is called to indicate whether or not the event has been modified. If so, the commit method is invoked and the event is saved.


         if(event.isModified()) {
                event.commit();
         }
 

RIM Implementation Notes

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 more information about this class or about the personal information management (PIM) API, refer to The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

Since:
PDAP 1.0
See Also:
PIMItem, EventList

Field Summary
static int ALARM
          Represents the date and time of the alarm for this event.
static int CLASS
          Field specifying the desired access class for this contact.
static int CLASS_CONFIDENTIAL
          Constant indicating this contact's class of access is confidential.
static int CLASS_PRIVATE
          Constant indicating this contact's class of access is private.
static int CLASS_PUBLIC
          Constant indicating this contact's class of access is public.
static int END
          Represents the end date of an event.
static int LOCATION
          Represents the location of this event (in string format).
static int NOTE
          Represents a note about this event.
static int REVISION
          Represents the date and time that this event's information was last modified.
static int START
          Represents the start date of an event.
static int SUMMARY
          Represents the summary for this event.
static int UID
          Represents an event's unique ID.
 
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()
          Returns 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
Represents the date and time of the alarm for this event.

Since:
JDE 4.0.0

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.

Since:
JDE 4.0.0

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL
Constant indicating this contact's class of access is confidential.
Since:
JDE 4.0.0

CLASS_PRIVATE

public static final int CLASS_PRIVATE
Constant indicating this contact's class of access is private.
Since:
JDE 4.0.0

CLASS_PUBLIC

public static final int CLASS_PUBLIC
Constant indicating this contact's class of access is public.
Since:
JDE 4.0.0

END

public static final int END
Represents the end date of an event.

The end date is inclusive. To indicate an all day event, use the ALLDAY field in the BlackBerryEvent class.

Since:
JDE 4.0.0

LOCATION

public static final int LOCATION
Represents the location of this event (in string format).

Since:
JDE 4.0.0

NOTE

public static final int NOTE
Represents a note about this event.

The note field contains further details about the event.

Since:
JDE 4.0.0

REVISION

public static final int REVISION
Represents the date and time that this event's information was last modified.

Since:
JDE 4.0.0

START

public static final int START
Represents the start date of an event.

The start date is inclusive. To indicate an all day event, use the ALLDAY field in the BlackBerryEvent class.

Since:
JDE 4.0.0

SUMMARY

public static final int SUMMARY
Represents the summary for this event.

The summary contains information, such as a title, or details, about this event.

Since:
JDE 4.0.0

UID

public static final int UID
Represents an event's unique ID.

The unique ID field is valid only if the event has been added to an EventList atleast once in the past. If the Event has not yet been added to a list, the UID returns Null.

Since:
JDE 4.0.0
Method Detail

getRepeat

public RepeatRule getRepeat()
Returns a RepeatRule object specifying how often and when this event occurs.

Returns:
The RepeatRule object describing how often this Event occurs or null if a RepeatRule has not been set.
Since:
JDE 4.0.0
See Also:
setRepeat(javax.microedition.pim.RepeatRule)

setRepeat

public void setRepeat(RepeatRule value)
Sets the RepeatRule specifying how often and when this event occurs.

Parameters:
value - A RepeatRule object describing how often this Event occurs or null to clear any RepeatRule.
Since:
JDE 4.0.0
See Also:
getRepeat()



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.