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 Contact entry in a PIM Contact database.
035: * The supported field list for a Contact is also a subset of the fields defined
036: * by the vCard specification from the Internet Mail Consortium
037: * (http://www.imc.org). This set of fields included
038: * in this Contact class represents those necessary to provide the relevant
039: * information about a contact without compromising platform portability.
040: *
041: * <P>The Contact class has many different fields that it can support.
042: * However, each individual Contact object supports only fields valid for its
043: * associated list. Its ContactList restricts what fields in a Contact are
044: * retained. This reflects that some native Contact databases do not support
045: * all of the fields available in a Contact item. The methods
046: * {@link AbstractPIMList#isSupportedField} and
047: * {@link AbstractPIMList#getSupportedAttributes}
048: * can be used to determine if particular Contact fields and types are supported
049: * by a ContactList and therefore persisted when the Contact is committed to its
050: * list. Attempts to add or get data based on fields not supported in the
051: * Contact's ContactList result in a
052: * {@link javax.microedition.pim.UnsupportedFieldException}.
053: * </P>
054: * <H3>Data</H3>
055: * The following table details the explicitly defined fields that may by in a
056: * Contact. Implementations may extend the field set using extended fields as
057: * defined in PIMItem.
058: * <h4>Table: Standard Fields</h4>
059: * <table border=1>
060: * <TR>
061: * <th> Fields </th>
062: * <th> Type of Data Associated with Field </th>
063: * </tr>
064: * <tr><td><code>NAME, ADDR</code></td>
065: * <td><code>PIMItem.STRING_ARRAY</code></td>
066: * </tr>
067: * <tr><td><code>EMAIL, FORMATTED_NAME, NICKNAME, NOTE, ORG, TEL, TITLE, UID,
068: * URL</code></td>
069: * <td><code>PIMItem.STRING</code></td>
070: * </tr>
071: * <tr><td><code>BIRTHDAY, REVISION</code></td>
072: * <td><code>PIMItem.DATE</code></td>
073: * </tr>
074: * <tr><td><code>PHOTO, PUBLIC_KEY</code></td>
075: * <td><code>PIMItem.BINARY</code></td>
076: * </tr>
077: * <tr><td><code>PHOTO_URL, PUBLIC_KEY_STRING</code></td>
078: * <td><code>PIMItem.STRING</code></td>
079: * </tr>
080: * <tr><td><code>CLASS</code></td>
081: * <td><code>PIMItem.INT</code></td>
082: * </tr>
083: * </table>
084: *
085: * <h3>Required Field Support</h3>
086: * <P>All Contact fields may or may not be supported by a particular list. This
087: * is due to the fact that underlying native databases may not support all of
088: * the fields defined in this API. Support for any of the fields can be
089: * determined by the method {@link AbstractPIMList#isSupportedField}.
090: * </p><P>
091: * Native Contact databases may require some of the fields to have values
092: * assigned to them in order to be persisted. If an application does not
093: * provide values for these fields, default values are provided for the Contact
094: * by the VM when the Contact is persisted.
095: * </P>
096: * <h3>Examples</h3>
097: * <h4>Explicit Field Use with Field Checking</h4>
098: * This first example shows explicit field access in which each field
099: * is properly checked for support prior to use. This results in code that
100: * is more portable across PIM implementations regardless of which specific
101: * fields are supported on particular PIM list implementations. If one of the
102: * fields is not supported by the list, the field is not set in the Contact.
103: * <pre>
104: * ContactList contacts = null;
105: * try {
106: * contacts = (ContactList) PIM.getInstance().openPIMList(PIM.CONTACT_LIST,
107: * PIM.READ_WRITE);
108: * } catch (PIMException e) {
109: * // An error occurred
110: * return;
111: * }
112: * Contact contact = contacts.createContact();
113: * String[] addr = new String[contacts.stringArraySize(Contact.ADDR)];
114: * String[] name = new String[contacts.stringArraySize(Contact.NAME)];
115: *
116: * if (contacts.isSupportedField(Contact.NAME_FORMATTED)
117: * contact.addString(Contact.NAME_FORMATTED, PIMItem.ATTR_NONE,
118: * "Mr. John Q. Public, Esq.");
119: * if (contacts.isSupportedArrayElement(Contact.NAME, Contact.NAME_FAMILY))
120: * name[Contact.NAME_FAMILY] = "Public";
121: * if (contacts.isSupportedArrayElement(Contact.NAME, Contact.NAME_GIVEN))
122: * name[Contact.NAME_GIVEN] = "John";
123: * contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, name);
124: * if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_COUNTRY))
125: * addr[Contact.ADDR_COUNTRY] = "USA";
126: * if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_LOCALITY))
127: * addr[Contact.ADDR_LOCALITY] = "Coolsville";
128: * if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_POSTALCODE))
129: * addr[Contact.ADDR_POSTALCODE] = "91921-1234";
130: * if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_STREET))
131: * addr[Contact.ADDR_STREET] = "123 Main Street";
132: * if (contacts.isSupportedField(Contact.ADDR))
133: * contact.addStringArray(Contact.ADDR, Contact.ATTR_HOME, addr);
134: * if (contacts.isSupportedField(Contact.TEL))
135: * contact.addString(Contact.TEL, Contact.ATTR_HOME, "613-123-4567");
136: * if (contacts.maxCategories() != 0
137: * && contacts.isCategory("Friends"))
138: * contact.addToCategory("Friends");
139: * if (contacts.isSupportedField(Contact.BIRTHDAY))
140: * contact.addDate(Contact.BIRTHDAY, PIMItem.ATTR_NONE,
141: * new Date().getTime());
142: * if (contacts.isSupportedField(Contact.EMAIL)) {
143: * contact.addString(Contact.EMAIL,
144: * Contact.ATTR_HOME | Contact.ATTR_PREFERRED,
145: * "jqpublic@xyz.dom1.com");
146: * }
147: * try {
148: * contact.commit();
149: * } catch (PIMException e) {
150: * // An error occured
151: * }
152: * try {
153: * contacts.close();
154: * } catch (PIMException e) {
155: * }
156: * </pre>
157: * <h4>Explicit Field Use with Exception Handling</h4>
158: * This second example also shows explicit field access that properly handles
159: * optionally supported fields by use of a try catch block with
160: * <code>UnsupportedFieldException</code>. In this case, the setting of the
161: * whole Contact is rejected if any of the fields are not supported in the
162: * particular list implementation.
163: * <PRE>
164: * ContactList contacts = null;
165: * try {
166: * contacts = (ContactList) PIM.getInstance().openPIMList(PIM.CONTACT_LIST,
167: * PIM.READ_WRITE);
168: * } catch (PIMException e) {
169: * // An error occurred
170: * return;
171: * }
172: * Contact contact = contacts.createContact();
173: *
174: * String[] name = new String[contacts.stringArraySize(Contact.NAME)];
175: * name[Contact.NAME_GIVEN] = "John";
176: * name[Contact.NAME_FAMILY] = "Public";
177: *
178: * String[] addr = new String[contacts.stringArraySize(Contact.ADDR)];
179: * addr[Contact.ADDR_COUNTRY] = "USA";
180: * addr[Contact.ADDR_LOCALITY] = "Coolsville";
181: * addr[Contact.ADDR_POSTALCODE] = "91921-1234";
182: * addr[Contact.ADDR_STREET] = "123 Main Street";
183: *
184: * try {
185: * contact.addString(Contact.NAME_FORMATTED, PIMItem.ATTR_NONE,
186: * "Mr. John Q. Public, Esq.");
187: * contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, name);
188: * contact.addStringArray(Contact.ADDR, Contact.ATTR_HOME, addr);
189: * contact.addString(Contact.TEL, Contact.ATTR_HOME, "613-123-4567");
190: * contact.addToCategory("Friends");
191: * contact.addDate(Contact.BIRTHDAY, PIMItem.ATTR_NONE,
192: * new Date().getTime());
193: * contact.addString(Contact.EMAIL,
194: * Contact.ATTR_HOME | Contact.ATTR_PREFERRED,
195: * "jqpublic@xyz.dom1.com");
196: *
197: * } catch (UnsupportedFieldException e) {
198: * // In this case, we choose not to save the contact at all if any of the
199: * // fields are not supported on this platform.
200: * System.out.println("Contact not saved");
201: * return;
202: * }
203: *
204: * try {
205: * contact.commit();
206: * } catch (PIMException e) {
207: * // An error occured
208: * }
209: * try {
210: * contacts.close();
211: * } catch (PIMException e) {
212: * }
213: * </PRE>
214: *
215: *
216: * @see <A target=_top href="http://www.imc.org/pdi">Internet
217: * Mail Consortium PDI</A>
218: * @see ContactListImpl
219: * @since PIM 1.0
220: */
221:
222: public interface Contact extends PIMItem {
223: /**
224: * Field specifying an address for this Contact. Data for this field is of
225: * STRING_ARRAY type.
226: */
227: public static final int ADDR = 100;
228:
229: /**
230: * Field for the birthday of the Contact. Data for this field is
231: * expressed in the same long value format as java.util.Date, which is
232: * milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
233: * <P>
234: * Note that the value provided may be rounded-down by an implementation due
235: * to platform restrictions. For example, should a native Contact database
236: * only support contact date values with granularity in terms of seconds,
237: * then the provided date value is rounded down to a date time with a
238: * full second.
239: * </p>
240: */
241: public static final int BIRTHDAY = 101;
242:
243: /**
244: * Field specifying the desired access class for this contact.
245: * Data associated with this field is of int type, and can be one of the
246: * values {@link #CLASS_PRIVATE}, {@link #CLASS_PUBLIC}, or
247: * {@link #CLASS_CONFIDENTIAL}.
248: */
249: public static final int CLASS = 102;
250:
251: /**
252: * Field for an e-mail address. Data for this field is of String type.
253: */
254: public static final int EMAIL = 103;
255:
256: /**
257: * Field represents a formatted version of a complete address for the
258: * Contact entry. This string is typically a single string containing the
259: * complete address separated with CRLF separators. This field is typically
260: * present for contact databases that support only one field for a contact's
261: * address, or for specifying address label format. Data for this field is
262: * of STRING type.
263: * For example:<BR>
264: * "123 Main St.
265: * Anytown, CA 99999
266: * USA"
267: */
268: public static final int FORMATTED_ADDR = 104;
269:
270: /**
271: * Field represents a formatted version of a name for the Contact
272: * entry. Data for this field is of STRING type. The string data associated
273: * with this field conforms to the X.520 Common Name attribute format.
274: * For example:<BR>
275: * "Mr. John Q. Public, Esq."
276: */
277: public static final int FORMATTED_NAME = 105;
278:
279: /**
280: * Field specifying the name for this contact. Data for this field is of
281: * STRING_ARRAY type.
282: */
283: public static final int NAME = 106;
284:
285: /**
286: * Field where the data represents a nickname. Data for this field is of
287: * STRING type.
288: * For example: <BR>
289: * "Copier Man"
290: */
291: public static final int NICKNAME = 107;
292:
293: /**
294: * Field specifying supplemental information or a comment associated
295: * with a Contact. Data for this field is of
296: * String type. The data associated with this field follows the
297: * X.520 Description data format. For example: <BR>
298: * "The fax number is operational 0800 to 1715 EST, Mon-Fri."
299: */
300: public static final int NOTE = 108;
301:
302: /**
303: * Field specifying the organization name or units associated with a
304: * Contact. Data for this field is of
305: * String type. The data associated with this field is based on the X.520
306: * Organization data format. For example: <BR>
307: * "ABC Inc."
308: */
309: public static final int ORG = 109;
310:
311: /**
312: * Field specifying a photo for a Contact. Data associated with this field
313: * is inline binary. Manipulation of this field may affect data stored in
314: * the <code>PHOTO_URL</code> field since some implementation may use the
315: * same memory for both fields (e.g. one can either have PHOTO or have
316: * PHOTO_URL but not both).
317: *
318: * @see AbstractPIMList#isSupportedField
319: */
320: public static final int PHOTO = 110;
321:
322: /**
323: * Field specifying a photo of a Contact. Data associated
324: * with this field is of String type, representing a URL for the photo.
325: * Manipulation of this field may affect data stored in the
326: * <code>PHOTO</code> field since some implementation may use the same
327: * memory for both fields (e.g. one can either have PHOTO or have PHOTO_URL
328: * but not both).
329: *
330: * @see AbstractPIMList#isSupportedField
331: */
332: public static final int PHOTO_URL = 111;
333:
334: /**
335: * Field specifying the public encryption key for a Contact.
336: * Data associated with this field is inline binary encoded data.
337: * Manipulation of this field may affect data stored in the
338: * <code>PUBLIC_KEY_STRING</code> field since some implementation may use
339: * the same memory for both fields (e.g. one can either have PUBLIC_KEY or
340: * have PUBLIC_KEY_STRING but not both).
341: */
342: public static final int PUBLIC_KEY = 112;
343:
344: /**
345: * Field specifying the public encryption key for a Contact.
346: * Data associated with this field is of String type.
347: * Manipulation of this field may affect data stored in the
348: * <code>PUBLIC_KEY</code> field since some implementation may use the same
349: * memory for both fields (e.g. one can either have PUBLIC_KEY or have
350: * PUBLIC_KEY_STRING but not both).
351: */
352: public static final int PUBLIC_KEY_STRING = 113;
353:
354: /**
355: * Field specifying the last modification date and time of a Contact
356: * item. If the Contact has ever been committed to a ContactList, then
357: * this attribute becomes read only. This field is set automatically on
358: * imports and commits of a Contact. Data for this field is expressed
359: * in the same long value format as java.util.Date, which is
360: * milliseconds since the epoch (00:00:00 GMT, January 1, 1970).
361: * <P>
362: * Note that the value provided may be rounded-down by an implementation due
363: * to platform restrictions. For example, should a native Contact database
364: * only support contact date values with granularity in terms of seconds,
365: * then the provided date value is rounded down to a date time with a
366: * full second.
367: * </p>
368: */
369: public static final int REVISION = 114;
370:
371: /**
372: * Field for a voice telephone number. Data associated with this field is
373: * of String type and can be any valid String. No telephone formatting
374: * is enforced since many native implementations allow free form text to
375: * be associated with TEL fields.
376: */
377: public static final int TEL = 115;
378:
379: /**
380: * Field specifying the job title for a Contact. Data for this field is of
381: * String type. This title is based on the X.520 Title attributes.
382: * For example: <BR>
383: * "Director, Research and Development"
384: */
385: public static final int TITLE = 116;
386:
387: /**
388: * Field specifying a unique ID for a Contact. This field can be
389: * used to check for identity using <code>String.equals</code>. UID is
390: * read only if the Contact has been committed to a ContactList at least
391: * once in its lifetime. The UID is not set if the
392: * Contact has never been committed to a ContactList;
393: * <CODE>countValues(UID)</CODE> returns 0 before a newly created
394: * Contact object is committed to its list. The attribute is valid
395: * for the persistent life of the Contact and may be reused by the platform
396: * once this particular Contact is deleted. Data for this field is of
397: * String data type.
398: */
399: public static final int UID = 117;
400:
401: /**
402: * Field specifying the uniform resource locator for a Contact. Data for
403: * this field is of String data type.
404: * For example: <BR>
405: * "http://www.swbyps.restaurant.french/~chezchic.html"
406: */
407: public static final int URL = 118;
408:
409: /**
410: * Attribute classifying a data value as related to an ASSISTANT.
411: */
412: public static final int ATTR_ASST = 1;
413:
414: /**
415: * Attribute classifying a data value as related to AUTO.
416: */
417: public static final int ATTR_AUTO = 2;
418:
419: /**
420: * Attribute classifying a data value as related to FAX.
421: */
422: public static final int ATTR_FAX = 4;
423:
424: /**
425: * Attribute classifying a data value as related to HOME.
426: */
427: public static final int ATTR_HOME = 8;
428:
429: /**
430: * Attribute classifying a data value as related to MOBILE.
431: */
432: public static final int ATTR_MOBILE = 16;
433:
434: /**
435: * Attribute classifying a data value as "OTHER".
436: */
437: public static final int ATTR_OTHER = 32;
438:
439: /**
440: * Attribute classifying a data value as related to PAGER.
441: */
442: public static final int ATTR_PAGER = 64;
443:
444: /**
445: * Attribute classifying a data value with preferred status for
446: * retrieval or display purposes (platform specific). Only one value in
447: * a field may be marked as preferred. Subsequent assigning of preferred
448: * status to values in a field overrides any previous preferred status
449: * indications.
450: */
451: public static final int ATTR_PREFERRED = 128;
452:
453: /**
454: * Attribute classifying a data value as related to SMS.
455: */
456: public static final int ATTR_SMS = 256;
457:
458: /**
459: * Attribute classifying a data value as related to WORK.
460: */
461: public static final int ATTR_WORK = 512;
462:
463: /**
464: * Index into the string array for an address field, where the data at
465: * this index represents the post office box of a particular address. Data
466: * for this field is of String type.
467: */
468: public static final int ADDR_POBOX = 0;
469:
470: /**
471: * Index into the string array for an address field, where the data at
472: * this index represents any extra info of a particular address. Data for
473: * this field is of String type.
474: */
475: public static final int ADDR_EXTRA = 1;
476:
477: /**
478: * Index into the string array for an address field, where the data at
479: * this index represents the street information of a particular address.
480: * Data for this field is of String type.
481: */
482: public static final int ADDR_STREET = 2;
483:
484: /**
485: * Index into the string array for an address field, where the data at
486: * this index represents the locality (for example, a city) of a particular
487: * address. Data for this field is of String type.
488: */
489: public static final int ADDR_LOCALITY = 3;
490:
491: /**
492: * Index into the string array for an address field, where the data at
493: * this index represents the region (for example, a province, state, or
494: * territory) of a particular address.
495: * Data for this field is of String type.
496: */
497: public static final int ADDR_REGION = 4;
498:
499: /**
500: * Index into the string array for an address field, where the data at
501: * this index represents the postal code (for example, a zip code) of a
502: * particular address. Data for this field is of String type.
503: */
504: public static final int ADDR_POSTALCODE = 5;
505:
506: /**
507: * Index into the string array for an address field, where the data at
508: * this index represents the country of a particular address. Data for this
509: * field is of String type.
510: */
511: public static final int ADDR_COUNTRY = 6;
512:
513: /**
514: * Index into the string array for a name field, where the data at
515: * this index represents the family name.
516: * For example: <BR>
517: * "Stevenson"
518: */
519: public static final int NAME_FAMILY = 0;
520:
521: /**
522: * Index into the string array for a name field, where the data at
523: * this index represents the given name.
524: * For example: <BR>
525: * "Johnathan"
526: */
527: public static final int NAME_GIVEN = 1;
528:
529: /**
530: * Index into the string array for a name field, where the data at
531: * this index represents other alternate name or names.
532: * For example: <BR>
533: * "John, Johnny"
534: */
535: public static final int NAME_OTHER = 2;
536:
537: /**
538: * Index into the string array for a name field, where the data at
539: * this index represents a prefix to a name.
540: * For example: <BR>
541: * "Dr."
542: */
543: public static final int NAME_PREFIX = 3;
544:
545: /**
546: * Index into the string array for a name field, where the data at
547: * this index represents a suffix to a name.
548: * For example: <BR>
549: * "M.D., A.C.P."
550: */
551: public static final int NAME_SUFFIX = 4;
552:
553: /**
554: * Constant indicating this contact's class of access is confidential.
555: */
556: public static final int CLASS_CONFIDENTIAL = 200;
557:
558: /**
559: * Constant indicating this contact's class of access is private.
560: */
561: public static final int CLASS_PRIVATE = 201;
562:
563: /**
564: * Constant indicating this contact's class of access is public.
565: */
566: public static final int CLASS_PUBLIC = 202;
567:
568: }
|