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 the common interfaces of an item for a PIM list.
035: * A PIM item represents a collection of data for a single PIM entry.
036: * A PIM item is created from a particular PIM list and is associated with
037: * that list for the life of the item. PIM items can have its data
038: * imported and exported using standard byte based formats. Each implementing
039: * class defines what formats can be imported and exported for that item.
040: * <H3>Fields</H3>
041: * <P>PIMItems reference its data through <i>fields</i>. A field is a grouping
042: * of data values that all have similar characteristics. An example of a field
043: * is TEL, which indicates data values for that particular field are telephone
044: * numbers. Classes implementing the PIMItem interface defines the possible
045: * fields that for that specific class (e.g TEL is defined in the
046: * <code>Contact</code> interface as a field that a contact may support).
047: * </P><P>
048: * PIM implementations are not required to support all of the possible fields
049: * defined in the classes implementing the PIMItem interface. This is because
050: * no native PIM databases contain all of the fields defined in this API.
051: * The PIMList that a PIMItem belongs to determines what fields a PIMItem can
052: * support and store (all PIMItems in a particular PIMList support the
053: * same set of fields). The {@link AbstractPIMList#getSupportedFields} method
054: * from a
055: * particular PIMItem's PIMList is used to find out what fields are supported
056: * within this item. Since not all possible fields are actually supported in a
057: * particular PIMItem, <B>all fields should be checked for support in the item's
058: * PIMList using {@link AbstractPIMList#isSupportedField} prior to being used
059: * in any retrieval or storage method.</B>
060: * </p><p>
061: * Each field has the following pieces of information available for it:
062: * <UL>
063: * <LI>Zero or more <i>data values</I> associated with the Field
064: * <LI><i>Attributes</I> for data values for the Field
065: * <LI>Descriptive <i>label</I> for the Field
066: * <LI><I>Data Type</i> of the data associated with the Field
067: * </UL>
068: * <h5>Data Values in a Field</h5>
069: * <p>A single field can have zero or more data values associated with it at any
070: * instance. All values within a field have the same data type as dictated by
071: * the field (for example, all Contact.TEL field data values must be of STRING
072: * type). The data type of a field determines the add/get/set methods to use
073: * for accessing the data values (for example, if a field requires STRING data
074: * types, then addString, getString, and setString methods are used to access
075: * the data).
076: * </p><P>
077: * Data values within a field are treated as a variable-length array of values,
078: * very similar to the behavior of a <code>Vector</code>. As such, the
079: * following rules apply for accessing data values for fields:<br>
080: * <ul>
081: * <li>Values are added using the appropriate addXXX() method. The value is
082: * appended as the last data value in the field's array, similar to
083: * <code>Vector.addElement</code>.</li>
084: * <li>Values are retrieved one at a time using the appropriate getXXX() method
085: * with an index. The index is an array index into the field's array of data
086: * values. Values are assigned a sequential index beginning from 0 for the first
087: * value in a field up to n-1, where n is the total number of values currently
088: * assigned to the field. This behavior is similar to the method
089: * <code>Vector.elementAt()</code>.</li>
090: * <li>Values are removed from a field by using the method
091: * {@link AbstractPIMItem#removeValue}.
092: * All indexes in the field's array are guaranteed by the implementation to
093: * contain an assigned value. Therefore, removing fields from the middle of a
094: * field's array causes compacting of the array and reindexing of the data
095: * values. This is similar behavior to the method
096: * <code>Vector.removeElement(Object)</code>.</li>
097: * </ul>
098: * <h5>Field Labels</h5>
099: * <p>Each field has a human readable <i>label</i>, usually used for display
100: * purposes.
101: * The label can be retrieved through {@link AbstractPIMList#getFieldLabel}.
102: * </p>
103: * <h5>Field Data Types</h5>
104: * <p>The data values for a field has a <i>data type</i>, such as {@link #INT},
105: * {@link #BINARY}, {@link #BOOLEAN}, {@link #DATE}, {@link #STRING_ARRAY} or
106: * {@link #STRING}. The data type of the field's data can be retrieved
107: * through {@link AbstractPIMList#getFieldDataType}.
108: * All data values for a particular field have the same data type.
109: * </p>
110: * <h4>Standard and Extended Fields</h4>
111: * <p>Fields can be classified into two logical divisions: standard fields and
112: * extended fields. This division of fields generally determines the
113: * portability of the fields across implementations. Standard fields are
114: * specifically defined within the javax.microedition.pim package and may be
115: * available on almost all PIM implementations. Extended fields are platform
116: * specific fields defined by an individual implementation and are therefore
117: * generally not portable across different devices. Extended fields are
118: * generally defined in vendor specific classes derived from this class.
119: * </p>
120: * <h5>Standard Fields</h5>
121: * <P>Standard fields are fields that have IDs explicitly defined as part of the
122: * PIM APIs in the javax.microedition.pim package. These fields are the common
123: * fields among PIM lists and are more likely to be portable across PIM
124: * implementations (but not guaranteed since not all platforms support the same
125: * fields in a PIMItem).
126: * </P>
127: * <h5>Extended Fields</h5>
128: * <p>Extended fields are fields that do not have a specific field explicitly
129: * defined in the javax.microedition.pim package, but are defined in
130: * vendor-specific classes in a separate vendor package. These fields may or
131: * may not be exposed publicly in vendor specific classes. Vendors are allowed
132: * to extend the field set for any of the PIM items in this manner to address
133: * any platform specific fields they wish to support. Users can find out if a
134: * field is an extended field by comparing its value against
135: * {@link #EXTENDED_FIELD_MIN_VALUE}, find out the field's allowed data type
136: * through the method {@link AbstractPIMList#getFieldDataType}, and find out
137: * the field's label through the method {@link AbstractPIMList#getFieldLabel}.
138: * </p>
139: * <h4>Attributes</h4>
140: * <p>Optional attributes can be provided to further describe individual data
141: * values for a field. Attributes are specified when adding data values to a
142: * field. These attributes are hints to the underlying implementation providing
143: * more information about the data value than just a field can provide. Since
144: * they are hints, they may or may not be ignored by the implementation when
145: * adding the data values. The actual attributes used and associated with the
146: * data values after adding can be retrieved by the method
147: * {@link AbstractPIMItem#getAttributes}.
148: * Attributes can also have human readable labels associated with them,
149: * retrieved by the method {@link AbstractPIMList#getAttributeLabel}.
150: * If no attributes are to be associated with a data value, then
151: * {@link #ATTR_NONE} must be used.
152: * </p><p>
153: * Attributes are handled in the API using a single bit to indicate a specific
154: * attribute and using int values as bit arrays to indicate a set of attributes.
155: * int values can be checked to see if they contain a specific attribute by
156: * using bitwise AND (&) with the attribute and the int value.
157: * {@link #ATTR_NONE} is a special attribute that indicates no attributes are
158: * set and has a value of 0 that erases all other attributes previously set.
159: * </P>
160: * <h5>Extended Attributes</h5>
161: * <p>Optional attributes may also be extended by vendors and their PIM API
162: * implementations. These extended attributes also may or may not be exposed
163: * publicly in vendor specific classes. The label for these attributes can
164: * be retrieved through {@link AbstractPIMList#getAttributeLabel}.
165: * </p>
166: * <h3>Categories</h3>
167: * <p>Categories are string items assigned to an item to represent the
168: * item's inclusion in a logical grouping. The category string
169: * correspond to category values already existing in the PIMItem's
170: * associated PIMList. Category support per list is optional, depending
171: * on the implementing PIMList class that the
172: * item is associated with. The item's list determines if categories can be
173: * assigned, and how many categories can be assigned per item.
174: * </p>
175: *
176: * @since PIM 1.0
177: */
178:
179: public interface PIMItem {
180:
181: /**
182: * Data type indicating data is binary in a byte array.
183: * Data associated with <code>BINARY</code> is
184: * retrieved via {@link AbstractPIMItem#getBinary}
185: * and added via {@link AbstractPIMItem#addBinary}.
186: */
187: public static final int BINARY = 0;
188:
189: /**
190: * Data type indicating data is of boolean primitive data type.
191: * Data associated with <code>BOOLEAN</code> is
192: * retrieved via {@link AbstractPIMItem#getBoolean}
193: * and added via {@link AbstractPIMItem#addBoolean}.
194: */
195: public static final int BOOLEAN = 1;
196:
197: /**
198: * Data type indicating data is a Date in long primitive data type format
199: * expressed in the same long value format as java.util.Date, which is
200: * milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
201: * Data associated with <code>DATE</code> is
202: * retrieved via {@link AbstractPIMItem#getDate}
203: * and added via {@link AbstractPIMItem#addDate}.
204: */
205: public static final int DATE = 2;
206:
207: /**
208: * Data type indicating data is of int primitive data type.
209: * Data associated with <code>INT</code> is
210: * retrieved via {@link AbstractPIMItem#getInt}
211: * and added via {@link AbstractPIMItem#addInt}.
212: */
213: public static final int INT = 3;
214:
215: /**
216: * Data type indicating data is a String object.
217: * Data associated with <code>STRING</code> is
218: * retrieved via {@link AbstractPIMItem#getString}
219: * and added via {@link AbstractPIMItem#addString}.
220: */
221: public static final int STRING = 4;
222:
223: /**
224: * Data type indicating data is a array of related fields returned in a
225: * string array. Data associated with <code>STRING_ARRAY</code> is
226: * retrieved via {@link AbstractPIMItem#getStringArray}
227: * and added via {@link AbstractPIMItem#addStringArray}.
228: */
229: public static final int STRING_ARRAY = 5;
230:
231: /**
232: * Constant indicating that no additional attributes are applicable to
233: * a data value for a field.
234: */
235: public static final int ATTR_NONE = 0;
236:
237: /**
238: * Constant indicating the minimum possible value for an extended field
239: * constant.
240: */
241: public static final int EXTENDED_FIELD_MIN_VALUE = 0x1000000;
242:
243: /**
244: * Constant indicating the minimum possible value for an extended attribute
245: * constant.
246: */
247: public static final int EXTENDED_ATTRIBUTE_MIN_VALUE = 0x1000000;
248: }
|