javax.microedition.pim
Class PIM

java.lang.Object
  |
  +--javax.microedition.pim.PIM
Direct Known Subclasses:
BlackBerryPIM

public abstract class PIM
extends Object

Class for accessing the PIM databases on a device.

Contains static methods for performing operations on lists.

For more information about this class or about the personal information management (PIM) API, refer to The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

Since:
PDAP 1.0
See Also:
PIMItem, PIMList

Field Summary
static int CONTACT_LIST
          Represents the Contact list type.
static int EVENT_LIST
          Represents the Event list type.
static int READ_ONLY
          Indicates that the list is open in read-only mode.
static int READ_WRITE
          Indicates that the list is open in read-write mode.
static int TODO_LIST
          Represents the ToDo list type.
static int WRITE_ONLY
          Indicates that the list is open in write-only mode.
 
Constructor Summary
protected PIM()
          PIM objects should be created using the getInstance() method.
 
Method Summary
abstract  PIMItem[] fromSerialFormat(InputStream is, String enc)
          Creates a PIMItem instance given a valid data InputStream.
static PIM getInstance()
          Returns a PIM instance.
abstract  String[] listPIMLists(int pimListType)
          Returns an array of strings representing the names of all valid PIM lists of the specified type.
abstract  PIMList openPIMList(int pimListType, int mode)
          Opens the default list of the specified list type.
abstract  PIMList openPIMList(int pimListType, int mode, String name)
          Opens the specified PIM list.
abstract  String[] supportedSerialFormats(int pimListType)
          Returns the supported serial formats for a PIMItem object.
abstract  void toSerialFormat(PIMItem item, OutputStream os, String enc, String dataFormat)
          Serializes a PIMItem instance.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CONTACT_LIST

public static final int CONTACT_LIST
Represents the Contact list type.
Since:
JDE 4.0.0

EVENT_LIST

public static final int EVENT_LIST
Represents the Event list type.
Since:
JDE 4.0.0

READ_ONLY

public static final int READ_ONLY
Indicates that the list is open in read-only mode.
Since:
JDE 4.0.0

READ_WRITE

public static final int READ_WRITE
Indicates that the list is open in read-write mode.

Since:
JDE 4.0.0

TODO_LIST

public static final int TODO_LIST
Represents the ToDo list type.
Since:
JDE 4.0.0

WRITE_ONLY

public static final int WRITE_ONLY
Indicates that the list is open in write-only mode.

Since:
JDE 4.0.0
Constructor Detail

PIM

protected PIM()
PIM objects should be created using the getInstance() method.
Since:
JDE 4.0.0
Method Detail

fromSerialFormat

public abstract PIMItem[] fromSerialFormat(InputStream is,
                                           String enc)
                                    throws PIMException,
                                           UnsupportedEncodingException
Creates a PIMItem instance given a valid data InputStream.

The format of the first characters of the incoming data determine what type of PIM items are created (see supportedSerialFormats(int) to see what data formats are actually supported.

The default encoding type is UTF8.

Importing data from serial format

Below, the fromSerialFormat method is invoked to create an array of PIMItems. The ContactList.importContact() method is then invoked to add a new Contact to the list.

The following example demonstrates how to convert an existing Contact into a vCard and then import the vCard into a new Contact.

 
     PIM pim = PIM.getInstance();
     String[] dataFormats = pim.supportedSerialFormats(PIM.CONTACT_LIST);

     //write contact to vCard
     ByteArrayOutputStream ostream = new ByteArrayOutputStream();
     pim.toSerialFormat(contact, ostream, "UTF8", dataFormats[0]);

     //import contact from vCard
     ByteArrayInputStream istream = new ByteArrayInputStream(ostream.toByteArray());
     PIMItem[] pi = pim.fromSerialFormat(istream, "UTF8");

     ContactList contacts = (ContactList) pim.openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);
     Contact contact2 = contacts.importContact((Contact)pi[0]);
     contacts.close();
 

Note:PIM data suffers a slight precision loss when converting PIM Date data to serial format since the serialization process does not provide millisecond precision. While this loss of precision will likely not effect the integrity of your Date data, it will cause any comparisons between serialized and unserialized PIM objects to fail.

