javax.microedition.pim
Interface EventList

All Superinterfaces:
PIMList
All Known Subinterfaces:
BlackBerryEventList

public interface EventList
extends PIMList

Represents an Event list containing Event items.

An Event List is responsible for determining which of the fields from an Event are retained when an Event is persisted into the List. An Event List does not have to retain all of the fields in an Event when the Event is persisted into the List. See the Event interface for a description of the fields available for a specific Event. The fields that are supported by a particular Event List can be queried through the method PIMList.isSupportedField(int). If a field ID that is not in the Event interface is provided as the parameter to the PIMList.isSupportedField(int) method, a IllegalArgumentException is thrown.

Inherited Method Behavior

An EventList only accepts objects implementing the Event interface as a parameter to PIMList.items(PIMItem). A IllegalArgumentException is thrown by this method if the input parameter does not implement the Event interface.

Enumerations returned by PIMList.items(), PIMList.items(PIMItem), and items(int, long, long, boolean) contain only objects implementing an Event interface.

RIM Implementation Notes

The RIM extension functionality for Event Lists are defined in BlackBerryEventList. Any instance of EventList that is retrieved from PIM.openPIMList() when specified pimListType==PIM.EVENT_LIST will be an instance of BlackBerryEventList and can be successfully casted to BlackBerryEventList, if desired, in order to use the RIM extension functionality. When a Event object is created by or retrieved from a BlackBerryEventList then it will necessarily be an instance of BlackBerryEvent and will support all RIM extension fields and attributes defined therein.

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:
Event, BlackBerryEventList

Field Summary
static int ENDING
          Constant representing a search type for Events based on the event occurrence's specific end date/time.
static int OCCURRING
          Constant representing a search type for Events based on any occurrence of an event during a time period.
static int STARTING
          Constant representing a search type for Events based on the event occurrence's specific start date/time.
 
Fields inherited from interface javax.microedition.pim.PIMList
UNCATEGORIZED
 
Method Summary
 Event createEvent()
          Factory method to create an Event for this event list.
 int[] getSupportedRepeatRuleFields(int frequency)
          Returns the Repeat Rule fields that are settable by the class user and supported by this EventList for the provided Repeat Rule frequency.
 Event importEvent(Event event)
          Imports the given Event into this list by making a new Event for the list and filling its information with as much information as it can from the provided Event.
 Enumeration items(int searchType, long startDate, long endDate, boolean initialEventOnly)
          Returns an enumeration of all the Events in this list where at least one of the Event's occurrences falls in the specified range from startDate to endDate, inclusive.
 void removeEvent(Event event)
          Removes an Event from the list.
 
Methods inherited from interface javax.microedition.pim.PIMList
addCategory, close, deleteCategory, getArrayElementLabel, getAttributeLabel, getCategories, getFieldDataType, getFieldLabel, getName, getSupportedArrayElements, getSupportedAttributes, getSupportedFields, isCategory, isSupportedArrayElement, isSupportedAttribute, isSupportedField, items, items, items, itemsByCategory, maxCategories, maxValues, renameCategory, stringArraySize
 

Field Detail

ENDING

public static final int ENDING
Constant representing a search type for Events based on the event occurrence's specific end date/time.
Since:
JDE 4.0.0

OCCURRING

public static final int OCCURRING
Constant representing a search type for Events based on any occurrence of an event during a time period.
Since:
JDE 4.0.0

STARTING

public static final int STARTING
Constant representing a search type for Events based on the event occurrence's specific start date/time.
Since:
JDE 4.0.0
Method Detail

createEvent

public Event createEvent()
Factory method to create an Event for this event list. The Event is empty upon creation with none of its fields containing any data (i.e. a call to the method Event.getFields() returns an array of zero length). Even though it is initially empty, the Event is capable of containing data for exactly those fields that this list supports. Note that creation of the Event does not add the Event to the list from which the item was created; a specific call to PIMItem.commit() must be made to commit the item and its data to the list.

RIM Implementation Note: If the runtime type of this Event List is BlackBerryEventList then the returned Event will be an instance of BlackBerryEvent and will support all RIM extension fields and attributes defined in BlackBerryEvent; if desired, the returned Event may be casted to BlackBerryEvent to use any RIM extension methods defined there.

Returns:
a new, empty Event object associated with this list. However, the Event is still not persistent in the list until a call to Event.commit() for the Event is made.
Since:
JDE 4.0.0
See Also:
importEvent(Event), removeEvent(Event)

