PDAP Public Review Draft

javax.microedition.pim
Interface ToDoList

All Superinterfaces:
PIMList

public interface ToDoList
extends PIMList

Represents a ToDo list containing ToDo elements.

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

Inherited Method Behavior

A ToDoList only accepts objects implementing the ToDo 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 ToDo interface.

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

Since:
PDAP 1.0
See Also:
ToDo

Method Summary
 ToDo createToDo()
          Factory method to create a ToDo entry for this ToDo list.
 Enumeration elements(long startDate, long endDate)
          Return an Enumeration of all ToDos in the list ranging from startDate to endDate inclusive.
 PIMElement importToDo(ToDo element)
          Imports the given ToDo into this list by making a new ToDo for the list and filling its information with as much information as it can from the provided ToDo.
 void removeToDo(ToDo element)
          Removes a specific ToDo from the list.
 
Methods inherited from interface javax.microedition.pim.PIMList
addCategory, close, deleteCategory, elements, elements, getCategories, getSupportedFields, getSupportedTypes, isExtendedField, isSupportedField, maxCategories
 

Method Detail

createToDo

public ToDo createToDo()
                throws PIMException
Factory method to create a ToDo entry for this ToDo list. Note that creation of the ToDo does not add the ToDo 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.

importToDo

public PIMElement importToDo(ToDo element)
                      throws PIMException
Imports the given ToDo into this list by making a new ToDo for the list and filling its information with as much information as it can from the provided ToDo. If the input ToDo is already an element of the list, a new ToDo is still created with information similar to the input element (but not necessarily identical). Note that not all data from the input ToDo may be supported in the new ToDo due to field restrictions for the list instance. In this case, data fields not supported are not transferred to the new ToDo object.
Parameters:
element - the ToDo to import into the list.
Returns:
a newly created Element 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 ToDo is null.
java.lang.SecurityException - if the application is not given permission to write to the list.

removeToDo

public void removeToDo(ToDo element)
                throws PIMException
Removes a specific ToDo from the list. The element must already exist in the list for this method to succeed.
Parameters:
element - the ToDo 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 ToDo 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 ToDos in the list ranging from startDate to endDate inclusive. The order is sequential by date.
Parameters:
startDate - begin looking for ToDos on this date (in long ms format)
endDate - stop looking for ToDos beyond this date (in long ms format)
Returns:
an Enumeration of all ToDos between startDate and endDate.
Throws:
PIMException - If the operation is unsupported,an error occurs, or is no longer accessible or closed.

PDAP 1.0 Spec, Rev. 0.16