Represents a single To Do item in a PIM To Do database.
The fields are a subset of the fields in VTODO defined by the
vCalendar specification from the Internet Mail Consortium
(http://www.imc.org). The subset represents those fields necessary to
provide enough information about a ToDo item without compromising platform
portability.
The ToDo class has many different field IDs that it can support. However,
each individual ToDo object supports only fields valid for its associated
list. Its ToDoList restricts what fields in a ToDo are retained. This
reflects that some native ToDo databases do not support all of the fields
available in a ToDo item.
The methods {@link AbstractPIMList#isSupportedField}
and {@link AbstractPIMList#getSupportedFields} can be used to determine if a
particular ToDo field is supported by a ToDoList and therefore persisted when
the ToDo is committed to its list. Attempts to set or get data based on
field IDs not supported in the ToDo's ToDoList result in a
{@link javax.microedition.pim.UnsupportedFieldException}.
Data
Table: Standard Fields
| Fields | Type of Data Associated with Field |
NOTE, SUMMARY, UID |
PIMItem.STRING |
CLASS, PRIORITY |
PIMItem.INT |
COMPLETION_DATE, DUE, REVISION |
PIMItem.DATE |
COMPLETED |
PIMItem.BOOLEAN |
Required Field Support
All ToDo fields may or may not be supported by a particular list. This
is due to the fact that underlying native databases may not support all of
the fields defined in this API. Support for any of the fields can be
determined by the method {@link AbstractPIMList#isSupportedField}.
Native ToDo databases may require some of the fields to have values
assigned to them in order to be persisted. If an application does not
provide values for these fields, default values are provided for the ToDo
by the VM when the ToDo is persisted.
Examples
Explicit Field Use with Field Checking
This first example shows explicit field access in which each field and type
ID is properly checked for support prior to use. This results in code that
is more portable across PIM implementations regardless of which specific
fields are supported on particular PIM list implementations. If one of the
fields is not supported by the list, the field is not set in the ToDo.
ToDoList todos = null;
try {
todos = (ToDoList) PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
} catch (PIMException e) {
// An error occurred
return;
}
ToDo todo = todos.createToDo();
if (todos.isSupportedField(Event.SUMMARY))
todo.addString(ToDo.SUMMARY, PIMItem.ATTR_NONE,
"Buy going away present for Judy");
if (todos.isSupportedField(Event.DUE))
todo.addDate(ToDo.DUE, PIMItem.ATTR_NONE, new Date().getTime());
if (todos.isSupportedField(Event.NOTE))
todo.addString(ToDo.NOTE, PIMItem.ATTR_NONE,
"Judy really likes stained glass and expensive pens");
if (todos.isSupportedField(Event.PRIORITY))
todo.addInt(ToDo.PRIORITY, PIMItem.ATTR_NONE, 2);
if (todos.maxCategories() != 0 && todos.isCategory("Work"))
todo.addToCategory("Work");
}
try {
todo.commit();
} catch (PIMException e) {
// An error occured
}
try {
todos.close();
} catch (PIMException e) {
}
Explicit Field Use with Exception Handling
This second example also shows explicit field access that properly handles
optionally supported fields by use of a try catch block with
UnsupportedFieldException. In this case, the setting of the
whole ToDo is rejected if any of the fields are not supported in the
particular list implementation.
ToDoList todos = null;
try {
todos = (ToDoList) PIM.getInstance().openPIMList(PIM.TODO_LIST,
PIM.READ_WRITE);
} catch (PIMException e) {
// An error occurred
return;
}
ToDo todo = todos.createToDo();
try {
todo.addString(ToDo.SUMMARY, PIMItem.ATTR_NONE,
"Buy going away present for Judy");
todo.addDate(ToDo.DUE, PIMItem.ATTR_NONE, new Date().getTime());
todo.addString(ToDo.NOTE, PIMItem.ATTR_NONE,
"Judy really likes stained glass and expensive pens");
todo.addInt(ToDo.PRIORITY, PIMItem.ATTR_NONE, 2);
todo.addToCategory("Work");
} catch (UnsupportedFieldException e) {
// In this case, we choose not to save the ToDo at all if any of the
// fields are not supported on this platform.
System.out.println("Todo not saved");
return;
}
try {
todo.commit();
} catch (PIMException e) {
// An error occured
}
try {
todos.close();
} catch (PIMException e) {
}
|
