javax.microedition.pim
Interface Contact

All Superinterfaces:
PIMItem
All Known Subinterfaces:
BlackBerryContact

public interface Contact
extends PIMItem

Represents a PIM contact.

A PIM contact consists of the fields, such as phone number, and address, that represent the personal information of a contact.

While the Contact object contains support for many different fields, the fields supported by a given instance of a Contact object are defined in the ContactList object associated with the contact. The ContactList restricts which fields are retained by a Contact database. If a ContactList encounters a Contact object that contains unsupported fields, those fields are dropped.

The PIMList.isSupportedField(int) is invoked to determine if a field (as specified by the integer argument) is supported by a ContactList. Similarly, the PIMList.getSupportedAttributes(int) method is invoked to return an integer array representing all fields supported by the list.

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.

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

Working with the Contact object

The following examples demonstrate how to use the Contact object.

Adding data to a Contact

Before adding data to a contact, invoke ContactList.IsSupportedField() to check that the field you are adding is supported by the list. If you try to add data to a field that does not exist, a PIMException is thrown.

                  
 ContactList contactList = (ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.WRITE_ONLY);
 if (contactList.isSupportedField(Contact.NAME)) {
     Contact contact = contactList.createContact();
     String[] name = new String[ contactList.stringArraySize( Contact.NAME ) ];
     name[Contact.NAME_GIVEN] = "Kate";
     name[Contact.NAME_FAMILY] = "Turner";
     contact.addStringArray(Contact.NAME, Contact.ATTR_NONE, name);
     contact.commit();
     return true;
 }  else {
     return false;
 } 
 

Similarly, to add a new attribute to a contact, invoke ContactList.isSupportedAttribute() to check that the attribute is supported by the field. If a specified field or attribute are not supported, an PIMException is thrown.

Updating data in an existing Contact

The previous example added new data to an empty field. Since you can not add data to a field that already contains data, invoke countValues() to determine whether the field is empty. If the field is not empty, invoke removeValue() to remove the data from the field.


       String[] name = new String[contactList.stringArraySize(Contact.NAME)];
       if (contact.countValues(Contact.NAME) > 0) {
         contact.removeValue(Contact.NAME, 0);
       }
       name[Contact.NAME_GIVEN] = "Kate";
       name[Contact.NAME_FAMILY] = "Turner";
       contact.addStringArray(Contact.NAME, PIMItem.ATTR_NONE, name);

Removing a contact

To remove a Contact, invoke removeContact(). The following example removes a contact from a contact list:


    contactList.removeContact(contact);
 

Saving a Contact object

The commit() method must be used to save the object to a list. In the following example, isModified() is called to determine whether the contact's information has been modified. If so, commit() method is invoked and the contact is saved.


     if(contact.isModified()) {
        contact.commit();
      }
 

RIM Implementation Notes

PHOTO Field

The PHOTO field, which is supported by RIM's implementation, is a binary field whose value is the bytes of the image to use for the contact's photo. Supported image formats are those supported by EncodedImage.

Note that the javadocs for addBinary(), setBinary(), and getBinary() all state that the binary data must be encoded "in a "B" binary encoded string as defined by [IETF RFC 2047]". This means that the photo data returned from getBinary() will be Base64-encoded. Also, data may be specified to setBinary() and addBinary() in either raw bytes or Base64-encoded; if raw bytes are specified then they are converted to Base64. To encode or decode Base64 data you may use Base64OutputStream or Base64InputStream, respectively.

Also note that in addBinary() and setBinary() the offset and length parameters apply to the unencoded array and not the encoded array. Therefore, addBinary() and setBinary() decode the entire Base64 data and then apply the offset and length to get a subset of the data.

