javax.microedition.pim
Interface Contact

All Superinterfaces:

PIMItem

public interface Contact

extends 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 PIMList.isSupportedField(int) and PIMList.getSupportedAttributes(int) 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 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 PIMList.isSupportedField(int).

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, "[email protected]");
 }
 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, "[email protected]");

  } 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) {
  }
 

Since:

PIM 1.0

See Also:

Internet Mail Consortium PDI, ContactList

Field Summary

static int	ADDR Field specifying an address for this Contact.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static 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.
static int	ATTR_ASST Attribute classifying a data value as related to an ASSISTANT.
static int	ATTR_AUTO Attribute classifying a data value as related to AUTO.
static int	ATTR_FAX Attribute classifying a data value as related to FAX.
static int	ATTR_HOME Attribute classifying a data value as related to HOME.
static int	ATTR_MOBILE Attribute classifying a data value as related to MOBILE.
static int	ATTR_OTHER Attribute classifying a data value as "OTHER".
static int	ATTR_PAGER Attribute classifying a data value as related to PAGER.
static int	ATTR_PREFERRED Attribute classifying a data value with preferred status for retrieval or display purposes (platform specific).
static int	ATTR_SMS Attribute classifying a data value as related to SMS.
static int	ATTR_WORK Attribute classifying a data value as related to WORK.
static int	BIRTHDAY Field for the birthday of the Contact.
static int	CLASS Field specifying the desired access class for this contact.
static int	CLASS_CONFIDENTIAL Constant indicating this contact's class of access is confidential.
static int	CLASS_PRIVATE Constant indicating this contact's class of access is private.
static int	CLASS_PUBLIC Constant indicating this contact's class of access is public.
static int	EMAIL Field for an e-mail address.
static int	FORMATTED_ADDR Field represents a formatted version of a complete address for the Contact entry.
static int	FORMATTED_NAME Field represents a formatted version of a name for the Contact entry.
static int	NAME Field specifying the name for this contact.
static int	NAME_FAMILY Index into the string array for a name field, where the data at this index represents the family name.
static int	NAME_GIVEN Index into the string array for a name field, where the data at this index represents the given name.
static int	NAME_OTHER Index into the string array for a name field, where the data at this index represents other alternate name or names.
static int	NAME_PREFIX Index into the string array for a name field, where the data at this index represents a prefix to a name.
static int	NAME_SUFFIX Index into the string array for a name field, where the data at this index represents a suffix to a name.
static int	NICKNAME Field where the data represents a nickname.
static int	NOTE Field specifying supplemental information or a comment associated with a Contact.
static int	ORG Field specifying the organization name or units associated with a Contact.
static int	PHOTO Field specifying a photo for a Contact.
static int	PHOTO_URL Field specifying a photo of a Contact.
static int	PUBLIC_KEY Field specifying the public encryption key for a Contact.
static int	PUBLIC_KEY_STRING Field specifying the public encryption key for a Contact.
static int	REVISION Field specifying the last modification date and time of a Contact item.
static int	TEL Field for a voice telephone number.
static int	TITLE Field specifying the job title for a Contact.
static int	UID Field specifying a unique ID for a Contact.
static int	URL Field specifying the uniform resource locator for a Contact.

Fields inherited from interface javax.microedition.pim.PIMItem

ATTR_NONE, BINARY, BOOLEAN, DATE, EXTENDED_ATTRIBUTE_MIN_VALUE, EXTENDED_FIELD_MIN_VALUE, INT, STRING, STRING_ARRAY

Method Summary

int	getPreferredIndex(int field) Returns the index of the value marked with the attribute ATTR_PREFERRED for the given field.

Methods inherited from interface javax.microedition.pim.PIMItem

addBinary, addBoolean, addDate, addInt, addString, addStringArray, addToCategory, commit, countValues, getAttributes, getBinary, getBoolean, getCategories, getDate, getFields, getInt, getPIMList, getString, getStringArray, isModified, maxCategories, removeFromCategory, removeValue, setBinary, setBoolean, setDate, setInt, setString, setStringArray

Field Detail

ADDR

public static final int ADDR

Field specifying an address for this Contact. Data for this field is of STRING_ARRAY type.

See Also:

Constant Field Values

BIRTHDAY

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.

See Also:

Constant Field Values

CLASS

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 CLASS_PRIVATE, CLASS_PUBLIC, or CLASS_CONFIDENTIAL.

See Also:

Constant Field Values

EMAIL

