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

Determining If PIM Optional Package Is Available
You should check to see if the PIM Optional Package is available on a device before attempting
to use it. Check for the system property called microedition.pim.version . All PIM Optional
Package implementations are required to support it. Use code similar to
String currentVersion = System.getProperty("microedition.pim.version " )
You should also use the returned version to make sure your code is version compatible. At
this time, however, only version “1.0” is available. The call will return null if the optional
package is not available.
Obtaining the Singleton PIM Instance
The API centers around the PIM abstract class. You cannot instantiate this class with the new
operator. However, there is a class factory method to obtain the one and only instance:
public static PIM getInstance()
Opening the PIM Lists
You can access the PIM lists once you have the singleton instance. A PIM list can be obtained
using one of these openPIMList() methods:
public PIMList openPIMList(int pimListType, int mode) throws PIMException
public PIMList openPIMList(int pimListType, int mode, String name) throws
PIMException
The pimListType can contain PIM.CONTACT_LIST , PIM.EVENT_LIST , or PIM.TODO_LIST . The
JSR 75 specification requires at least one list to be available if the optional package is supported.
The access mode can be PIM.READ_ONLY , PIM.READ_WRITE , or PIM.WRITE_ONLY .
JSR 75 allows a device to maintain multiple lists of the same type. Not all implementations
will have this need. If you need to, the second form of the openPIMList() method enables you
to select a list by name and type. The name of the lists available, if an implementation supports
multiple lists of the same type, can be obtained via the following:
String [] listPIMLists( int pimListType);
pimListType is any one of PIM.CONTACT_LIST , PIM.EVENT_LIST , or PIM.TODO_LIST .
Obtaining Items from a PIM List
Once you have a list opened, you can start accessing its content. The openPIMList() call returns
a PIMList . The javax.microedition.pim.PIMList interface is the superinterface of ContactList ,
EventList , and ToDoList . You need to cast it to the expected type before accessing the list,
for example:
ContactList clist = (ContactList)
pimInst.openPIMList( PIM.CONTACT_LIST, PIM.READ_WRITE);