The code below shows how to work with the PHOTO field using Base64 encoding. Note the invocations of addBinary() and setBinary() that specify the length of the unencoded array.

     import java.io.IOException;
     import javax.microedition.pim.Contact;
     import javax.microedition.pim.ContactList;
     import javax.microedition.pim.PIM;
     import javax.microedition.pim.PIMException;
     import javax.microedition.pim.PIMItem;
     import net.rim.device.api.io.Base64InputStream;
     import net.rim.device.api.io.Base64OutputStream;
     
     public class PhotoExample {
     
         private Contact _contact;
     
         public PhotoExample() throws PIMException {
             ContactList contactList = (ContactList) 
                 PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
             _contact = contactList.createContact();
         }
     
         public void setPhoto() throws IOException {
             byte[] photo = getSamplePhoto();
             byte[] photoEncoded = Base64OutputStream.encode(photo, 0, photo.length, false, false);
             if (_contact.countValues(Contact.PHOTO) > 0) {
                 _contact.setBinary(Contact.PHOTO, 0, PIMItem.ATTR_NONE, photoEncoded, 0, photo.length);
             } else {
                 _contact.addBinary(Contact.PHOTO, PIMItem.ATTR_NONE, photoEncoded, 0, photo.length);
             }
         }
     
         public byte[] getPhoto() throws IOException {
             if (_contact.countValues(Contact.PHOTO) > 0) {
                 byte[] photoEncoded = _contact.getBinary(Contact.PHOTO, 0);
                 return Base64InputStream.decode(photoEncoded, 0, photoEncoded.length);
             } else {
                 return null;
             }
         }
     
         private static byte[] getSamplePhoto() {
             // return the raw bytes of the photo to use
         }
     
         public static void main(String[] args) throws Throwable {
             PhotoExample example = new PhotoExample();
             example.setPhoto();
             example.getPhoto();
         }
     
     }
 

More Information

See BlackBerryContact for more information on the behavior of Contacts on RIM devices.
For more information about this class or about the personal information management (PIM) API, see The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

Since:
JDE 4.0.0
See Also:
ContactList

Field Summary
static int ADDR
          Represents the address of the contact.
static int ADDR_COUNTRY
          Represents the country field of the contact's address array.
static int ADDR_EXTRA
          Represents an extra field of the contact's address array.
static int ADDR_LOCALITY
          Represents the locality (for example, city) field of the contact's address array.
static int ADDR_POBOX
          Represents the post office box number field of the contact's address array.
static int ADDR_POSTALCODE
          Represents the postal code field of the contact's address array.
static int ADDR_REGION
          Represents the region (for example, state or province) field of the contact's address array.
static int ADDR_STREET
          Represents the street address field of the contact's address.
static int ATTR_ASST
          Represents the information (usually name or phone number) of a contact's assistant.
static int ATTR_AUTO
          Represents the automobile phone number of a contact.
static int ATTR_FAX
          Represents the fax number of a contact.
static int ATTR_HOME
          Represents the home phone number of a contact.
static int ATTR_MOBILE
          Represents the mobile phone number of a contact.
static int ATTR_OTHER
          Represents an "other" field for a contact.
static int ATTR_PAGER
          Represents a pager number for a contact.
static int ATTR_PREFERRED
          Indicates that a field is the preferred attribute for a contact.
static int ATTR_SMS
          Represents the SMS address of a contact.
static int ATTR_WORK
          Represents the work phone number of a contact.
static int BIRTHDAY
          Represents the birthday field of the contact.
static int CLASS
          Field specifying the class of this contact.
static int CLASS_CONFIDENTIAL
          Represents the constant for the "confidential" access class.
static int CLASS_PRIVATE
          Represents the constant for the "private" access class.
static int CLASS_PUBLIC
          Represents the constant for the "public" access class.
static int EMAIL
          Represents the contact's email address field(s).
static int FORMATTED_ADDR
          Represents the contact's formatted address.
static int FORMATTED_NAME
          Represents the contact's formatted name.
static int NAME
          Represents the contact's name.
static int NAME_FAMILY
          Represents the family name of the contact's name array.
static int NAME_GIVEN
          Represents the given name of the contact's name array.
static int NAME_OTHER
          Represents another name for the contact's name array.
static int NAME_PREFIX
          Represents a prefix, for example Mr. or Dr., of the contact's name array.
