javax.microedition.pim
Interface Event

All Superinterfaces:
PIMItem
All Known Subinterfaces:
BlackBerryEvent

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

 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 ) { }

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.

The PDA Profile specification (JSR-75) for the J2ME(TM) Platform

For more information about this class or about the personal information management (PIM) API, see The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

Since:
PIM 1.0
See Also:
EventList, BlackBerryEvent, Internet Mail Consortium PDI

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

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.

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.

Since:
JDE 4.0.0

CLASS_CONFIDENTIAL

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

CLASS_PRIVATE

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

CLASS_PUBLIC

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 CLASS for details.

See Also:
CLASS
Since:
JDE 4.0.0

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

See Also:
START
Since:
JDE 4.0.0

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"
Since:
JDE 4.0.0

NOTE

public static final int NOTE
A field specifying a more complete description than the SUMMARY for this Event. Data for this field are STRING values. For example: "I phoned John on Friday to book this meeting, he better show"
Since:
JDE 4.0.0

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

Since:
JDE 4.0.0

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

See Also:
END
Since:
JDE 4.0.0

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"
Since:
JDE 4.0.0

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(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.
Since:
JDE 4.0.0
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(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.
Since:
JDE 4.0.0
See Also:
setRepeat(RepeatRule)

setRepeat

public void setRepeat(RepeatRule value)
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.
Since:
JDE 4.0.0
See Also:
getRepeat()



Copyright 1999-2009 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.