Java Doc for Contact.java in  » 6.0-JDK-Modules » j2me » com » sun » kvem » midp » pim » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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 AbstractPIMList.isSupportedField and 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 javax.microedition.pim.UnsupportedFieldException .

Data

Table: Standard Fields

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

 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

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

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.

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.