PDAP Public Review Draft

javax.microedition.pim
Interface Contact

All Superinterfaces:
PIMElement

public interface Contact
extends PIMElement

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 IETF vCard 3.0 specification [RFC 2426]. 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 field IDs 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 element. The methods PIMList.isSupportedField(int) and PIMList.getSupportedTypes(int) can be used to determine if a particular Contact field is supported by a ContactList and therefore persisted when the Contact is committed to its list. Attempts to set or get data based on field IDs not supported in the Contact's ContactList result in a PIMException.

Data

A contact contains three types of data:

Named fields are items that are referenced by the explicit field names defined in this class. Named fields appear only once in a single Contact entry. The data items for fields are only retrieved and set by the get/set methods corresponding to the type of the data associated with the named field (e.g. PIMElement.getString(int) and PIMElement.setString(int, String) are used for Contact.FORMATTED_NAME since a String value is associated with formatted names).

Some named fields also have a further defining type ID associated with them. This allows for the appearance of more than one instance of a field. For instance, a contact entry may have more than one telephone number by storing mulitple phone numbers with different type IDs (e.g. for the Contact.TEL field ID, use different type ids such as Contact.TYPE_HOME and Contact.TYPE_WORK. The specific combination of field and type ID must only appear once in the Contact entry (e.g. only one Work phone number may be present in the Contact entry).

Extended fields are fields that does not have a specific field explicitly predefined in the API, but do have field ids assigned by the contact list. These fields are implementation dependent and can vary. Users can find out a field id is is extended field through the method PIMList.isExtendedField(int). Users can also find out the data type for the field (PIMElement.getFieldDataType(int)) and the human readable label for the field (PIMElement.getFieldLabel(int)). Extended fields use the same get and set methods as named fields.

Categories are string items. There is no limit to the number of categories that a Contact can be associated with.

Table: Named Fields

Field IDs Allowed Type IDs Type of Data Associated with Field
FORMATTED_NAME, NAME_FAMILY, NAME_GIVEN, NAME_OTHER, NAME_PREFIX, NAME_SUFFIX, NICKNAME, NOTE, ORG, TITLE, UID, URL - PIMElement.STRING
BIRTHDAY, REVISION - PIMElement.DATE
PHOTO, PUBLIC_KEY - PIMElement.BINARY or PIMElement.STRING
EMAIL, FAX, TEL TYPE_ASSISTANT, TYPE_AUTO, TYPE_HOME, TYPE_MOBILE, TYPE_OTHER, TYPE_PAGER, TYPE_WORK PIMElement.TYPED_STRING
ADDR_COUNTRY, ADDR_EXTRA, ADDR_LOCALITY, ADDR_POBOX, ADDR_POSTALCODE, ADDR_REGION, ADDR_STREET TYPE_HOME, TYPE_OTHER, TYPE_WORK PIMElement.TYPED_STRING

Note that the FORMATTED_NAME field and the NAME_FAMILY, NAME_GIVEN, NAME_OTHER, NAME_PREFIX and NAME_SUFFIX fields may be related in some Contact implementations. In other words, some implementations may intepret or store the FORMATTED_NAME field in such a way that associating data with the FORMATTED_NAME field changes the associated values in NAME_FAMILY, NAME_GIVEN, NAME_OTHER, NAME_PREFIX, or NAME_SUFFIX.

Required Field Support

FORMATTED_NAME is the only field that is required to be supported in a Contact and its List. All other fields may or may not be required by the list. Support for all fields can be determined by the method PIMList.isSupportedField(int).

Inherited Method Behavior

Examples

  ContactList contacts = null;
  try {
      contacts = PIM.openContactList(PIM.READ_WRITE);
  } catch (PIMException e) {
      // An error occurred
      return;
  }
  Contact contact = contacts.createContact();
  contact.setString(Contact.FORMATTED_NAME, "Mr. John Q. Public\, Esq");
  contact.setString(Contact.NAME_FAMILY, "Public");
  contact.setString(Contact.NAME_GIVEN, "John");
  contact.setString(Contact.TEL, Contact.TYPE_HOME, "613-123-4567");
  contact.setString(Contact.ADDR_COUNTRY, Contact.TYPE_HOME, "USA");
  contact.setString(Contact.ADDR_LOCALITY, Contact.TYPE_HOME, "Coolsville");
  contact.setString(Contact.ADDR_POSTALCODE, Contact.TYPE_HOME, "91921-1234");
  contact.setString(Contact.ADDR_STREET, Contact.TYPE_HOME, "123 Main Street");
  contact.addToCategory("Friends");
  contact.setDate(Contact.BIRTHDAY, new Date().getTime());
  contact.setString(Contact.EMAIL, Contact.TYPE_HOME, "jqpublic@xyz.dom1.com");
  contact.setPreferredType(Contact.EMAIL, Contact.TYPE_HOME);
  try {
      contact.commit();
  } catch (PIMException e) {
      // An error occured
  }
  try {
      contacts.close();
  } catch (PIMException e) {
  }
 

Since:
PDAP 1.0
See Also:
http://www.imc.org/pdi, ContactList

Field Summary
static int ADDR_COUNTRY
          Field ID for the country of a particular address.
static int ADDR_EXTRA
          Field ID for the extra info of a particular address.
static int ADDR_LOCALITY
          Field ID for the locality (for example, a city) of a particular address.
static int ADDR_POBOX
          Field ID for the post office box of a particular address.
static int ADDR_POSTALCODE
          Field ID for the postal code (for example, a zip code) of a particular address.
static int ADDR_REGION
          Field ID for the region (for example, a province, state, or territory) of a particular address.
static int ADDR_STREET
          Field ID for the street information of a particular address.
static int BIRTHDAY
          Field ID for the birthday of the Contact.
static int EMAIL
          Field ID for an e-mail address.
static int FAX
          Field ID for a facsimile machine telephone number.
static int FORMATTED_NAME
          Field ID for data corresponding to the name of the Contact.
static int NAME_FAMILY
          Field ID for the family name of the Contact.
static int NAME_GIVEN
          Field ID for the given name of the Contact.
static int NAME_OTHER
          Field ID for another name for the Contact.
static int NAME_PREFIX
          Field ID for a name prefix for the Contact.
static int NAME_SUFFIX
          Field ID for a name suffix for the Contact.
static int NICKNAME
          Field ID corresponding to the Nickname of the contact.
static int NOTE
          Field ID specifying supplemental information or a comment associated with a Contact.
static int ORG
          Field ID specifying the organization name or units associated with a Contact.
static int PHOTO
          Field ID specifying the photo of a Contact.
static int PUBLIC_KEY
          Field ID specifying the public encryption key for a Contact.
static int REVISION
          Field ID specifying the last modification time of a Contact.
static int TEL
          Field ID for a voice telephone number.
static int TITLE
          Field ID specifying the job title for a Contact.
static int TYPE_ASSISTANT
          Type "assistant" for TEL, FAX and EMAIL entries.
static int TYPE_AUTO
          Type "auto" for TEL, FAX and EMAIL entries.
static int TYPE_HOME
          Type "home" for ADDR_*, TEL, FAX and EMAIL entries.
static int TYPE_MOBILE
          Type "mobile" for TEL, FAX and EMAIL entries.
static int TYPE_OTHER
          Type "other" for ADDR_*, TEL, FAX and EMAIL entries.
static int TYPE_PAGER
          Type "pager" for TEL, FAX and EMAIL entries.
static int TYPE_WORK
          Type "work" for ADDR_*, TEL, FAX and EMAIL entries.
static int UID
          Field ID specifying a unique ID for a Contact.
static int URL
          Field ID specifying the uniform resource locator for a Contact.
 
Fields inherited from interface javax.microedition.pim.PIMElement
BINARY, DATE, INT, STRING, TYPED_STRING
 
Method Summary
 int getPreferredType(int fieldID)
          Returns the preferred type ID for the given field, as set by setPreferredType.
 void setPreferredType(int fieldID, int typeID)
          Sets the preferred type for the given field.
 
Methods inherited from interface javax.microedition.pim.PIMElement
addToCategory, commit, fromSerialFormat, getBinary, getCategories, getDate, getFieldDataType, getFieldLabel, getFields, getInt, getPIMList, getString, getTypedString, isModified, maxCategories, removeFromCategory, setBinary, setDate, setInt, setString, setTypedString, supportedSerialVersions, toSerialFormat, toSerialFormat
 

Field Detail

ADDR_COUNTRY

public static final int ADDR_COUNTRY
Field ID for the country of a particular address.

Value 1 is assigned to ADDR_COUNTRY.


ADDR_EXTRA

public static final int ADDR_EXTRA
Field ID for the extra info of a particular address.

Value 2 is assigned to ADDR_EXTRA.


ADDR_LOCALITY

public static final int ADDR_LOCALITY
Field ID for the locality (for example, a city) of a particular address.

Value 3 is assigned to ADDR_LOCALITY.


ADDR_POBOX

public static final int ADDR_POBOX
Field ID for the post office box of a particular address.

Value 4 is assigned to ADDR_POBOX.


ADDR_POSTALCODE

public static final int ADDR_POSTALCODE
Field ID for the postal code (for example, a zip code) of a particular address.

Value 5 is assigned to ADDR_POSTALCODE.


ADDR_REGION

public static final int ADDR_REGION
Field ID for the region (for example, a province, state, or territory) of a particular address.

Value 6 is assigned to ADDR_REGION.


ADDR_STREET

public static final int ADDR_STREET
Field ID for the street information of a particular address.

Value 7 is assigned to ADDR_STREET.


TEL

public static final int TEL
Field ID for a voice telephone number.

Value 8 is assigned to TEL.


FAX

public static final int FAX
Field ID for a facsimile machine telephone number.

Value 9 is assigned to FAX.


EMAIL

public static final int EMAIL
Field ID for an e-mail address.

Value 10 is assigned to EMAIL.


BIRTHDAY

public static final int BIRTHDAY
Field ID for the birthday of the Contact.

Value 11 is assigned to BIRTHDAY.


FORMATTED_NAME

public static final int FORMATTED_NAME
Field ID for data corresponding to the name of the Contact. The string data associated with this field conforms to the X.520 Common Name attribute format. For example:
"Mr. John Q. Public\, Esq."

Value 12 is assigned to FORMATTED_NAME.


NAME_FAMILY

public static final int NAME_FAMILY
Field ID for the family name of the Contact. For example:
"Stevenson"

Value 13 is assigned to NAME_FAMILY.


NAME_GIVEN

public static final int NAME_GIVEN
Field ID for the given name of the Contact. For example:
"John"

Value 14 is assigned to NAME_GIVEN.


NAME_OTHER

public static final int NAME_OTHER
Field ID for another name for the Contact. For example:
"Philip,Paul"

Value 15 is assigned to NAME_OTHER.


NAME_PREFIX

public static final int NAME_PREFIX
Field ID for a name prefix for the Contact. For example:
"Dr."

Value 16 is assigned to NAME_PREFIX.


NAME_SUFFIX

public static final int NAME_SUFFIX
Field ID for a name suffix for the Contact. For example:
"M.D., A.C.P."

Value 17 is assigned to NAME_SUFFIX.


NICKNAME

public static final int NICKNAME
Field ID corresponding to the Nickname of the contact. For example:
"Copier Man"

Value 18 is assigned to NICKNAME.


NOTE

public static final int NOTE
Field ID specifying supplemental information or a comment associated with a Contact. 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."

Value 19 is assigned to NOTE.


ORG

public static final int ORG
Field ID specifying the organization name or units associated with a Contact. The data associated with this field is based on the X.520 Organization data format. For example:
"ABC Inc."

Value 20 is assigned to ORG.


TITLE

public static final int TITLE
Field ID specifying the job title for a Contact. This title is based on the X.520 Title attributes. For example:
"Director, Research and Development"

Value 21 is assigned to TITLE.


PUBLIC_KEY

public static final int PUBLIC_KEY
Field ID specifying the public encryption key for a Contact. Data associated with this field can be either of String type or inline binary. The method PIMElement.getFieldDataType(int) should be used to determine the type of the data associated with this field.

Value 22 is assigned to PUBLIC_KEY.


URL

public static final int URL
Field ID specifying the uniform resource locator for a Contact. For example:
"http://www.swbyps.restaurant.french/~chezchic.html"

Value 23 is assigned to URL.


UID

public static final int UID
Field ID specifying a unique ID for a Contact. This field can be used to check for identity. This is a read only attribute. The UID is valid only after the Contact is added to a Contact list and is valid for the persistent life of the Contact. Once the Contact is deleted from the list, the UID may be reused for other Contacts. getString(UID) returns null before the Contact object is added to a list.

Value 24 is assigned to UID.


REVISION

public static final int REVISION
Field ID specifying the last modification time of a Contact. This field cannot be set through the API (e.g. is read-only). This field is set automatically on adds and updates of a Contact.

Value 25 is assigned to REVISION.


PHOTO

public static final int PHOTO
Field ID specifying the photo of a Contact. Data associated with this field can be either of String type (for a URL) or inline binary. The method PIMElement.getFieldDataType(int) should be used to determine the type of the data associated with this field.

Value 26 is assigned to PHOTO.

See Also:
PIMList.isSupportedField(int)

TYPE_OTHER

public static final int TYPE_OTHER
Type "other" for ADDR_*, TEL, FAX and EMAIL entries. This is for address, telephone, fax, and e-mail entries that have no specific association assigned to them. This is the default type for those fields that have no type specified.

Value 256 is assigned to TYPE_OTHER.


TYPE_HOME

public static final int TYPE_HOME
Type "home" for ADDR_*, TEL, FAX and EMAIL entries.

Value 257 is assigned to .


TYPE_WORK

public static final int TYPE_WORK
Type "work" for ADDR_*, TEL, FAX and EMAIL entries.

Value 258 is assigned to TYPE_WORK.


TYPE_MOBILE

public static final int TYPE_MOBILE
Type "mobile" for TEL, FAX and EMAIL entries.

Value 259 is assigned to TYPE_MOBILE.


TYPE_PAGER

public static final int TYPE_PAGER
Type "pager" for TEL, FAX and EMAIL entries.

Value 260 is assigned to TYPE_PAGER.


TYPE_AUTO

public static final int TYPE_AUTO
Type "auto" for TEL, FAX and EMAIL entries.

Value 261 is assigned to TYPE_AUTO.


TYPE_ASSISTANT

public static final int TYPE_ASSISTANT
Type "assistant" for TEL, FAX and EMAIL entries.

Value 262 is assigned to TYPE_ASSISTANT.

Method Detail

getPreferredType

public int getPreferredType(int fieldID)
                     throws PIMException
Returns the preferred type ID for the given field, as set by setPreferredType.
Parameters:
fieldID - the field ID to find the preferred type for
Throws:
java.lang.IllegalArgumentException - if fieldID is not a valid field ID for a Contact
PIMException - if the field ID does not have types associated with it.

setPreferredType

public void setPreferredType(int fieldID,
                             int typeID)
                      throws PIMException
Sets the preferred type for the given field.
Parameters:
fieldID - the field ID to set the preferred type for
typeID - the type ID to be the default for field ID. The type ID must be one of TYPE_*.
Throws:
java.lang.IllegalArgumentException - if fieldID is not a valid field ID for a Contact or typeID is not a value Contact type ID.
PIMException - if the typeID is not a valid type ID for the given field ID, or data for the given fieldID/typeID combination does not exist in the Contact.

PDAP 1.0 Spec, Rev. 0.16