Persistent Storage II: File Connection and PIM API - Beginning J2ME: From Novice to Professional - page 130

All the records in a list can be accessed via an Enumeration ( java.util.Enmeration ) of
PIMItems . You can obtain the Enumeration using one of the items() methods on the PIMList :
public Enumeration items() throws PIMException
public Enumeration items(PIMItem matchingItem) throws PIMException
public Enumeration items(String matchingValue) throws PIMException
The second and third form in the preceding list will both return a subset of the items in a list.
The second form matches based on a supplied PIMItem template (which is a contact, an
event, or a to-do item). You need to set the fields on this template that you want to match
(setting field values is covered later in this chapter; see the section “Modifying Field Values”).
For a String typed field, you can specify a partial string. For example, specifying “hom” will
match both “homing pigeon” and “HOMER”.
The third form attempts to perform the partial string match across all string-typed fields of
an item. For a ContactList , it is essentially saying, “Find me all the contacts that contain the
string in any of its (string-typed) fields.”
Manipulating Categories
Some PDAs support the notion of a category. You can classify a list of items by categories.
A category is a just a string. For example, a “personal” category can be used to flag all the personal
contacts in the content list, while a “business” category is used for business contacts. To obtain
all the list items in a particular category, you can use the following:
public Enumeration itemsByCategory(String category) throws PIMException
To get a list of categories supported by the device, call
String [] getCategories() throws PIMException
If you get a zero-length array in return, you know that either the device does not support
categories or the user hasn't defined any.
Once you've determined that the device supports categories, you can add new categories
using the following:
public void addCategory(String category) throws PIMException
This method will never add the same category twice. It will return without throwing an exception
if the specified category already exists. To delete a category, use this method:
public void deleteCategory(String category, boolean deleteUnassignedItems)
Note that some items may end up having no category assigned once a category is deleted.
Set the deleteUnassignedItems flag to true if you want these items deleted from the list. The
deleteCategory() method will return without throwing an exception even if the category specified
does not exist. It will, however, throw a PIMException if categories are not supported on the device.
A category can be renamed using the following method:
public void renameCategory(String currentCategoryName, String newCategoryName)
throws PIMException
Four methods can be used to manipulate the categories associated with a contact: