001: /*
002: *
003: *
004: * Portions Copyright 2000-2007 Sun Microsystems, Inc. All Rights
005: * Reserved. Use is subject to license terms.
006: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
007: *
008: * This program is free software; you can redistribute it and/or
009: * modify it under the terms of the GNU General Public License version
010: * 2 only, as published by the Free Software Foundation.
011: *
012: * This program is distributed in the hope that it will be useful, but
013: * WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * General Public License version 2 for more details (a copy is
016: * included at /legal/license.txt).
017: *
018: * You should have received a copy of the GNU General Public License
019: * version 2 along with this work; if not, write to the Free Software
020: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
021: * 02110-1301 USA
022: *
023: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
024: * Clara, CA 95054 or visit www.sun.com if you need additional
025: * information or have any questions.
026: */
027: /*
028: * Copyright (C) 2002-2003 PalmSource, Inc. All Rights Reserved.
029: */
030:
031: package com.sun.kvem.midp.pim;
032:
033: /**
034: * Represents a single To Do item in a PIM To Do database.
035: * The fields are a subset of the fields in <code>VTODO</code> defined by the
036: * vCalendar specification from the Internet Mail Consortium
037: * (http://www.imc.org). The subset represents those fields necessary to
038: * provide enough information about a ToDo item without compromising platform
039: * portability.
040: * <P>The ToDo class has many different field IDs that it can support. However,
041: * each individual ToDo object supports only fields valid for its associated
042: * list. Its ToDoList restricts what fields in a ToDo are retained. This
043: * reflects that some native ToDo databases do not support all of the fields
044: * available in a ToDo item.
045: * The methods {@link AbstractPIMList#isSupportedField}
046: * and {@link AbstractPIMList#getSupportedFields} can be used to determine if a
047: * particular ToDo field is supported by a ToDoList and therefore persisted when
048: * the ToDo is committed to its list. Attempts to set or get data based on
049: * field IDs not supported in the ToDo's ToDoList result in a
050: * {@link javax.microedition.pim.UnsupportedFieldException}.
051: * </P>
052: * <H3>Data</H3>
053: * <P>
054: * </P>
055: * <h4>Table: Standard Fields</h4>
056: * <table border=1>
057: * <TR>
058: * <th> Fields </th><th> Type of Data Associated with Field </th>
059: * </tr>
060: * <tr><td><code>NOTE, SUMMARY, UID</code></td>
061: * <td><code>PIMItem.STRING</code></td>
062: * </tr>
063: * <tr><td><code>CLASS, PRIORITY</code></td>
064: * <td><code>PIMItem.INT</code></td>
065: * </tr>
066: * <tr><td><code>COMPLETION_DATE, DUE, REVISION </code></td>
067: * <td><code>PIMItem.DATE</code></td>
068: * </tr>
069: * <tr><td><code>COMPLETED</code></td>
070: * <td><code>PIMItem.BOOLEAN</code></td>
071: * </tr>
072: * </table>
073: *
074: * <h3>Required Field Support</h3>
075: * <P>All ToDo fields may or may not be supported by a particular list. This
076: * is due to the fact that underlying native databases may not support all of
077: * the fields defined in this API. Support for any of the fields can be
078: * determined by the method {@link AbstractPIMList#isSupportedField}.
079: * </p><P>
080: * Native ToDo databases may require some of the fields to have values
081: * assigned to them in order to be persisted. If an application does not
082: * provide values for these fields, default values are provided for the ToDo
083: * by the VM when the ToDo is persisted.
084: * </P>
085: * <h3>Examples</h3>
086: * <h4>Explicit Field Use with Field Checking</h4>
087: * This first example shows explicit field access in which each field and type
088: * ID is properly checked for support prior to use. This results in code that
089: * is more portable across PIM implementations regardless of which specific
090: * fields are supported on particular PIM list implementations. If one of the
091: * fields is not supported by the list, the field is not set in the ToDo.
092: * <pre>
093: * ToDoList todos = null;
094: * try {
095: * todos = (ToDoList) PIM.getInstance().openPIMList(PIM.TODO_LIST,
096: * PIM.READ_WRITE);
097: * } catch (PIMException e) {
098: * // An error occurred
099: * return;
100: * }
101: * ToDo todo = todos.createToDo();
102: * if (todos.isSupportedField(Event.SUMMARY))
103: * todo.addString(ToDo.SUMMARY, PIMItem.ATTR_NONE,
104: * "Buy going away present for Judy");
105: * if (todos.isSupportedField(Event.DUE))
106: * todo.addDate(ToDo.DUE, PIMItem.ATTR_NONE, new Date().getTime());
107: * if (todos.isSupportedField(Event.NOTE))
108: * todo.addString(ToDo.NOTE, PIMItem.ATTR_NONE,
109: * "Judy really likes stained glass and expensive pens");
110: * if (todos.isSupportedField(Event.PRIORITY))
111: * todo.addInt(ToDo.PRIORITY, PIMItem.ATTR_NONE, 2);
112: * if (todos.maxCategories() != 0 && todos.isCategory("Work"))
113: * todo.addToCategory("Work");
114: * }
115: * try {
116: * todo.commit();
117: * } catch (PIMException e) {
118: * // An error occured
119: * }
120: * try {
121: * todos.close();
122: * } catch (PIMException e) {
123: * }
124: * </pre>
125: * <h4>Explicit Field Use with Exception Handling</h4>
126: * This second example also shows explicit field access that properly handles
127: * optionally supported fields by use of a try catch block with
128: * <code>UnsupportedFieldException</code>. In this case, the setting of the
129: * whole ToDo is rejected if any of the fields are not supported in the
130: * particular list implementation.
131: * <PRE>
132: * ToDoList todos = null;
133: * try {
134: * todos = (ToDoList) PIM.getInstance().openPIMList(PIM.TODO_LIST,
135: * PIM.READ_WRITE);
136: * } catch (PIMException e) {
137: * // An error occurred
138: * return;
139: * }
140: * ToDo todo = todos.createToDo();
141: *
142: * try {
143: * todo.addString(ToDo.SUMMARY, PIMItem.ATTR_NONE,
144: * "Buy going away present for Judy");
145: * todo.addDate(ToDo.DUE, PIMItem.ATTR_NONE, new Date().getTime());
146: * todo.addString(ToDo.NOTE, PIMItem.ATTR_NONE,
147: * "Judy really likes stained glass and expensive pens");
148: * todo.addInt(ToDo.PRIORITY, PIMItem.ATTR_NONE, 2);
149: * todo.addToCategory("Work");
150: *
151: * } catch (UnsupportedFieldException e) {
152: * // In this case, we choose not to save the ToDo at all if any of the
153: * // fields are not supported on this platform.
154: * System.out.println("Todo not saved");
155: * return;
156: * }
157: *
158: * try {
159: * todo.commit();
160: * } catch (PIMException e) {
161: * // An error occured
162: * }
163: * try {
164: * todos.close();
165: * } catch (PIMException e) {
166: * }
167: * </PRE>
168: *
169: * @see <A target=_top href="http://www.imc.org/pdi">
170: * Internet Mail Consortium PDI</A>
171: * @see ToDoListImpl
172: * @since PIM 1.0
173: */
174:
175: public interface ToDo extends PIMItem {
176: /**
177: * Field specifying the desired access class for this contact.
178: * Data associated with this field is of int type, and can be one of the
179: * values {@link #CLASS_PRIVATE}, {@link #CLASS_PUBLIC}, or
180: * {@link #CLASS_CONFIDENTIAL}.
181: */
182: public static final int CLASS = 100;
183:
184: /**
185: * Field ID indicating a ToDo has been completed. Data for this field is
186: * of boolean type.
187: */
188: public static final int COMPLETED = 101;
189:
190: /**
191: * Field ID indicating a ToDo has been completed on the date indicated by
192: * this field. The data for this field is expressed in the same long value
193: * format as java.util.Date, which is milliseconds since the epoch
194: * (00:00:00 GMT, January 1, 1970).
195: * <P>
196: * Note that the value provided may be rounded-down by an implementation due
197: * to platform restrictions. For example, should a native ToDo database
198: * only support todo date values with granularity in terms of seconds, then
199: * the provided date value is rounded down to a date time with a
200: * full second.
201: * </p>
202: */
203: public static final int COMPLETION_DATE = 102;
204:
205: /**
206: * The date a ToDo is due.The data for this field is expressed in the same
207: * long value format as java.util.Date, which is milliseconds since the
208: * epoch (00:00:00 GMT, January 1, 1970).
209: * <P>
210: * Note that the value provided may be rounded-down by an implementation due
211: * to platform restrictions. For example, should a native ToDo database
212: * only support todo date values with granularity in terms of seconds, then
213: * the provided date value is rounded down to a date time with a
214: * full second.
215: * </p>
216: */
217: public static final int DUE = 103;
218:
219: /**
220: * Field specifying a more complete description than the SUMMARY for this
221: * ToDo. Data for this field is of string type. For example: <BR>
222: * "Judy really likes stained glass and expensive pens"
223: */
224: public static final int NOTE = 104;
225:
226: /**
227: * Field specifying the priority of this ToDo. The priority is a value
228: * from zero to nine. Zero specifies an undefined priority, one specifies
229: * the highest priority and nine the lowest priority. It is not guaranteed
230: * that this value remains unchanged after setting the value and/or
231: * persistence of the ToDo item due to underlying native database
232: * priority support and mappings to the native priority values. Data for
233: * this field is of int type.
234: */
235: public static final int PRIORITY = 105;
236:
237: /**
238: * Field specifying the last modification date and time of a ToDo
239: * item. If the ToDo has ever been committed to a ToDoList, then this
240: * attribute becomes read only. This field is set automatically on imports
241: * and commits of a ToDo. Data for this field is expressed
242: * in the same long value format as java.util.Date, which is
243: * milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
244: * <P>
245: * Note that the value provided may be rounded-down by an implementation
246: * due to platform restrictions. For example, should a native ToDo database
247: * only support todo date values with granularity in terms of seconds, then
248: * the provided date value is rounded down to a date time with a
249: * full second.
250: * </p>
251: */
252: public static final int REVISION = 106;
253:
254: /**
255: * Field specifying the summary or subject for this ToDo.
256: * Data for this field is of string type. For example: <BR>
257: * "Buy going away present for Judy"
258: */
259: public static final int SUMMARY = 107;
260:
261: /**
262: * Field specifying a unique ID for a ToDo. This field can be
263: * used to check for identity using <code>String.equals</code>. UID is
264: * read only if the ToDo has been committed to a ToDoList at least
265: * once in its lifetime. The UID is not set if the
266: * ToDo has never been committed to a ToDoList;
267: * <CODE>countValues(UID)</CODE> returns 0 before a newly
268: * created ToDo object is committed to its list. The attribute is valid
269: * for the persistent life of the ToDo and may be reused by the platform
270: * once this particular ToDo is deleted. Data for this field is of string
271: * type.
272: */
273: public static final int UID = 108;
274:
275: /**
276: * Constant indicating this todo's class of access is confidential.
277: */
278: public static final int CLASS_CONFIDENTIAL = 200;
279:
280: /**
281: * Constant indicating this todo's class of access is private.
282: */
283: public static final int CLASS_PRIVATE = 201;
284:
285: /**
286: * Constant indicating this todo's class of access is public.
287: */
288: public static final int CLASS_PUBLIC = 202;
289:
290: }
|