File Doc Category Size Date Package
Contact.java API Doc phoneME MR2 API (J2ME) 21729 Wed May 02 18:00:28 BST 2007 com.sun.kvem.midp.pim

Contact

public interface Contact implements PIMItem

Represents a single Contact entry in a PIM Contact database. The supported field list for a Contact is also a subset of the fields defined by the vCard specification from the Internet Mail Consortium (http://www.imc.org). This set of fields included in this Contact class represents those necessary to provide the relevant information about a contact without compromising platform portability.

The Contact class has many different fields that it can support. However, each individual Contact object supports only fields valid for its associated list. Its ContactList restricts what fields in a Contact are retained. This reflects that some native Contact databases do not support all of the fields available in a Contact item. The methods {@link AbstractPIMList#isSupportedField} and {@link AbstractPIMList#getSupportedAttributes} can be used to determine if particular Contact fields and types are supported by a ContactList and therefore persisted when the Contact is committed to its list. Attempts to add or get data based on fields not supported in the Contact's ContactList result in a {@link javax.microedition.pim.UnsupportedFieldException}.

Data

The following table details the explicitly defined fields that may by in a Contact. Implementations may extend the field set using extended fields as defined in PIMItem.

Table: Standard Fields

Fields	Type of Data Associated with Field
`NAME, ADDR`	`PIMItem.STRING_ARRAY`
`EMAIL, FORMATTED_NAME, NICKNAME, NOTE, ORG, TEL, TITLE, UID, URL`	`PIMItem.STRING`
`BIRTHDAY, REVISION`	`PIMItem.DATE`
`PHOTO, PUBLIC_KEY`	`PIMItem.BINARY`
`PHOTO_URL, PUBLIC_KEY_STRING`	`PIMItem.STRING`
`CLASS`	`PIMItem.INT`

Required Field Support

All Contact fields may or may not be supported 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 {@link AbstractPIMList#isSupportedField}.

Native Contact 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 Contact by the VM when the Contact is persisted.

Examples

Explicit Field Use with Field Checking

This first example shows explicit field access in which each field 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 Contact.

ContactList contacts = null;
try {
contacts = (ContactList) PIM.getInstance().openPIMList(PIM.CONTACT_LIST,
PIM.READ_WRITE);
} catch (PIMException e) {
// An error occurred
return;
}
Contact contact = contacts.createContact();
String[] addr = new String[contacts.stringArraySize(Contact.ADDR)];
String[] name = new String[contacts.stringArraySize(Contact.NAME)];

if (contacts.isSupportedField(Contact.NAME_FORMATTED)
contact.addString(Contact.NAME_FORMATTED, PIMItem.ATTR_NONE,
"Mr. John Q. Public, Esq.");
if (contacts.isSupportedArrayElement(Contact.NAME, Contact.NAME_FAMILY))
name[Contact.NAME_FAMILY] = "Public";
if (contacts.isSupportedArrayElement(Contact.NAME, Contact.NAME_GIVEN))
name[Contact.NAME_GIVEN] = "John";
contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, name);
if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_COUNTRY))
addr[Contact.ADDR_COUNTRY] = "USA";
if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_LOCALITY))
addr[Contact.ADDR_LOCALITY] = "Coolsville";
if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_POSTALCODE))
addr[Contact.ADDR_POSTALCODE] = "91921-1234";
if (contacts.isSupportedArrayElement(Contact.ADDR, Contact.ADDR_STREET))
addr[Contact.ADDR_STREET] = "123 Main Street";
if (contacts.isSupportedField(Contact.ADDR))
contact.addStringArray(Contact.ADDR, Contact.ATTR_HOME, addr);
if (contacts.isSupportedField(Contact.TEL))
contact.addString(Contact.TEL, Contact.ATTR_HOME, "613-123-4567");
if (contacts.maxCategories() != 0
&& contacts.isCategory("Friends"))
contact.addToCategory("Friends");
if (contacts.isSupportedField(Contact.BIRTHDAY))
contact.addDate(Contact.BIRTHDAY, PIMItem.ATTR_NONE,
new Date().getTime());
if (contacts.isSupportedField(Contact.EMAIL)) {
contact.addString(Contact.EMAIL,
Contact.ATTR_HOME | Contact.ATTR_PREFERRED,
"jqpublic@xyz.dom1.com");
}
try {
contact.commit();
} catch (PIMException e) {
// An error occured
}
try {
contacts.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 Contact is rejected if any of the fields are not supported in the particular list implementation.

ContactList contacts = null;
try {
contacts = (ContactList) PIM.getInstance().openPIMList(PIM.CONTACT_LIST,
PIM.READ_WRITE);
} catch (PIMException e) {
// An error occurred
return;
}
Contact contact = contacts.createContact();

String[] name = new String[contacts.stringArraySize(Contact.NAME)];
name[Contact.NAME_GIVEN] = "John";
name[Contact.NAME_FAMILY] = "Public";

String[] addr = new String[contacts.stringArraySize(Contact.ADDR)];
addr[Contact.ADDR_COUNTRY] = "USA";
addr[Contact.ADDR_LOCALITY] = "Coolsville";
addr[Contact.ADDR_POSTALCODE] = "91921-1234";
addr[Contact.ADDR_STREET] = "123 Main Street";

try {
contact.addString(Contact.NAME_FORMATTED, PIMItem.ATTR_NONE,
"Mr. John Q. Public, Esq.");
contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, name);
contact.addStringArray(Contact.ADDR, Contact.ATTR_HOME, addr);
contact.addString(Contact.TEL, Contact.ATTR_HOME, "613-123-4567");
contact.addToCategory("Friends");
contact.addDate(Contact.BIRTHDAY, PIMItem.ATTR_NONE,
new Date().getTime());
contact.addString(Contact.EMAIL,
Contact.ATTR_HOME | Contact.ATTR_PREFERRED,
"jqpublic@xyz.dom1.com");

} catch (UnsupportedFieldException e) {
// In this case, we choose not to save the contact at all if any of the
// fields are not supported on this platform.
System.out.println("Contact not saved");
return;
}