Parameters:
is - The data inputstream containing the serialized data.
enc - The encoding type.
Throws:
PIMException - Thrown if an error occurs with the list.
UnsupportedEncodingException - Thrown if the specified encoding type is unsupported or unknown.
Since:
JDE 4.0.0

getInstance

public static PIM getInstance()
Returns a PIM instance.

Returns:
A PIM object.
Since:
JDE 4.0.0

listPIMLists

public abstract String[] listPIMLists(int pimListType)
Returns an array of strings representing the names of all valid PIM lists of the specified type.

A zero-length array is returned if no lists exist. The first name in the list represents the default list.

Parameters:
pimListType - The type of PIM list (CONTACT_LIST, EVENT_LIST, TODO_LIST).
Returns:
An array of strings representing the list names.
Since:
JDE 4.0.0

openPIMList

public abstract PIMList openPIMList(int pimListType,
                                    int mode)
                             throws PIMException
Opens the default list of the specified list type.

Parameters:
pimListType - The type of PIM list (CONTACT_LIST, EVENT_LIST, TODO_LIST).
mode - An integer representing the mode (READ_ONLY, WRITE_ONLY, READ_WRITE) in which to open the list.
Returns:
A PIMList instance.
Throws:
PIMException - Thrown if an error occurs with the list.
Since:
JDE 4.0.0

openPIMList

public abstract PIMList openPIMList(int pimListType,
                                    int mode,
                                    String name)
                             throws PIMException
Opens the specified PIM list.

For a list of available PIM lists, invoke the listPIMLists(int) method.

Parameters:
pimListType - The type of PIM list (CONTACT_LIST, EVENT_LIST, TODO_LIST).
mode - An integer representing the mode (READ_ONLY, WRITE_ONLY, READ_WRITE) in which to open the list.
name - The name of the list to open.
Returns:
A PIMList instance.
Throws:
PIMException - Thrown if an error occurs with the list.
Since:
JDE 4.0.0

supportedSerialFormats

public abstract String[] supportedSerialFormats(int pimListType)
Returns the supported serial formats for a PIMItem object.

The first element of the return value (an array of strings) can be used as the data format parameter in the toSerialFormat method.

The default encoding type is UTF8.

Parameters:
pimListType - The type of the PIMList.
Returns:
An array of strings containing the supported data formats.
Since:
JDE 4.0.0

toSerialFormat

public abstract void toSerialFormat(PIMItem item,
                                    OutputStream os,
                                    String enc,
                                    String dataFormat)
                             throws PIMException,
                                    UnsupportedEncodingException
Serializes a PIMItem instance.

The format of the encoding must be supported by the API. The format of the first characters of the incoming data determine what type of PIM items are created (see supportedSerialFormats(int) to see what data formats are actually supported.

The default encoding type is UTF8.

Converting data to serial format

Data can be imported or exported from PIMItems using using standard formats, such as iCal and vCard. The following example demonstrates how to export all the contacts from the handheld Address Book to a supported serial format, using an output stream writer:


    PIM pim = PIM.getInstance();
    ContactList cl = (ContactList)pim.openPIMList(PIM.CONTACT_LIST, PIM.READ_ONLY);
    ByteArrayOutputStream output = new ByteArrayOutputStream();
    String[] dataFormats = pim.supportedSerialFormats(PIM.CONTACT_LIST);
    Enumeration e = cl.items();
    while (e.hasMoreElements()) {
            Contact c = (Contact)e.nextElement();
            pim.toSerialFormat(c, output, "UTF8", dataFormats[0]);
    }
    output.close();
    cl.close(); 
 

Note:PIM data suffers a slight precision loss when converting PIM Date data to serial format since the serialization process does not provide millisecond precision. While this loss of precision will likely not effect the integrity of your Date data, it will cause any comparisons between serialized and unserialized PIM objects to fail.

Parameters:
item - The PIMItem to be serialized.
os - The OutputStream to write the data to.
enc - The encoding type.
dataFormat - The data format to use.
Throws:
PIMException - Thrown if an error occurs during the encoding.
UnsupportedEncodingException - Thrown if the specified encoding type is unsupported or unknown.
Since:
JDE 4.0.0



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