javax.microedition.pim
Class PIM

java.lang.Object
  extended by javax.microedition.pim.PIM
Direct Known Subclasses:
BlackBerryPIM

public abstract class PIM
extends Object

Class for accessing PIM lists on a device and performing PIM wide functions. This class is a collection of static methods for getting the names of the existing PIM lists, opening the lists, and converting raw data streams to and from PIM items for importing and exporting into those lists.

Examples

Importing a Contact from a Stream

This example assumes that the InputStream contains a valid vCard 3.0 entry with the following characteristics:

  Content-Type: text/directory; charset="UTF-8"; profile="vCard"
  Content-ID: <id3@host.com>
  Content-Transfer-Encoding: Quoted-Printable
 
The content of the vCard looks like the following:
  begin:VCARD
  source:ldap://cn=3Dbjorn%20Jensen, o=3Duniversity%20of%20Michigan, c=3DUS
  name:Bjorn Jensen
  fn:Bj=C3=B8rn Jensen
  n:Jensen;Bj=F8rn
  email;type=3Dinternet:bjorn@umich.edu
  tel;type=3Dwork,voice,msg:+1 313 747-4454
  key;type=3Dx509;encoding=3DB:dGhpcyBjb3VsZCBiZSAKbXkgY2VydGlmaWNhdGUK
  end:VCARD
 

The following method assumes that the input stream is positioned at the first character of the vCard (i.e. the start of the "begin:" tag). For simplicity in this example, the method also hardcodes the transfer encoding of Quoted Printable and the data in the character set UTF-8.

 void importVCard( InputStream is )
 {
     // Using application defined class QuotedPrintableInputStream ...
     QuotedPrintableInputStream qpis = new QuotedPrintableInputStream( is );
     try {
         PIMItem[] items = PIM.getInstance().fromSerialFormat( qpis, "UTF-8" );
         Contact c = (Contact) ( items[ 0 ] );
         ContactList cl = (ContactList) PIM.getInstance().openPIMList(
                 PIM.CONTACT_LIST, PIM.READ_WRITE );
         cl.importContact( c );
     } catch( PIMException pe ) {
     } catch( IOException ioe ) {
     }
 }
 

Exporting a Contact to a Stream

This example exports a Contact to the provided output stream. The data format used is the first data format returned from PIM.supportedSerialFormats(int). Note that any transfer encoding, such as applying Quoted Printable, is the responsibility of the application outside of this method.

 void exportVCard( Contact c, OutputStream os )
 {
     String[] data_formats = PIM.getInstance().supportedSerialFormats(
             PIM.CONTACT_LIST );
     try {
         PIM.getInstance().toSerialFormat( c, os, "UTF-8", data_formats[ 0 ] );
     } catch( PIMException pe ) {
     } catch( IOException ioe ) {
     }
 }
 

RIM Implementation Notes

The RIM extension functionality for the PIM class is defined in BlackBerryPIM. Any instance of PIM that is retrieved from PIM.getInstance() will be an instance of BlackBerryPIM and can be successfully casted to BlackBerryPIM, if desired, in order to use the RIM extension functionality. Also, the RIM extension constants defined in BlackBerryPIM are recognized by PIM, so there is normally no need to perform the casting.

Multiple PIMList Support

The standard calendar and contact list PIM applications on a BlackBerry device support multiple databases. When a device is associated with multiple accounts, such as BlackBerry Enterprise Server accounts and BlackBerry Internet Service accounts, each account has its own database for the calendar and the contact list PIM applications. For example, if a device is associated with both a BlackBerry Enterprise Server account and a BlackBerry Internet Service account, the calendar and contact list applications each have a database for each account.

Multiple EventList Support

Support for accessing the multiple EventLists was added in BlackBerry software version 4.6.0. Invoking PIM.listPIMLists(PIM.EVENT_LIST) returns a name for each individual EventList so that they can be accessed individually. In previous versions of the software, the JSR75 PIM API only returned a single EventList which provided access to all of the EventLists without distinguishing between EventLists for different BlackBerry Enterprise Server accounts.

Multiple ContactList Support

Support for accessing the multiple ContactLists was added in BlackBerry software version 5.0.0. Invoking PIM.listPIMLists(PIM.CONTACT_LIST) returns a name for each individual ContactList so that they can be accessed individually. In previous versions of the software, the JSR75 PIM API only returned a single ContactList which provided access to all of the ContactLists without distinguishing between ContactLists for different BlackBerry Enterprise Server accounts.

