Accessing Files and Other Data - Beginning Java ME Platform - page 170

PIMItem objects, and each PIMItem is an interface into a specific item in an application's
database. Using the various interfaces in this hierarchy, you can enumerate records in any
of these application stores, as well as examine how entries are grouped into categories,
create new records, and remove existing records, just as a native application would.
Using the PIM Package
To use the PIM package, you need your code to follow this basic structure:
1. Check the device to ensure the PIM package is available.
2. Open the desired PIM database and obtain a PIMList for the desired database.
3. If you want to read entries from the PIMList , obtain elements from it using one of
its Enumeration -yielding interfaces.
4. If you want to create new entries in the PIMList , create a new PIMItem using
the PIMList . Then add the data to PIMItem , and finally call commit to commit
the changes.
5. If you want to change an entry of the PIMList , obtain the PIMItem corresponding
to the item you want to change, and call a method to set the various fields of the
item. Then call commit to commit the changes to the item.
6. If you want to remove an item, obtain the PIMItem corresponding to the item to be
removed, and then invoke the appropriate remove method on the PIMList , passing
the item to be removed.
Unlike the FCOP, which uses different exceptions to flag different errors, the PIM
package interfaces throw only a PIMException on an error. The PIMException thrown will
have one of the following reason codes available via the getReason method indicating why
the exception was thrown:
• FEATURE_NOT_SUPPORTED : If the functionality requested is not supported by the
implementation
• GENERAL_ERROR : For general errors
• LIST_CLOSED : If the PIMList you're trying to use is closed already
• LIST_NOT_ACCESSIBLE : If the PIMList you're trying to use is no longer available, per-
haps because the underlying database was deleted
• MAX_CATEGORIES_EXCEEDED : If the maximum number of categories for items in the
PIMList has been exceeded