javax.microedition.pim
Interface ContactList

All Superinterfaces:

PIMList

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 java.lang.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 java.lang.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.

Since:

PIM 1.0

See Also:

Contact

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 by making a new Contact for the list and filling its information with as much information as it can from the provided Contact.
void	removeContact(Contact contact) Removes a specific Contact from the 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

public 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 Contact.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.

Returns:

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

importContact

public Contact importContact(Contact contact)

Imports the given Contact into this contact list 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.

Parameters:

contact - the Contact to import into the list.

Returns:

a newly created Contact.

Throws:

java.lang.NullPointerException - If contact is null.

removeContact

public void removeContact(Contact contact)
                   throws PIMException

Removes a specific Contact from the 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 deleting the item or the list is no longer accessible or closed.

java.lang.NullPointerException - If contact is null.

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