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.

Since:
PIM 1.0
See Also:
Contact, BlackBerryContactList

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

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 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.
Since:
JDE 4.0.0
See Also:
importContact(Contact), removeContact(Contact)

importContact

public 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.
Since:
JDE 4.0.0
See Also:
createContact(), removeContact(Contact)

removeContact

public 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.
Since:
JDE 4.0.0
See Also:
createContact(), importContact(Contact)



Copyright 1999-2009 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.