|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
public 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.
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 |
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.
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 occurred
}
try {
events.close();
} catch( PIMException e ) {
}
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 occurred
}
try {
events.close();
} catch( PIMException e ) {
}
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.
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 |
|---|
static final int ALARM
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).
static final int CLASS
INT type, and can be one
of the values Event.CLASS_PRIVATE, Event.CLASS_PUBLIC, or
Event.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.
static final int CLASS_CONFIDENTIAL
Event.CLASS,
Constant Field Valuesstatic final int CLASS_PRIVATE
Event.CLASS,
Constant Field Valuesstatic final int CLASS_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.
Event.CLASS,
Constant Field Valuesstatic final int END
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.
Event.START,
Constant Field Valuesstatic final int LOCATION
STRING value. For example: "Conference Room - F123, Bldg.
002"
static final int NOTE
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"
static final int REVISION
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.
static final int START
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.
Event.END,
Constant Field Valuesstatic final int SUMMARY
STRING type. For example: "Meeting with John"
static final int UID
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.
| Method Detail |
|---|
RepeatRule getRepeat()
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.
RepeatRule describing how often this
Event occurs or null if a
RepeatRule has not been set.Event.setRepeat(RepeatRule)void setRepeat(RepeatRule value)
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.
value - A RepeatRule describing how often this
Event occurs or null to
clear any RepeatRule.Event.getRepeat()
|
|||||||||
| PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
| SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD | ||||||||
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal