javax.microedition.pim
Interface EventList

All Superinterfaces:
PIMList

public interface EventList
extends PIMList

Represents an EventList. An EventList contains PIM Event objects.

The EventList object defines that fields that are valid for a given Event. If an Event that contains fields that are not supported, is added to an EventList, the fields will be discarded. The PIMList.isSupportedField(int) is invoked to determine if a field (as specified by the integer argument) is supported by an EventList. Similarly, the PIMList.getSupportedAttributes(int) method is invoked to return an integer array representing all fields supported by the list.

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

Since:
JDE 4.0.0
See Also:
PIMItem, Event

Field Summary
static int ENDING
          Represents a search type for Events based on the occurrence's specific end date/time.
static int OCCURRING
          Represents a search type for Events based on any occurrence of an event during a given period of time.
static int STARTING
          Represents 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()
          Creates a new Event instance.
 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 element)
          Imports an Event into the list using a given, predefined Event object.
 Enumeration items(int searchType, long startDate, long endDate, boolean initialEventOnly)
          Returns an enumeration of all events in the EventList ordered by start date inclusive.
 void removeEvent(Event element)
          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
Represents a search type for Events based on the occurrence's specific end date/time.
Since:
JDE 4.0.0

OCCURRING

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

STARTING

public static final int STARTING
Represents 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()
Creates a new Event instance.

The new Event object is created initially empty and contains fields for all attributes that are supported by the list.

The Event object is not added to the EventList upon creation. The method PIMItem.commit() must be invoked in order to add the Event to the list.

Returns:
The new event object.
Since:
JDE 4.0.0

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:
Repeat Rule frequency for which the supported fields are queried.
Throws:
IllegalArgumentException - if frequncy is not RepeatRule.YEARLY, RepeatRule.MONTHLY, RepeatRule.WEEKLY, or RepeatRule.DAILY.
Since:
JDE 4.0.0

importEvent

public Event importEvent(Event element)
Imports an Event into the list using a given, predefined Event object.

The Event is created using as much of the existing information as possible. If a field in the existing Event object is not supported by the EventList, the field is not included in the Event. If the specified Event is already in the list, a new Event is created with similar information.

The Event object is not added to the EventList upon creation. The method PIMItem.commit() must be invoked in order to add the Event to the list.

Parameters:
element - The Event object to import data from.
Returns:
The Event object to add to the list.
Since:
JDE 4.0.0

items

public Enumeration items(int searchType,
                         long startDate,
                         long endDate,
                         boolean initialEventOnly)
                  throws PIMException
Returns an enumeration of all events in the EventList ordered by start date inclusive.

Parameters:
searchtype - Determines which events are returned. One of STARTING, ENDING, OCCURRING.
startDate - The start date of the events to return (in long MS form).
endDate - The end date of the events to return (in long MS form).
initialEventOnly - true indicates that the search will include only the initial event. false indicates that recurrences of the event will also be calculated.
Returns:
An enumeration containing the events from start date to end date.
Throws:
PIMException - Thrown if an error occurs, the list is no longer accesible, or the operation is unsupported.
Since:
JDE 4.0.0

removeEvent

public void removeEvent(Event element)
                 throws PIMException
Removes an Event from the list.

Parameters:
element - The Event to be removed from the list.
Throws:
PIMException - Thrown if an error occurs, or if the Event cannot be found in the list.
Since:
JDE 4.0.0



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