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

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.

Since:
PIM 1.0
See Also:
ToDoList, BlackBerryToDo, Internet Mail Consortium PDI

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

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.
Since:
JDE 4.0.0

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL
Constant indicating this todo's class of access is confidential.
See Also:
CLASS
Since:
JDE 4.0.0

CLASS_PRIVATE

public static final int CLASS_PRIVATE
Constant indicating this todo's class of access is private.
See Also:
CLASS
Since:
JDE 4.0.0

CLASS_PUBLIC

public static final int CLASS_PUBLIC
Constant indicating this todo's class of access is public.
See Also:
CLASS
Since:
JDE 4.0.0

COMPLETED

public static final int COMPLETED
Field ID indicating a ToDo has been completed. Data for this field is of BOOLEAN type.
Since:
JDE 4.0.0

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

Since:
JDE 4.0.0

DUE

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

Since:
JDE 4.0.0

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"
Since:
JDE 4.0.0

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.
Since:
JDE 4.0.0

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

Since:
JDE 4.0.0

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"
Since:
JDE 4.0.0

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(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.
Since:
JDE 4.0.0



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