javax.microedition.pim
Interface ContactList

All Superinterfaces:

PIMList

All Known Subinterfaces:

BlackBerryContactList

public interface ContactList
extends PIMList

Represents a Contact list containing Contact items.

A Contact List is responsible for determining which of the fields from a Contact are retained when a Contact is persisted into the List. A Contact List does not have to retain all of the fields in a Contact when the Contact is persisted into the List. See the Contact interface for a description of the fields in a Contact.

The fields that are supported by a particular Contact List are queried through the methods PIMList.isSupportedField(int) and PIMList.getSupportedAttributes(int). If a field ID that is not in the Contact interface is provided as the parameter to the PIMList.isSupportedField(int) method, a IllegalArgumentException is thrown. The PIMList.isSupportedField(int) method for a Contact List also accepts field type values (e.g. TYPE_* constants) as valid parameters for checking for support.

Inherited Method Behavior

A ContactList only accepts objects implementing the Contact interface as a parameter to PIMList.items(PIMItem). A IllegalArgumentException is thrown by this method if the input parameter does not implement the Contact interface.

Enumerations returned by PIMList.items() and PIMList.items(PIMItem) in a Contact List contain only objects implementing a Contact interface.

RIM Implementation Notes

The RIM extension functionality for Contact Lists are defined in BlackBerryContactList. Any instance of ContactList that is retrieved from PIM.openPIMList() when specified pimListType==PIM.CONTACT_LIST will be an instance of BlackBerryContactList and can be successfully casted to BlackBerryContactList, if desired, in order to use the RIM extension functionality. When a Contact object is created by or retrieved from a BlackBerryContactList then it will necessarily be an instance of BlackBerryContact and will support all RIM extension fields and attributes defined therein.

The PDA Profile specification (JSR-75) for the J2ME(TM) Platform

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.

See Also:

Contact, BlackBerryContactList

Since:

BlackBerry API 4.0.0, PIM 1.0

Field Summary

Fields inherited from interface javax.microedition.pim.PIMList

UNCATEGORIZED

Method Summary
Contact	createContact() Factory method to create a Contact for this contact list.
Contact	importContact(Contact contact) Imports the given Contact into this contact list.
void	removeContact(Contact contact) Removes a Contact from this list.

Methods inherited from interface javax.microedition.pim.PIMList

addCategory, close, deleteCategory, getArrayElementLabel, getAttributeLabel, getCategories, getFieldDataType, getFieldLabel, getName, getSupportedArrayElements, getSupportedAttributes, getSupportedFields, isCategory, isSupportedArrayElement, isSupportedAttribute, isSupportedField, items, items, items, itemsByCategory, maxCategories, maxValues, renameCategory, stringArraySize

Method Detail

createContact

Contact createContact()

Factory method to create a Contact for this contact list. The Contact is empty upon creation with none of its fields containing any data (i.e. a call to the method getFields() returns an array of zero length). Even though it is initially empty, the Contact is capable of containing data for exactly those fields that this list supports. Note that creation of the Contact does not add the Contact to the list from which the item was created; a specific call to PIMItem.commit() must be made to commit the item and its data to the list.

RIM Implementation Note: If the runtime type of this Contact List is BlackBerryContactList then the returned Contact will be an instance of BlackBerryContact and will support all RIM extension fields and attributes defined in BlackBerryContact; if desired, the returned Contact may be casted to BlackBerryContact to use any RIM extension methods defined there.

Returns:

a new, empty Contact object associated with this list. However, the Contact is still not persistent in the list until a call to commit() for the Contact is made.

See Also:

ContactList.importContact(Contact), ContactList.removeContact(Contact)

Since:

BlackBerry API 4.0.0

importContact

Contact importContact(Contact contact)

Imports the given Contact into this contact list. This is done by making a new Contact for the list and filling its information with as much information as it can from the provided Contact. If the input Contact is already in the list, a new Contact is still created with information similar to the input item (but not necessarily identical).

Note that not all data from the input Contact may be supported in the new Contact due to field restrictions for the list instance. In this case, data fields not supported are not transferred to the new Contact object.

Also note that creation of the Contact does not add the Contact to this list; a specific call to PIMItem.commit() must be made to commit the item and its data to the list.

RIM Implementation Note: If the runtime type of this Contact List is BlackBerryContactList then the returned Contact will be an instance of BlackBerryContact and will support all RIM extension fields and attributes defined in BlackBerryContact; if desired, the returned Contact may be casted to BlackBerryContact to use any RIM extension methods defined there.

Parameters:

contact - the Contact to import into the list.

Returns:

a newly created Contact, as described above.

Throws:

NullPointerException - if contact is null.

See Also:

ContactList.createContact(), ContactList.removeContact(Contact)

Since:

BlackBerry API 4.0.0

removeContact

void removeContact(Contact contact)
                   throws PIMException

Removes a Contact from this list. The item must already exist in the list for this method to succeed.

Parameters:

contact - the Contact to be removed from the list.

Throws:

PIMException - If an error occurs removing the item or the list is no longer accessible or closed.

NullPointerException - If contact is null.

SecurityException - if the application is not given permission to write to the Contact list or the list is opened READ_ONLY.

See Also:

ContactList.createContact(), ContactList.importContact(Contact)

Since:

BlackBerry API 4.0.0