Multiple ToDoList and BlackBerryMemoList Support

There is currently no support for accessing multiple ToDoLists or BlackBerryMemoLists. The ToDoList or BlackBerryMemoList returned from PIM.openPIMList() provides access to all of the lists of that database without distinguishing between the different BlackBerry Enterprise Server. accounts

PIMList UIDs

If an application maintains a parallel database to a PIMList then the PIMList should be referenced by its UID instead of its name. This is because the name of a PIMList can change over its lifetime and also may be assigned a different name if the BlackBerry device software is upgraded or downgraded. A PIMLists's UID can be obtained from BlackBerryPIMList.getPIMListUID() and a PIMList can be opened by its UID using BlackBerryPIM.openPIMList(int, int, long). Support for PIMList UIDs was added in BlackBerry software version 5.0.0.

Default PIMList Changes

When a BlackBerry smartphone synchronizes with a BlackBerry Enterprise Server then the default PIMList for each PIMList type (EventList, ContactList, etc.) may change. When this happens, PIMItems from the device-only PIMList may be moved into the PIMList for the newly-added PIMList for the new BlackBerry Enterprise Server account. When this occurs, PIMItems will seem to "disappear" from the PIMList as they are moved into the new PIMList. To respond to this event, applications can be notified when the default PIMList changes by registering a ListChangeListener via BlackBerryPIM.addListChangeListener(ListChangeListener).

The PDA Profile specification (JSR-75) for the J2ME(TM) Platform

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

See Also:
BlackBerryPIM
Since:
BlackBerry API 4.0.0, PIM 1.0

Field Summary
static int CONTACT_LIST
          Constant representing a Contact List.
static int EVENT_LIST
          Constant representing an Event List.
static int READ_ONLY
          Constant representing opening a list in read only mode.
static int READ_WRITE
          Constant representing opening a list in read/write mode.
static int TODO_LIST
          Constant representing a ToDo List.
static int WRITE_ONLY
          Constant representing opening a list in write only mode.
 
Constructor Summary
protected PIM()
          Constructor for subclasses.
 
Method Summary
abstract  PIMItem[] fromSerialFormat(InputStream is, String enc)
          Creates and fills one or more PIM items from data provided in the given InputStream object where the data is expressed in a valid data format supported by this platform.
static PIM getInstance()
          Factory method to get an instance of the PIM class.
abstract  String[] listPIMLists(int pimListType)
          Returns a list of all PIM List names for the given PIM list type.
abstract  PIMList openPIMList(int pimListType, int mode)
          Opens the default list for the indicated PIM list type.
abstract  PIMList openPIMList(int pimListType, int mode, String name)
          Opens a named PIM List.
abstract  String[] supportedSerialFormats(int pimListType)
          Returns the supported data formats for items used when converting a PIMItem's data to and from data streams.
abstract  void toSerialFormat(PIMItem item, OutputStream os, String enc, String dataFormat)
          Writes the data from the given item to the given OutputStream object as Unicode characters in a format indicated by the String parameters.
 
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
Constant representing a Contact List.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

EVENT_LIST

public static final int EVENT_LIST
Constant representing an Event List.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

READ_ONLY

public static final int READ_ONLY
Constant representing opening a list in read only mode.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

READ_WRITE

public static final int READ_WRITE
Constant representing opening a list in read/write mode.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

TODO_LIST

public static final int TODO_LIST
Constant representing a ToDo List.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0

WRITE_ONLY

public static final int WRITE_ONLY
Constant representing opening a list in write only mode.

See Also:
Constant Field Values
Since:
BlackBerry API 4.0.0


Constructor Detail

PIM

protected PIM()
Constructor for subclasses. PIM class objects are not instantiated directly; to access a PIM object, PIM.getInstance() should be used.

Since:
BlackBerry API 4.0.0


Method Detail

fromSerialFormat

public abstract PIMItem[] fromSerialFormat(InputStream is,
                                           String enc)
                                    throws PIMException,
                                           UnsupportedEncodingException
Creates and fills one or more PIM items from data provided in the given InputStream object where the data is expressed in a valid data format supported by this platform. The character stream starting from the InputStream's current character position must represent a complete entry as specified by the supported data format or else a PIMException is thrown. Data representing unsupported data entries and/or data fields is ignored as long as a valid entry of a supported entry type is contained in the stream.

