javax.microedition.pim
Interface EventList

All Superinterfaces:

PIMList

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 java.lang.IllegalArgumentException is thrown.

Inherited Method Behavior

An EventList only accepts objects implementing the Event interface as a parameter to PIMList.items(PIMItem)). A java.lang.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.

Since:

PIM 1.0

See Also:

Event

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 item) 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.
java.util.Enumeration	items(int searchType, long startDate, long endDate, boolean initialEventOnly) Return an enumeration of all the Events where at least one of the Event's occurrences falls in the specified range from startDate to endDate inclusive.
void	removeEvent(Event item) Removes a specific 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

STARTING

public static final int STARTING

Constant representing a search type for Events based on the event occurrence's specific start date/time.

See Also:

Constant Field Values

ENDING

public static final int ENDING

Constant representing a search type for Events based on the event occurrence's specific end date/time.

See Also:

Constant Field Values

OCCURRING

public static final int OCCURRING

Constant representing a search type for Events based on any occurrence of an event during a time period.

See Also:

Constant Field Values

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.

Returns:

a new, empty Event object associated with this list. However, the Event is still not persistent in the list until a call to PIMItem.commit() for the Event is made.

importEvent

public Event importEvent(Event item)

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 PIMItem.commit() must be made to commit the item and its data to the list.

Parameters:

item - the Event to import into the list.

Returns:

a newly created Event.

Throws:

java.lang.NullPointerException - If the item is null.

removeEvent

public void removeEvent(Event item)
                 throws PIMException

Removes a specific Event from the list. The item must already exist in the list for this method to succeed.

Parameters:

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

java.lang.NullPointerException - If item is null.

java.lang.SecurityException - if the application is not given permission to write to the Event list or the list is opened READ_ONLY.

items

public java.util.Enumeration items(int searchType,
                                   long startDate,
                                   long endDate,
                                   boolean initialEventOnly)
                            throws PIMException

Return an enumeration of all the Events where at least one of the Event's occurrences falls in the specified range from startDate to endDate inclusive. The search type specified 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 an 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 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 stop date to end looking for events beyond this date, returned in milliseconds since the epoch (00:00:00 GMT, January 1, 1970)

initialEventOnly - true indicates only search based on an Event's START and END values and do not calculate repeating occurrences of the event. False indicates repeating occurrences of an Event are included during the search.

Returns:

an enumeration of all the Events with an occurrence between startDate and endDate

Throws:

java.lang.IllegalArgumentException - if searchType is not STARTING, ENDING, or OCCURRING, or startDate is greater than endDate.

PIMException - If the operation is unsupported, an error occurs, or the list is no longer accessible or closed.

java.lang.SecurityException - if the application is not given permission to read the Event list or the list is opened WRITE_ONLY.

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

Throws:

java.lang.IllegalArgumentException - if frequncy is not RepeatRule.YEARLY, RepeatRule.MONTHLY, RepeatRule.WEEKLY, or RepeatRule.DAILY.

See Also:

RepeatRule