getSupportedRepeatRuleFields

public int[] getSupportedRepeatRuleFields(int frequency)
Returns the Repeat Rule fields that are settable by the class user and supported by this EventList for the provided Repeat Rule frequency. Repeat Rule frequencies are RepeatRule.YEARLY, RepeatRule.MONTHLY, RepeatRule.WEEKLY, and RepeatRule.DAILY.

The int values in the returned array represent a bitwise combination of Repeat Rule fields that are valid for the given frequency. For example, if MONTHLY was the frequency and this event list supported specifying monthly repeat rules by either the day of the month or by a day in a specific week (e.g. Thursday of the 3rd week in the month), then the returned int array would contain two elements with one value being DAY_IN_MONTH and the other being DAY_IN_WEEK|WEEK_IN_MONTH. All possible field combinations that are valid are returned in the array.

If the given frequency is not supported by this list, a zero-length array is returned. If the frequency is supported but no fields are supported by this list for that frequency, a one item array containing the integer 0 (zero) is returned. In these conditions, any field that has a value set will be ignored by this event list.

Parameters:
frequency - Repeat Rule frequency for which the supported fields are queried.
Returns:
an array of integer values corresponding to the Repeat Rule fields that are supported by this list for the given frequency, as defined above
Throws:
IllegalArgumentException - if frequency is not one of RepeatRule.YEARLY, RepeatRule.MONTHLY, RepeatRule.WEEKLY, or RepeatRule.DAILY.
Since:
JDE 4.0.0
See Also:
RepeatRule

importEvent

public Event importEvent(Event event)
Imports the given Event into this list by making a new Event for the list and filling its information with as much information as it can from the provided Event. If the input Event is already in the list, a new Event is still created with information similar to the input item (but not necessarily identical).

Note that not all data from the input Event may be supported in the new Event due to field restrictions for the list instance. In this case, data fields not supported are not transferred to the new Event object.

Also note that creation of the Event does not add the Event to this list; a specific call to Event.commit() must be made to commit the item and its data to the list.

RIM Implementation Note: If the runtime type of this Event List is BlackBerryEventList then the returned Event will be an instance of BlackBerryEvent and will support all RIM extension fields and attributes defined in BlackBerryEvent; if desired, the returned Event may be casted to BlackBerryEvent to use any RIM extension methods defined there.

Parameters:
event - the Event to import into the list.
Returns:
a newly created Event, as defined above.
Throws:
NullPointerException - if event is null.
Since:
JDE 4.0.0
See Also:
createEvent(), removeEvent(Event)

items

public Enumeration items(int searchType,
                         long startDate,
                         long endDate,
                         boolean initialEventOnly)
                  throws PIMException
Returns an enumeration of all the Events in this list where at least one of the Event's occurrences falls in the specified range from startDate to endDate, inclusive.

The specified "search type" determines the criteria for matching an event occurrence; STARTING searches for events starting between startDate and endDate, ENDING searches for events ending between startDate and endDate, and OCCURRING searches for events that have any part of the event occurring during the period specified by startDate and endDate. The returned Events are sorted in ascending order by the starting date-timestamp of the event's occurrence. An Event is returned in the Enumeration only once if the event occurs more than once during the specified time interval.

Parameters:
searchType - the criteria used to determine which Events are returned; must be one of STARTING, ENDING, or OCCURRING.
startDate - the inclusive start date to begin looking for event occurrences on or after this date, returned in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)
endDate - the inclusive end date to stop looking for events beyond this date, returned in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)
initialEventOnly - if true then only search based on an Event's START and END values and do not calculate repeating occurrences of the event; if false then repeating occurrences of an Event are included during the search.
Returns:
an enumeration of all the Events that match the specified search criteria, as defined above.
Since:
JDE 4.0.0
See Also:
PIMList.items(), PIMList.items(PIMItem), PIMList.items(String), PIMList.itemsByCategory(String)

removeEvent

public void removeEvent(Event event)
                 throws PIMException
Removes an Event from the list. The item must already exist in the list for this method to succeed.
Parameters:
event - the Event to be removed from the list.
Throws:
PIMException - If an error occurs deleting the item or the list is no longer accessible or closed.
NullPointerException - If event is null.
SecurityException - if the application is not given permission to write to the Event list or the list is opened READ_ONLY.
Since:
JDE 4.0.0
See Also:
createEvent(), importEvent(Event)



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.