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 Event entry in a PIM Event database.
035: * The fields are a subset of the fields in the <code>vEvent</code> object
036: * defined by the vCalendar 1.0 specification from the Internet Mail Consortium
037: * (http://www.imc.org). The subset represents those fields necessary to
038: * provide the relevant information about an Event entry without compromising
039: * platform portability.
040: * <P>
041: * A single event may have multiple occurrences; i.e. the event may be a
042: * recurring event that is repeated at specified intervals. Each occurrence of
043: * an event is determined by using a {@link javax.microedition.pim.RepeatRule}
044: * to calculate when the
045: * event should have additional occurrences, besides the one defined by the
046: * <code>Event.START</code> field.
047: * </P>
048: * <P>The Event class has many different fields that it can support.
049: * However, each individual Event object supports only fields valid for its
050: * associated list. Its EventList restricts what fields in a Event are
051: * retained. This reflects that some native Event databases do not support all
052: * of the fields available in a Event item. The methods
053: * {@link AbstractPIMList#isSupportedField}
054: * and {@link AbstractPIMList#getSupportedFields}
055: * can be used to determine if a particular Event field is supported by an
056: * EventList and therefore persisted when the Event is committed to its list.
057: * Attempts to set or get data based on field IDs not supported in the Event's
058: * EventList result in a
059: * {@link javax.microedition.pim.UnsupportedFieldException}.
060: * </P>
061: * <H3>Data</H3>
062: * <P>The following table details the explicitly defined fields that may by in
063: * an Event. Implementations may extend the field set using extended fields as
064: * defined in PIMItem.
065: * </P>
066: * <h4>Table: Predefined Fields</h4>
067: * <table border=1>
068: * <TR>
069: * <th> Fields </th><th> Type of Data Associated with Field </th>
070: * </tr>
071: * <tr><td><code>LOCATION, NOTE, SUMMARY, UID</code></td>
072: * <td><code>PIMItem.STRING</code></td>
073: * </tr>
074: * <tr><td><code>END, REVISION, START </code></td>
075: * <td><code>PIMItem.DATE</code></td>
076: * </tr>
077: * <tr><td><code>ALARM, CLASS</code></td>
078: * <td><code>PIMItem.INT</code></td>
079: * </tr>
080: * </table>
081: *
082: * <h3>Required Field Support</h3>
083: * <P>All Event fields may or may not be supported by a particular list. This
084: * is due to the fact that underlying native databases may not support all of
085: * the fields defined in this API. Support for any of the fields can be
086: * determined by the method {@link AbstractPIMList#isSupportedField}.
087: * </p><P>
088: * Native Event databases may require some of the fields to have values
089: * assigned to them in order to be persisted. If an application does not
090: * provide values for these fields, default values are provided for the Event
091: * by the VM when the Event is persisted.
092: * </P>
093: * <h3>Examples</h3>
094: * <h4>Explicit Field Use with Field Checking</h4>
095: * This first example shows explicit field access in which each field and type
096: * ID is properly checked for support prior to use. This results in code that
097: * is more portable across PIM implementations regardless of which specific
098: * fields are supported on particular PIM list implementations. If one of the
099: * fields is not supported by the list, the field is not set in the Event.
100: * <pre>
101: * EventList events = null;
102: * try {
103: * events = (EventList) PIM.getInstance().openPIMList(PIM.EVENT_LIST,
104: * PIM.READ_WRITE);
105: * } catch (PIMException e) {
106: * // An error occurred
107: * return;
108: * }
109: * Event event = events.createEvent();
110: * if (events.isSupportedField(Event.SUMMARY))
111: * event.addString(Event.SUMMARY, PIMItem.ATTR_NONE, "Meeting with John");
112: * if (events.isSupportedField(Event.START))
113: * event.addDate(Event.START, PIMItem.ATTR_NONE, aDate.getTime());
114: * if (events.isSupportedField(Event.END))
115: * event.addDate(Event.END, PIMItem.ATTR_NONE, aDate.getTime());
116: * if (events.isSupportedField(Event.ALARM))
117: * event.addInt(Event.ALARM, PIMItem.ATTR_NONE, aDate.getTime() - 60000);
118: * if (events.isSupportedField(Event.NOTE))
119: * event.addString(Event.NOTE, PIMItem.ATTR_NONE,
120: * "I phoned on Monday to book this meeting");
121: * if (events.maxCategories() != 0 && events.isCategory("Work"))
122: * event.addToCategory("Work");
123: * }
124: * try {
125: * event.commit();
126: * } catch (PIMException e) {
127: * // An error occured
128: * }
129: * try {
130: * events.close();
131: * } catch (PIMException e) {
132: * }
133: * </pre>
134: * <h4>Explicit Field Use with Exception Handling</h4>
135: * This second example also shows explicit field access that properly handles
136: * optionally supported fields by use of a try catch block with
137: * <code>UnsupportedFieldException</code>. In this case, the setting of the
138: * whole Event is rejected if any of the fields are not supported in the
139: * particular list implementation.
140: * <PRE>
141: * EventList events = null;
142: * try {
143: * events = (EventList) PIM.getInstance().openPIMList(PIM.EVENT_LIST,
144: * PIM.READ_WRITE);
145: * } catch (PIMException e) {
146: * // An error occurred
147: * return;
148: * }
149: * Event event = events.createEvent();
150: *
151: * try {
152: * Date aDate = new Date();
153: * event.addString(Event.SUMMARY, PIMItem.ATTR_NONE, "Meeting with John");
154: * event.addDate(Event.START, PIMItem.ATTR_NONE, aDate.getTime());
155: * event.addDate(Event.END, PIMItem.ATTR_NONE, aDate.getTime());
156: * event.addDate(Event.ALARM, PIMItem.ATTR_NONE, aDate.getTime() - 60000);
157: * event.addString(Event.NOTE, PIMItem.ATTR_NONE,
158: * "I phoned on Monday to book this meeting");
159: * event.addToCategory("Work");
160: *
161: * } catch (UnsupportedFieldException e) {
162: * // In this case, we choose not to save the contact at all if any of the
163: * // fields are not supported on this platform.
164: * System.out.println("Event not saved");
165: * return;
166: * }
167: *
168: * try {
169: * event.commit();
170: * } catch (PIMException e) {
171: * // An error occured
172: * }
173: * try {
174: * events.close();
175: * } catch (PIMException e) {
176: * }
177: * </PRE>
178: *
179: * @see <A target=_top href="http://www.imc.org/pdi">
180: * Internet Mail Consortium PDI</A>
181: * @see EventListImpl
182: * @since PIM 1.0
183: */
184:
185: public interface Event extends PIMItem {
186: /**
187: * Field specifying a relative time for an Alarm for this Event. Data
188: * for this field is expressed with an int data type. The alarm is
189: * expressed in seconds and derived by subtracting the alarm value from
190: * every date/time occurrence of this Event. For example, if this field has
191: * a value of 600, then the alarm first occurs 600 seconds before the
192: * date/time value specified by <code>Event.START</code>. For
193: * reoccurrences of the event, the alarm is calculated by subtracting the
194: * stored value from the date/time of the specific event occurrence.
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 Event database
198: * only support alarm values with granularity in terms of minutes, then the
199: * provided alarm value is rounded down to the nearest minute (e.g.
200: * 636 seconds would become 600 seconds).
201: * </p>
202: */
203: public static final int ALARM = 100;
204:
205: /**
206: * Field specifying the desired access class for this contact.
207: * Data associated with this field is of int type, and can be one of the
208: * values {@link #CLASS_PRIVATE}, {@link #CLASS_PUBLIC}, or
209: * {@link #CLASS_CONFIDENTIAL}.
210: */
211: public static final int CLASS = 101;
212:
213: /**
214: * Field specifying the non-inclusive date and time a single Event
215: * ends. Data for this field is expressed in the same long value
216: * format as java.util.Date, which is milliseconds since the epoch
217: * (00:00:00 GMT, January 1, 1970).
218: * <P>
219: * If <CODE>START</CODE> and <CODE>END</CODE> are the same this event is
220: * an all day event. If <CODE>END</code> is specified but <CODE>START</code>
221: * is not, the event occurs only at the instance specified by
222: * <CODE>END</code>.
223: * </P><P>
224: * Note that the value provided may be rounded-down by an implementation due
225: * to platform restrictions. For example, should a native Event database
226: * only support event date values with granularity in terms of seconds, then
227: * the provided date value is rounded down to a date time with a
228: * full second.
229: * </p>
230: *
231: * @see #START
232: */
233: public static final int END = 102;
234:
235: /**
236: * Field identifying the venue for this Event. Data for this field is a
237: * string value. For example: <BR>
238: * "Conference Room - F123, Bldg. 002"
239: */
240: public static final int LOCATION = 103;
241:
242: /**
243: * A String specifying a more complete description than the
244: * <CODE>SUMMARY</CODE> for this Event. Data for this field is a string
245: * value.
246: * For example: <BR>
247: * "I phoned John on Friday to book this meeting, he better show"
248: */
249: public static final int NOTE = 104;
250:
251: /**
252: * Field specifying the last modification date and time of an Event
253: * item. If the Event has ever been committed to an EventList, then this
254: * attribute becomes read only. This field is set automatically on imports
255: * and commits of an Event. The data for this field is expressed
256: * in the same long value format as java.util.Date, which is
257: * milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
258: * <P>
259: * Note that the value provided may be rounded-down by an implementation due
260: * to platform restrictions. For example, should a native Event database
261: * only support event date values with granularity in terms of seconds, then
262: * the provided date value is rounded down to a date time with a
263: * full second.
264: * </p>
265: */
266: public static final int REVISION = 105;
267:
268: /**
269: * Field specifying the inclusive date and time a single Event
270: * starts. The data for this field is expressed
271: * in the same long value format as java.util.Date, which is
272: * milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
273: * <P>
274: * If <CODE>START</CODE> and <CODE>END</CODE> are the same this event is
275: * an all day event. If <CODE>START</code> is specified but <CODE>END</code>
276: * is not, the event occurs only at the instance specified by
277: * <CODE>START</code>.
278: * <P>
279: * Note that the value provided may be rounded-down by an implementation due
280: * to platform restrictions. For example, should a native Event database
281: * only support event date values with granularity in terms of seconds, then
282: * the provided date value is rounded down to a date time with a
283: * full second.
284: * </p>
285: *
286: * @see #END
287: */
288: public static final int START = 106;
289:
290: /**
291: * Field specifying the summary or subject for this Event. Data for this
292: * field is a string type. For example: <BR>
293: * "Meeting with John"
294: */
295: public static final int SUMMARY = 107;
296:
297: /**
298: * Field specifying a unique ID for an Event. This field can be
299: * used to check for identity using <code>String.equals</code>. UID is
300: * read only if the Event has been committed to an EventList at least
301: * once in its lifetime. The UID is not set if the
302: * Event has never been committed to an EventList;
303: * <CODE>countValues(UID)</CODE> returns 0 before a newly
304: * created Event object is committed to its list. The attribute is valid
305: * for the persistent life of the Event and may be reused by the platform
306: * once this particular Event is deleted. The data for this field is of
307: * string type.
308: */
309: public static final int UID = 108;
310:
311: /**
312: * Constant indicating this event's class of access is confidential.
313: */
314: public static final int CLASS_CONFIDENTIAL = 200;
315:
316: /**
317: * Constant indicating this event's class of access is private.
318: */
319: public static final int CLASS_PRIVATE = 201;
320:
321: /**
322: * Constant indicating this event's class of access is public.
323: */
324: public static final int CLASS_PUBLIC = 202;
325: }
|