static int NAME_SUFFIX
          Represents a suffix, for example a degree, for the contact's name array.
static int NICKNAME
          Represents the contact's nick name.
static int NOTE
          Represents a field used to store a note about the contact.
static int ORG
          Represents the name of a contact's organization.
static int PHOTO
          Represents a photo for the contact.
static int PHOTO_URL
          Represents a string URL to a photo of the contact.
static int PUBLIC_KEY
          Represents the public key of the contact.
static int PUBLIC_KEY_STRING
          Contains a string representation of the contact's public key.
static int REVISION
          Represents the last date and time that this contact's information was modified.
static int TEL
          Represents the contact's telephone number.
static int TITLE
          Represents the contact's title, for example Vice President.
static int UID
          Represents a Contact's unique ID.
static int URL
          Represents a uniform resource locator (URL) to a website.
 
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 number of the preferred 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
Represents the address of the contact.
Since:
JDE 4.0.0

ADDR_COUNTRY

public static final int ADDR_COUNTRY
Represents the country field of the contact's address array.
Since:
JDE 4.0.0

ADDR_EXTRA

public static final int ADDR_EXTRA
Represents an extra field of the contact's address array.
Since:
JDE 4.0.0

ADDR_LOCALITY

public static final int ADDR_LOCALITY
Represents the locality (for example, city) field of the contact's address array.
Since:
JDE 4.0.0

ADDR_POBOX

public static final int ADDR_POBOX
Represents the post office box number field of the contact's address array.
Since:
JDE 4.0.0

ADDR_POSTALCODE

public static final int ADDR_POSTALCODE
Represents the postal code field of the contact's address array.
Since:
JDE 4.0.0

ADDR_REGION

public static final int ADDR_REGION
Represents the region (for example, state or province) field of the contact's address array.
Since:
JDE 4.0.0

ADDR_STREET

public static final int ADDR_STREET
Represents the street address field of the contact's address.
Since:
JDE 4.0.0

ATTR_ASST

public static final int ATTR_ASST
Represents the information (usually name or phone number) of a contact's assistant.
Since:
JDE 4.0.0

ATTR_AUTO

public static final int ATTR_AUTO
Represents the automobile phone number of a contact.
Since:
JDE 4.0.0

ATTR_FAX

public static final int ATTR_FAX
Represents the fax number of a contact.
Since:
JDE 4.0.0

ATTR_HOME

public static final int ATTR_HOME
Represents the home phone number of a contact.
Since:
JDE 4.0.0

ATTR_MOBILE

public static final int ATTR_MOBILE
Represents the mobile phone number of a contact.
Since:
JDE 4.0.0

ATTR_OTHER

public static final int ATTR_OTHER
Represents an "other" field for a contact.
Since:
JDE 4.0.0

ATTR_PAGER

public static final int ATTR_PAGER
Represents a pager number for a contact.
Since:
JDE 4.0.0

ATTR_PREFERRED

public static final int ATTR_PREFERRED
Indicates that a field is the preferred attribute for a contact.

This attribute will be used for retrieval and display. Only one field can be designated as preferred. The getPreferredIndex(int) method returns the index of the preferred attribute.

Since:
JDE 4.0.0

ATTR_SMS

public static final int ATTR_SMS
Represents the SMS address of a contact.
Since:
JDE 4.0.0

ATTR_WORK

public static final int ATTR_WORK
Represents the work phone number of a contact.
Since:
JDE 4.0.0

BIRTHDAY

public static final int BIRTHDAY
Represents the birthday field of the contact.
Since:
JDE 4.0.0

CLASS

public static final int CLASS
Field specifying the class of this contact.

One of CLASS_PRIVATE, CLASS_PUBLIC, or CLASS_CONFIDENTIAL.

Since:
JDE 4.0.0

CLASS_CONFIDENTIAL

public static final int CLASS_CONFIDENTIAL
Represents the constant for the "confidential" access class.
Since:
JDE 4.0.0