This method reads only one complete data entry from the InputStream, leaving the InputStream object open and its character position on the character after the end of the entry, or at a position in the stream where an error is detected if the data stream is in an invalid or incomplete format. A single valid data entry in an InputStream results in the creation of one or more PIMItems (in some data formats more than one PIMItem may be in a single entry).

The format of the data in the InputStream determines what type of PIM items are created (see PIM.supportedSerialFormats(int) to see what data formats are supported by this implementation).

It is the responsibility of the application to perform any transfer character decoding (such as Content-Transfer-Encoding for MIME or Transfer-Encoding for HTTP) prior to providing the InputStream object with the entry data to this method.

In creating PIM items, data from the input stream is taken and mapped to appropriate corresponding PIM item fields. If there is no appropriate corresponding PIM item field for a particular piece of data in the input stream, that data may be either silently discarded by this method or retained in the PIM item as an extended field value (the action taken is implementation specific). If the data from the input stream does not contain values for all of the fields required by the item, the VM may provide default values so that the information can still be received and PIM items can still be created.

Also note that creation of the PIM items does not add the item to any list; the import method for a list capable of containing the specific PIM item must be used to add the item to a list. For example, should a Contact item be created, then the method ContactList.importContact() should be invoked from an existing list to import that contact into the target list.

Parameters:
is - an input stream containing PIM information in a well-known data format supported by this method.
enc - the character encoding of the characters in the input stream; if null, the default character encoding of UTF-8 is used.
Returns:
an array of newly created PIM items created from the InputStream. In some cases, more than one PIM item may be created from a complete entry (for example, a single vCalendar entry may produce two PIM items, both an Event and a ToDo).
Throws:
PIMException - If the data is incorrect, does not contain enough information to form a complete entry, or a stream error occurs.
NullPointerException - if is is null.
UnsupportedEncodingException - if enc is not a encoding method supported on this platform.
See Also:
PIM.toSerialFormat(PIMItem, OutputStream, String, String), PIM.supportedSerialFormats(int)
Since:
BlackBerry API 4.0.0

listPIMLists

public abstract String[] listPIMLists(int pimListType)
Returns a list of all PIM List names for the given PIM list type. If there are no Lists for that list type, a zero length String array is returned. The first name in the list is the name of the default List for a type.

RIM Implementation Note: In the PIM instance returned from PIM.getInstance() when used on BlackBerry smartphones, this method also recognizes the PIM list types defined in the RIM extensions to this class, BlackBerryPIM, such as MEMO_LIST.

Parameters:
pimListType - the PIM list type whose list names to return; valid values include PIM.CONTACT_LIST, PIM.EVENT_LIST, and PIM.TODO_LIST.
Returns:
the list of named lists for the specified PIM list type
Throws:
SecurityException - if the application is not given permission to read PIM lists.
IllegalArgumentException - if pimListType is not a valid PIM list type.
Since:
BlackBerry API 4.0.0

openPIMList

public abstract PIMList openPIMList(int pimListType,
                                    int mode)
                             throws PIMException
Opens the default list for the indicated PIM list type.

RIM Implementation Note: In the PIM instance returned from PIM.getInstance() when used on BlackBerry smartphones, this method also recognizes the PIM list types defined in the RIM extensions to this class, BlackBerryPIM, such as MEMO_LIST.

Parameters:
pimListType - the PIM list type to open; valid values include PIM.CONTACT_LIST, PIM.EVENT_LIST, and PIM.TODO_LIST.
mode - the mode in which the List is opened; must be one of PIM.READ_ONLY, PIM.READ_WRITE, or PIM.WRITE_ONLY.
Returns:
the default PIM list for the indicated PIM list type.
Throws:
PIMException - If the operation is unsupported or an error occurs.
SecurityException - if the application is not given permissions that match the requested mode.
IllegalArgumentException - If an invalid mode is provided as a parameter or if pimListType is not a valid PIM list type.
See Also:
PIM.openPIMList(int, int, String), BlackBerryPIM.openPIMList(int, int, long)
Since:
BlackBerry API 4.0.0

openPIMList

public abstract PIMList openPIMList(int pimListType,
                                    int mode,
                                    String name)
                             throws PIMException
Opens a named PIM List. Only string names returned by PIM.listPIMLists(int) can be used to open a list.