public static final int EMAIL

Field for an e-mail address. Data for this field is of String type.

See Also:

Constant Field Values

FORMATTED_ADDR

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"

See Also:

Constant Field Values

FORMATTED_NAME

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."

See Also:

Constant Field Values

NAME

public static final int NAME

Field specifying the name for this contact. Data for this field is of STRING_ARRAY type.

See Also:

Constant Field Values

NICKNAME

public static final int NICKNAME

Field where the data represents a nickname. Data for this field is of STRING type. For example:
"Copier Man"

See Also:

Constant Field Values

NOTE

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."

See Also:

Constant Field Values

ORG

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."

See Also:

Constant Field Values

PHOTO

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).

See Also:

PIMList.isSupportedField(int), Constant Field Values

PHOTO_URL

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).

See Also:

PIMList.isSupportedField(int), Constant Field Values

PUBLIC_KEY

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).

See Also:

Constant Field Values

PUBLIC_KEY_STRING

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).

See Also:

Constant Field Values

REVISION

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.

See Also:

Constant Field Values

TEL

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.

See Also:

Constant Field Values

TITLE

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"

See Also:

Constant Field Values

UID

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.

See Also:

Constant Field Values

URL

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"

See Also:

Constant Field Values

ATTR_ASST

public static final int ATTR_ASST

Attribute classifying a data value as related to an ASSISTANT.

See Also:

Constant Field Values

ATTR_AUTO

public static final int ATTR_AUTO

Attribute classifying a data value as related to AUTO.

See Also:

Constant Field Values

ATTR_FAX

public static final int ATTR_FAX

Attribute classifying a data value as related to FAX.

See Also:

Constant Field Values

ATTR_HOME

public static final int ATTR_HOME

Attribute classifying a data value as related to HOME.

See Also:

Constant Field Values

ATTR_MOBILE

public static final int ATTR_MOBILE

Attribute classifying a data value as related to MOBILE.

See Also:

Constant Field Values

ATTR_OTHER

public static final int ATTR_OTHER

Attribute classifying a data value as "OTHER".

See Also:

Constant Field Values

ATTR_PAGER

public static final int ATTR_PAGER

Attribute classifying a data value as related to PAGER.

See Also:

Constant Field Values

ATTR_PREFERRED

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.

See Also:

Constant Field Values

ATTR_SMS

public static final int ATTR_SMS

Attribute classifying a data value as related to SMS.

See Also:

Constant Field Values

ATTR_WORK

public static final int ATTR_WORK

Attribute classifying a data value as related to WORK.

See Also:

Constant Field Values

ADDR_POBOX

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.

See Also:

Constant Field Values

ADDR_EXTRA

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.

See Also:

Constant Field Values

ADDR_STREET

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.

See Also:

Constant Field Values

ADDR_LOCALITY

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.

See Also:

Constant Field Values

ADDR_REGION

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.

See Also:

Constant Field Values

ADDR_POSTALCODE

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.

See Also:

Constant Field Values

ADDR_COUNTRY

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.

See Also:

Constant Field Values

NAME_FAMILY

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"

See Also:

Constant Field Values

NAME_GIVEN

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"

See Also:

Constant Field Values

NAME_OTHER

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"

See Also:

Constant Field Values

NAME_PREFIX

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."

See Also:

Constant Field Values

NAME_SUFFIX

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."

See Also:

Constant Field Values

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL

Constant indicating this contact's class of access is confidential.

See Also:

Constant Field Values

CLASS_PRIVATE

public static final int CLASS_PRIVATE

Constant indicating this contact's class of access is private.

See Also:

Constant Field Values

CLASS_PUBLIC

public static final int CLASS_PUBLIC

Constant indicating this contact's class of access is public.

See Also:

Constant Field Values

Method Detail

getPreferredIndex

public int getPreferredIndex(int field)

Returns the index of the value marked with the attribute ATTR_PREFERRED for the given field. Only one value per field may be marked as preferred. PIMList.isSupportedField(int) should be used to verify the field validity for this item prior to invoking this method. PIMList.isSupportedAttribute(int, int) should be used to verify the attribute validity for this item prior to invoking this method.

Parameters:

field - the field to look for a preferred value

Returns:

an integer representing the index of the value that is marked as preferred. -1 is returned if no values within the field are marked as preferred.

Throws:

java.lang.IllegalArgumentException - if field is not a valid field for a Contact.

UnsupportedFieldException - if the field is not supported by the implementing class.