CLASS_PRIVATE

public static final int CLASS_PRIVATE
Represents the constant for the "private" access class.
Since:
JDE 4.0.0

CLASS_PUBLIC

public static final int CLASS_PUBLIC
Represents the constant for the "public" access class.
Since:
JDE 4.0.0

EMAIL

public static final int EMAIL
Represents the contact's email address field(s).
Since:
JDE 4.0.0

FORMATTED_ADDR

public static final int FORMATTED_ADDR
Represents the contact's formatted address.

The formatted address consists of the various fields that make up an address.

Since:
JDE 4.0.0

FORMATTED_NAME

public static final int FORMATTED_NAME
Represents the contact's formatted name.

The formatted name represents the fields that make up a full name.

Since:
JDE 4.0.0

NAME

public static final int NAME
Represents the contact's name.
Since:
JDE 4.0.0

NAME_FAMILY

public static final int NAME_FAMILY
Represents the family name of the contact's name array.

Since:
JDE 4.0.0

NAME_GIVEN

public static final int NAME_GIVEN
Represents the given name of the contact's name array.

Since:
JDE 4.0.0

NAME_OTHER

public static final int NAME_OTHER
Represents another name for the contact's name array.

For example, the contact's middle name.

Since:
JDE 4.0.0

NAME_PREFIX

public static final int NAME_PREFIX
Represents a prefix, for example Mr. or Dr., of the contact's name array.

Since:
JDE 4.0.0

NAME_SUFFIX

public static final int NAME_SUFFIX
Represents a suffix, for example a degree, for the contact's name array.

Since:
JDE 4.0.0

NICKNAME

public static final int NICKNAME
Represents the contact's nick name.
Since:
JDE 4.0.0

NOTE

public static final int NOTE
Represents a field used to store a note about the contact.

The data associated with this field conforms to the X.520 Description data format.

Since:
JDE 4.0.0

ORG

public static final int ORG
Represents the name of a contact's organization.

Since:
JDE 4.0.0

PHOTO

public static final int PHOTO
Represents a photo for the contact.

The photo is stored in inline binary format and is directly related to the PHOTO_URL field.

For details about the PHOTO field please see the RIM Implementation Notes.

Since:
JDE 4.0.0

PHOTO_URL

public static final int PHOTO_URL
Represents a string URL to a photo of the contact.

The photo URL is stored in the same memory location as the photo.

Since:
JDE 4.0.0

PUBLIC_KEY

public static final int PUBLIC_KEY
Represents the public key of the contact.

Manipulation of this field may affect data stored in the PUBLIC_KEY_STRING field since both are stored in the same memory location.

Since:
JDE 4.0.0

PUBLIC_KEY_STRING

public static final int PUBLIC_KEY_STRING
Contains a string representation of the contact's public key.

Manipulation of this field may affect data stored in the PUBLIC_KEY field since both are stored in the same memory location.

Since:
JDE 4.0.0

REVISION

public static final int REVISION
Represents the last date and time that this contact's information was modified.
Since:
JDE 4.0.0

TEL

public static final int TEL
Represents the contact's telephone number.

This data is stored as a string. Any valid string will be acceptable.

Since:
JDE 4.0.0

TITLE

public static final int TITLE
Represents the contact's title, for example Vice President.

This title is based on the X.520 Title attribute.

Since:
JDE 4.0.0

UID

public static final int UID
Represents a Contact's unique ID.

The unique ID field is valid only if the Contact has been added to a ContactList atleast once in the past. If the Contact has not yet been added to a list, the UID returns Null.

Since:
JDE 4.0.0

URL

public static final int URL
Represents a uniform resource locator (URL) to a website.
Since:
JDE 4.0.0
Method Detail

getPreferredIndex

public int getPreferredIndex(int field)
Returns the index number of the preferred field.

Parameters:
field - The field to check for a preferred value.
Returns:
An integer representing the index of the preferred value. -1 is returned if no value is marked as preferred.
Since:
JDE 4.0.0



Copyright 1999-2008 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.