RIM Implementation Note: In the PIM instance returned from PIM.getInstance() when used on BlackBerry smartphones, this method also recognizes the PIM list types defined in the RIM extensions to this class, BlackBerryPIM, such as MEMO_LIST.

For information about multiple PIMList support, see Multiple PIMList Support.

Parameters:
pimListType - the PIM list type to open; valid values include PIM.CONTACT_LIST, PIM.EVENT_LIST, and PIM.TODO_LIST.
mode - the mode in which the List is opened; must be one of PIM.READ_ONLY, PIM.READ_WRITE, or PIM.WRITE_ONLY.
name - the name of the list to open
Returns:
the default PIM list for the indicated PIM list type.
Throws:
PIMException - If the list is not available, the operation is unsupported or an error occurs.
SecurityException - if the application is not given permissions that match the requested mode.
IllegalArgumentException - If an invalid mode is provided as a parameter or if pimListType is not a valid PIM list type.
NullPointerException - If name is null.
See Also:
PIM.openPIMList(int, int), BlackBerryPIM.openPIMList(int, int, long)
Since:
BlackBerry API 4.0.0

supportedSerialFormats

public abstract String[] supportedSerialFormats(int pimListType)
Returns the supported data formats for items used when converting a PIMItem's data to and from data streams. The return value is suitable for use as the data format parameter in PIM.toSerialFormat(PIMItem, OutputStream, String, String). The naming convention for the strings returned is the common name of the data format in all capital letters, followed by a slash ("/"), and then followed by the version number of the data format. For example "VCARD/2.1" or "VCALENDAR/1.0".

Parameters:
pimListType - the PIM list type whose supported serial formats to return; valid values include PIM.CONTACT_LIST, PIM.EVENT_LIST, and PIM.TODO_LIST.
Returns:
String array of data formats supported for converting items to and from data streams.
Throws:
IllegalArgumentException - if pimListType is not a valid PIM list type.
See Also:
PIM.toSerialFormat(PIMItem, OutputStream, String, String), PIM.fromSerialFormat(InputStream, String)
Since:
BlackBerry API 4.0.0

toSerialFormat

public abstract void toSerialFormat(PIMItem item,
                                    OutputStream os,
                                    String enc,
                                    String dataFormat)
                             throws PIMException,
                                    UnsupportedEncodingException
Writes the data from the given item to the given OutputStream object as Unicode characters in a format indicated by the String parameters. The character encoding for those characters written to the OutputStream is in the provided character encoding. The data format specified must be supported by the PIM implementation (see PIM.supportedSerialFormats(int)) or else an IllegalArgumentException is thrown. After this method is invoked, the OutputStream contains the item as a data stream in the given data format. The output produced is a single complete entry and suitable for exchange with other programs supporting that data format. The OutputStream is left open and any writes to that stream occurs at the position immediately after the entry just written.

All data fields contained in the provided PIMItem are written out to the output stream in the specified format. Fields that do not have specific corresponding fields in the data format specified are written as extended fields if the data format supports extended fields.

It is the responsibility of the application to perform any further character encoding needed for transportation of the vCard entry (such as Content-Transfer-Encoding for MIME or Transfer-Encoding for HTTP).

Parameters:
item - the item to export to the OutputStream object.
os - the OutputStream object that the item is written to as a character stream.
enc - the character encoding used to write the PIMItem to the OutputStream; if null, the default character encoding of UTF-8 is used.
dataFormat - he requested PIM data format to use (i.e. the well-known structure of the data prior to character encoding)
Throws:
PIMException - if an error occurs when converting the item's data or if a stream error occurs, preventing the data from being written in a complete and valid form. There is no guarantee that the OutputStream is unmodified or contains complete information if this exception is thrown.
NullPointerException - if one or more of os, dataFormat or item is null.
UnsupportedEncodingException - if enc is not a encoding method supported on this platform.
IllegalArgumentException - if dataFormat is not a valid format; that is, dataFormat is not equal to one of the strings returned from PIM.supportedSerialFormats(int) when specified the PIM list type of item.
See Also:
PIM.fromSerialFormat(InputStream, String), PIM.supportedSerialFormats(int)
Since:
BlackBerry API 4.0.0

getInstance

public static PIM getInstance()
Factory method to get an instance of the PIM class.

Returns:
an instance of the PIM class.
Since:
BlackBerry API 4.0.0





Copyright 1999-2010 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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.