PDAP Public Review Draft

javax.microedition.pim
Interface ContactList

All Superinterfaces:
PIMList

public interface ContactList
extends PIMList

Represents a Contact list containing Contact elements.

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.getSupportedTypes(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.elements(PIMElement)). A java.lang.IllegalArgumentException is thrown by this method if the input parameter does not implement the Contact interface.

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

Since:
PDAP 1.0
See Also:
Contact

Method Summary
 Contact createContact()
          Factory method to create a Contact for this contact list.
 Contact importContact(Contact element)
          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 element)
          Removes a specific Contact from the list.
 
Methods inherited from interface javax.microedition.pim.PIMList
addCategory, close, deleteCategory, elements, elements, getCategories, getSupportedFields, getSupportedTypes, isExtendedField, isSupportedField, maxCategories
 

Method Detail

createContact

public Contact createContact()
                      throws PIMException
Factory method to create a Contact for this contact list. Note that creation of the Contact does not add the Contact to the list from which the element was created; a specific call to PIMElement.commit() must be made to commit the element and its data to the list.
Throws:
PIMException - if the element cannot be created or the list is no longer accessible or closed.

importContact

public Contact importContact(Contact element)
                      throws PIMException
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 element (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.
Parameters:
element - the Contact to import into the list.
Returns:
a newly created Contact after it has been persisted to the database.
Throws:
PIMException - If an error occurs or the list is no longer accessible or closed.
java.lang.IllegalArgumentException - If the Contact is null.
java.lang.SecurityException - if the application is not given permission to write to the Contact list.

removeContact

public void removeContact(Contact element)
                   throws PIMException
Removes a specific Contact from the list. The element must already exist in the list for this method to succeed.
Parameters:
element - 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.IllegalArgumentException - If the Contact is null.
java.lang.SecurityException - if the application is not given permission to write to the Contact list.

PDAP 1.0 Spec, Rev. 0.16