javax.microedition.pim
Interface ToDo

All Superinterfaces:

PIMItem

All Known Subinterfaces:

BlackBerryToDo

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 an UnsupportedFieldException being thrown.

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 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( ToDo.SUMMARY ) )
     todo.addString( ToDo.SUMMARY, PIMItem.ATTR_NONE,
             "Buy going away present for Judy" );
 if( todos.isSupportedField( ToDo.DUE ) )
     todo.addDate( ToDo.DUE, PIMItem.ATTR_NONE, new Date().getTime() );
 if( todos.isSupportedField( ToDo.NOTE ) )
     todo.addString( ToDo.NOTE, PIMItem.ATTR_NONE,
             "Judy really likes stained glass and expensive pens" );
 if( todos.isSupportedField( ToDo.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 ) {
 }
 

RIM Implementation Notes

The RIM extension fields and attributes for Events are all defined in BlackBerryEvent. Any instance of Event that is retrieved from a BlackBerryEventList will be an instance of BlackBerryEvent and will support all RIM extension fields and attributes defined therein. Casting such a Event to a BlackBerryEvent is possible if use of any RIM extension methods defined therein is desired.

Table: RIM Extended Fields

Fields	Type of Data Associated with Field	Valid Field Values
STATUS (PIMItem.EXTENDED_FIELD_MIN_VALUE + 9)	PIMItem.INT	STATUS_NOT_STARTED = 0 STATUS_IN_PROGRESS = 1 STATUS_COMPLETED = 2 STATUS_WAITING = 3 STATUS_DEFERRED = 4
REMINDER (20000927)	PIMItem.DATE	Any date

The PDA Profile specification (JSR-75) for the J2ME(TM) Platform

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

See Also:

ToDoList, BlackBerryToDo, Internet Mail Consortium PDI

Since:

BlackBerry API 4.0.0, PIM 1.0

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 Field storing the date a ToDo is due.
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

Method Summary

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

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 ToDo.CLASS_PRIVATE, ToDo.CLASS_PUBLIC, or ToDo.CLASS_CONFIDENTIAL.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

CLASS_CONFIDENTIAL

static final int CLASS_CONFIDENTIAL

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

See Also:

ToDo.CLASS, Constant Field Values

Since:

BlackBerry API 4.0.0

CLASS_PRIVATE

static final int CLASS_PRIVATE

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

See Also:

ToDo.CLASS, Constant Field Values

Since:

BlackBerry API 4.0.0

CLASS_PUBLIC

static final int CLASS_PUBLIC

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

See Also:

ToDo.CLASS, Constant Field Values

Since:

BlackBerry API 4.0.0

COMPLETED

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

Since:

BlackBerry API 4.0.0

COMPLETION_DATE

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 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

Since:

BlackBerry API 4.0.0

DUE

static final int DUE

Field storing the date a ToDo is due. The data for this field is expressed in the same long value format as 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

Since:

BlackBerry API 4.0.0

NOTE

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

Since:

BlackBerry API 4.0.0

PRIORITY

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.

RIM Implementation Note: The BlackBerry Tasks application only supports 3 different priorities: Normal, Low, and High. The range of priorities supported by the PRIORITY field has been mapped to these native priorities as identified in the table below. As a result, setting a priority in the range 0-9 will actually set one of only 3 priorities, causing getInt() to potentially return a different value than was specified to addInt() or setInt(); the value returned from getInt() will, however, map to the same native priority as the one specified to addInt()/setInt().

PRIORITY Specified to setInt()/addInt()	PRIORITY returned from getInt()	PRIORITY in the Tasks Application
0, 4, 5, 6	5	Normal
1, 2, 3	1	High
7, 8, 9	9	Low

If a new ToDo is created with its PRIORITY field unset then the "Normal" priority will be assigned when it is committed.

See Also:

Constant Field Values

Since:

BlackBerry API 4.0.0

REVISION

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 field 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 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

Since:

BlackBerry API 4.0.0

SUMMARY

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

Since:

BlackBerry API 4.0.0

UID

static final int UID

Field specifying a unique ID for a ToDo. This field can be used to check for identity using String.equals(Object). 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; this.countValues(ToDo.UID) returns 0 (zero) before a newly created ToDo object is committed to its list. The value 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

Since:

BlackBerry API 4.0.0