SHOW Signed

net.rim.blackberry.api.pim
Class PIM

java.lang.Object
  |
  +--net.rim.blackberry.api.pim.PIM

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.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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

PIM()

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

READ_ONLY

public static final int READ_ONLY

Indicates that the list is open in read-only mode.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

WRITE_ONLY

public static final int WRITE_ONLY

Indicates that the list is open in write-only mode.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

READ_WRITE

public static final int READ_WRITE

Indicates that the list is open in read-write mode.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

CONTACT_LIST

public static final int CONTACT_LIST

Represents the Contact list type.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

EVENT_LIST

public static final int EVENT_LIST

Represents the Event list type.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

TODO_LIST

public static final int TODO_LIST

Represents the ToDo list type.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Constructor Detail

PIM

public PIM()

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

Method Detail

getInstance

public static PIM getInstance()

Returns a PIM instance.

Returns:

A PIM object.

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 contact list to open.

Returns:

A PIMList instance.

Throws:

PIMException - Thrown if an error occurs with the list.

Since:

JDE 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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.

 
     String[] dataFormats = PIM.contactSerialFormats();

     //write contact to vCard
     ByteArrayOutputStream ostream = new ByteArrayOutputStream();
     OutputStreamWriter writer = new OutputStreamWriter(ostream);
     PIM.toSerialFormat(contact, writer, dataFormats[0]);

     //import contact from vCard
     ByteArrayInputStream istream = new ByteArrayInputStream(bo.toByteArray))));
     InputStreamReader reader = new InputStreamReader(istream);
     PIMItem[] pi = PIM.fromSerialFormat(reader);

     ContactList contacts = PIM.openContactList(PIM.READ_WRITE);
     Contact contact2 = contacts.importContact((Contact)pi[0]);
 

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

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:

      ContactList contacts = PIM.openContactList(PIM.READ_ONLY);
      OutputStreamWriter writer = new OutputStreamWriter(
                        new ByteArrayOutputStream());
      String[] dataFormats = PIM.contactSerialFormats();
      Enumeration e = contacts.elements();
      while (e.hasMoreElements()) {
               Contact c = (Contact)e.nextElement();
               PIM.toSerialFormat(c, writer, dataFormats[0]);
      }
 

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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.

supportedSerialFormats

public abstract String[] supportedSerialFormats(int pimListType)

Returns the supported serial formats for a PIMItem object.

The return value 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 3.6

Category:

Signed: This element is only accessible by signed clients. If you intend to use this element, please contact RIM to establish the necessary agreements that will allow you to have your COD files signed. Signing is only required for use on the device, development under the JDE can occur without signing the CODs.