try {
contact.commit();
} catch (PIMException e) {
// An error occured
}
try {
contacts.close();
} catch (PIMException e) {
}

see: Internet Mail Consortium PDI
see: ContactListImpl
since: PIM 1.0

Fields Summary
public static final int
ADDR
Field specifying an address for this Contact. Data for this field is of STRING_ARRAY type.
public static final int
BIRTHDAY
Field for the birthday of the Contact. Data for this field is expressed in the same long value format as java.util.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 Contact database only support contact date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.
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 {@link #CLASS_PRIVATE}, {@link #CLASS_PUBLIC}, or {@link #CLASS_CONFIDENTIAL}.
public static final int
EMAIL
Field for an e-mail address. Data for this field is of String type.
public static final int
FORMATTED_ADDR
Field represents a formatted version of a complete address for the Contact entry. This string is typically a single string containing the complete address separated with CRLF separators. This field is typically present for contact databases that support only one field for a contact's address, or for specifying address label format. Data for this field is of STRING type. For example:
"123 Main St. Anytown, CA 99999 USA"
public static final int
FORMATTED_NAME
Field represents a formatted version of a name for the Contact entry. Data for this field is of STRING type. The string data associated with this field conforms to the X.520 Common Name attribute format. For example:
"Mr. John Q. Public, Esq."
public static final int
NAME
Field specifying the name for this contact. Data for this field is of STRING_ARRAY type.
public static final int
NICKNAME
Field where the data represents a nickname. Data for this field is of STRING type. For example:
"Copier Man"
public static final int
NOTE
Field specifying supplemental information or a comment associated with a Contact. Data for this field is of String type. The data associated with this field follows the X.520 Description data format. For example:
"The fax number is operational 0800 to 1715 EST, Mon-Fri."
public static final int
ORG
Field specifying the organization name or units associated with a Contact. Data for this field is of String type. The data associated with this field is based on the X.520 Organization data format. For example:
"ABC Inc."
public static final int
PHOTO
Field specifying a photo for a Contact. Data associated with this field is inline binary. Manipulation of this field may affect data stored in the PHOTO_URL field since some implementation may use the same memory for both fields (e.g. one can either have PHOTO or have PHOTO_URL but not both).
public static final int
PHOTO_URL
Field specifying a photo of a Contact. Data associated with this field is of String type, representing a URL for the photo. Manipulation of this field may affect data stored in the PHOTO field since some implementation may use the same memory for both fields (e.g. one can either have PHOTO or have PHOTO_URL but not both).
public static final int
PUBLIC_KEY
Field specifying the public encryption key for a Contact. Data associated with this field is inline binary encoded data. Manipulation of this field may affect data stored in the PUBLIC_KEY_STRING field since some implementation may use the same memory for both fields (e.g. one can either have PUBLIC_KEY or have PUBLIC_KEY_STRING but not both).
public static final int
PUBLIC_KEY_STRING
Field specifying the public encryption key for a Contact. Data associated with this field is of String type. Manipulation of this field may affect data stored in the PUBLIC_KEY field since some implementation may use the same memory for both fields (e.g. one can either have PUBLIC_KEY or have PUBLIC_KEY_STRING but not both).
public static final int
REVISION
Field specifying the last modification date and time of a Contact item. If the Contact has ever been committed to a ContactList, then this attribute becomes read only. This field is set automatically on imports and commits of a Contact. Data for this field is expressed in the same long value format as java.util.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 Contact database only support contact date values with granularity in terms of seconds, then the provided date value is rounded down to a date time with a full second.
public static final int
TEL
Field for a voice telephone number. Data associated with this field is of String type and can be any valid String. No telephone formatting is enforced since many native implementations allow free form text to be associated with TEL fields.
public static final int
TITLE
Field specifying the job title for a Contact. Data for this field is of String type. This title is based on the X.520 Title attributes. For example:
"Director, Research and Development"
public static final int
UID
Field specifying a unique ID for a Contact. This field can be used to check for identity using String.equals. UID is read only if the Contact has been committed to a ContactList at least once in its lifetime. The UID is not set if the Contact has never been committed to a ContactList; countValues(UID) returns 0 before a newly created Contact object is committed to its list. The attribute is valid for the persistent life of the Contact and may be reused by the platform once this particular Contact is deleted. Data for this field is of String data type.
public static final int
URL
Field specifying the uniform resource locator for a Contact. Data for this field is of String data type. For example:
"http://www.swbyps.restaurant.french/~chezchic.html"
public static final int
ATTR_ASST
Attribute classifying a data value as related to an ASSISTANT.
public static final int
ATTR_AUTO
Attribute classifying a data value as related to AUTO.
public static final int
ATTR_FAX
Attribute classifying a data value as related to FAX.
public static final int
ATTR_HOME
Attribute classifying a data value as related to HOME.
public static final int
ATTR_MOBILE
Attribute classifying a data value as related to MOBILE.
public static final int
ATTR_OTHER
Attribute classifying a data value as "OTHER".
public static final int
ATTR_PAGER
Attribute classifying a data value as related to PAGER.
public static final int
ATTR_PREFERRED
Attribute classifying a data value with preferred status for retrieval or display purposes (platform specific). Only one value in a field may be marked as preferred. Subsequent assigning of preferred status to values in a field overrides any previous preferred status indications.
public static final int
ATTR_SMS
Attribute classifying a data value as related to SMS.
public static final int
ATTR_WORK
Attribute classifying a data value as related to WORK.
public static final int
ADDR_POBOX
Index into the string array for an address field, where the data at this index represents the post office box of a particular address. Data for this field is of String type.
public static final int
ADDR_EXTRA
Index into the string array for an address field, where the data at this index represents any extra info of a particular address. Data for this field is of String type.
public static final int
ADDR_STREET
Index into the string array for an address field, where the data at this index represents the street information of a particular address. Data for this field is of String type.
public static final int
ADDR_LOCALITY
Index into the string array for an address field, where the data at this index represents the locality (for example, a city) of a particular address. Data for this field is of String type.
public static final int
ADDR_REGION
Index into the string array for an address field, where the data at this index represents the region (for example, a province, state, or territory) of a particular address. Data for this field is of String type.
public static final int
ADDR_POSTALCODE
Index into the string array for an address field, where the data at this index represents the postal code (for example, a zip code) of a particular address. Data for this field is of String type.
public static final int
ADDR_COUNTRY
Index into the string array for an address field, where the data at this index represents the country of a particular address. Data for this field is of String type.
public static final int
NAME_FAMILY
Index into the string array for a name field, where the data at this index represents the family name. For example:
"Stevenson"
public static final int
NAME_GIVEN
Index into the string array for a name field, where the data at this index represents the given name. For example:
"Johnathan"
public static final int
NAME_OTHER
Index into the string array for a name field, where the data at this index represents other alternate name or names. For example:
"John, Johnny"
public static final int
NAME_PREFIX
Index into the string array for a name field, where the data at this index represents a prefix to a name. For example:
"Dr."
public static final int
NAME_SUFFIX
Index into the string array for a name field, where the data at this index represents a suffix to a name. For example:
"M.D., A.C.P."
public static final int
CLASS_CONFIDENTIAL
Constant indicating this contact's class of access is confidential.
public static final int
CLASS_PRIVATE
Constant indicating this contact's class of access is private.
public static final int
CLASS_PUBLIC
Constant indicating this contact's class of access is public.
Constructors Summary
Methods Summary