PDAP Public Review Draft

javax.microedition.pim
Interface EventList

All Superinterfaces:
PIMList

public interface EventList
extends PIMList

Represents an Event list containing Event elements.

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.elements(PIMElement)). A java.lang.IllegalArgumentException is thrown by this method if the input parameter does not implement the Event interface.

Enumerations returned by PIMList.elements(), PIMList.elements(PIMElement), and elements(long, long) contain only objects implementing an Event interface.

Since:
PDAP 1.0
See Also:
Event

Method Summary
 Event createEvent()
          Factory method to create an Event for this event list.
 Enumeration elements(long startDate, long endDate)
          Return an Enumeration of all Events in the list ranging from startDate to endDate inclusive.
 Event importEvent(Event element)
          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.
 void removeEvent(Event element)
          Removes a specific Event from the list.
 
Methods inherited from interface javax.microedition.pim.PIMList
addCategory, close, deleteCategory, elements, elements, getCategories, getSupportedFields, getSupportedTypes, isExtendedField, isSupportedField, maxCategories
 

Method Detail

createEvent

public Event createEvent()
                  throws PIMException
Factory method to create an Event for this event list. Note that creation of the Event does not add the Event to the list from which the element was created; a specific call to PIMElement.commit() must be made to commit the element and its data to the list.
Throws:
PIMException - if the element cannot be created or the list is no longer accessible or closed.

importEvent

public Event importEvent(Event element)
                  throws PIMException
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 element (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.
Parameters:
element - the Event to import into the list.
Returns:
a newly created Event after it has been persisted to the database.
Throws:
PIMException - If an error occurs or the list is no longer accessible or closed.
java.lang.IllegalArgumentException - If the input Event is null.
java.lang.SecurityException - if the application is not given permission to write to the list.

removeEvent

public void removeEvent(Event element)
                 throws PIMException
Removes a specific Event from the list. The element must already exist in the list for this method to succeed.
Parameters:
element - 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.IllegalArgumentException - If the Event is null.
java.lang.SecurityException - if the application is not given permission to write to the Contact list.

elements

public Enumeration elements(long startDate,
                            long endDate)
                     throws PIMException
Return an Enumeration of all Events in the list ranging from startDate to endDate inclusive. The order is sequential by date.
Parameters:
inclusive - startDate begin looking for events on this date (in long ms format)
inclusive - endDate stop looking for events beyond this date (in long ms format)
Returns:
an Enumeration of all Events between startDate and endDate.
Throws:
PIMException - If the operation is unsupported, an error occurs, or the list is no longer accessible or closed.

PDAP 1.0 Spec, Rev. 0.16