javax.microedition.pim
Interface ToDo

All Superinterfaces:

PIMItem

public interface ToDo

extends PIMItem

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 PIMList.isSupportedField(int) and PIMList.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 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 besupported 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 PIMList.isSupportedField(int).

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) {
  }
 

Since:

PIM 1.0

See Also:

Internet Mail Consortium PDI, ToDoList

Field Summary

static int	CLASS Field specifying the desired access class for this contact.
static int	CLASS_CONFIDENTIAL Constant indicating this todo's class of access is confidential.
static int	CLASS_PRIVATE Constant indicating this todo's class of access is private.
static int	CLASS_PUBLIC Constant indicating this todo's class of access is public.
static int	COMPLETED Field ID indicating a ToDo has been completed.
static int	COMPLETION_DATE Field ID indicating a ToDo has been completed on the date indicated by this field.
static int	DUE The date a ToDo is due.The data for this field is expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
static int	NOTE Field specifying a more complete description than the SUMMARY for this ToDo.
static int	PRIORITY Field specifying the priority of this ToDo.
static int	REVISION Field specifying the last modification date and time of a ToDo item.
static int	SUMMARY Field specifying the summary or subject for this ToDo.
static int	UID Field specifying a unique ID for a ToDo.

Fields inherited from interface javax.microedition.pim.PIMItem

ATTR_NONE, BINARY, BOOLEAN, DATE, EXTENDED_ATTRIBUTE_MIN_VALUE, EXTENDED_FIELD_MIN_VALUE, INT, STRING, STRING_ARRAY

Methods inherited from interface javax.microedition.pim.PIMItem

addBinary, addBoolean, addDate, addInt, addString, addStringArray, addToCategory, commit, countValues, getAttributes, getBinary, getBoolean, getCategories, getDate, getFields, getInt, getPIMList, getString, getStringArray, isModified, maxCategories, removeFromCategory, removeValue, setBinary, setBoolean, setDate, setInt, setString, setStringArray

Field Detail

CLASS

public static final int CLASS

Field specifying the desired access class for this contact. Data associated with this field is of int type, and can be one of the values CLASS_PRIVATE, CLASS_PUBLIC, or CLASS_CONFIDENTIAL.

See Also:

Constant Field Values

COMPLETED

public static final int COMPLETED

Field ID indicating a ToDo has been completed. Data for this field is of boolean type.

See Also:

Constant Field Values

COMPLETION_DATE

public static final int COMPLETION_DATE

Field ID indicating a ToDo has been completed on the date indicated by this field. The data for this field is expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Note that the value provided may be rounded-down by an implementation due to platform restrictions. For example, should a native ToDo database only support todo date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.

See Also:

Constant Field Values

DUE

public static final int DUE

The date a ToDo is due.The data for this field is expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Note that the value provided may be rounded-down by an implementation due to platform restrictions. For example, should a native ToDo database only support todo date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.

See Also:

Constant Field Values

NOTE

public static final int NOTE

Field specifying a more complete description than the SUMMARY for this ToDo. Data for this field is of string type. For example:
"Judy really likes stained glass and expensive pens"

See Also:

Constant Field Values

PRIORITY

public static final int PRIORITY

Field specifying the priority of this ToDo. The priority is a value from zero to nine. Zero specifies an undefined priority, one specifies the highest priority and nine the lowest priority. It is not guaranteed that this value remains unchanged after setting the value and/or persistence of the ToDo item due to underlying native database priority support and mappings to the native priority values. Data for this field is of int type.

See Also:

Constant Field Values

REVISION

public static final int REVISION

Field specifying the last modification date and time of a ToDo item. If the ToDo has ever been committed to a ToDoList, then this attribute becomes read only. This field is set automatically on imports and commits of a ToDo. Data for this field is expressed in the same long value format as java.util.Date, which is milliseconds since the epoch (00:00:00 GMT, January 1, 1970).

Note that the value provided may be rounded-down by an implementation due to platform restrictions. For example, should a native ToDo database only support todo date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.

See Also:

Constant Field Values

SUMMARY

public static final int SUMMARY

Field specifying the summary or subject for this ToDo. Data for this field is of string type. For example:
"Buy going away present for Judy"

See Also:

Constant Field Values

UID

public static final int UID

Field specifying a unique ID for a ToDo. This field can be used to check for identity using String.equals. UID is read only if the ToDo has been committed to a ToDoList at least once in its lifetime. The UID is not set if the ToDo has never been committed to a ToDoList; countValues(UID) returns 0 before a newly created ToDo object is committed to its list. The attribute is valid for the persistent life of the ToDo and may be reused by the platform once this particular ToDo is deleted. Data for this field is of string type.

See Also:

Constant Field Values

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL

Constant indicating this todo's class of access is confidential.

See Also:

Constant Field Values

CLASS_PRIVATE

public static final int CLASS_PRIVATE

Constant indicating this todo's class of access is private.

See Also:

Constant Field Values

CLASS_PUBLIC

public static final int CLASS_PUBLIC

Constant indicating this todo's class of access is public.

See Also:

Constant Field Values