|
|||||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||||
This document contains the packages required to access personal information management (PIM) data on a BlackBerry device. PIM data is defined as information included in address book, calendars, tasks, and memopad applications. The Blackberry device fully supports the J2ME PIM implementation established in JSR 75, with a number of custom extensions. For more information, see the following sections:
The javax.microedition.pim package, which was introduced with JSR 75, provides a number of interfaces that allow you to access PIM data on a compliant mobile device. PIM data is organized into PIM lists, items, and fields. PIM lists are databases that contain all PIM items that can be accessed on a device. PIMLists maintain categories, which are logical groupings for the PIMItems contained in the list. Each PIMList can support zero or more categories. Categories are represented by unique String names.
A PIM item represents a collection of data for a single PIM entry. A PIM item is created from a particular PIM list and is associated with that list for the life of the item. PIM items can have its data imported and exported using standard byte based formats. Each implementing class defines what formats can be imported and exported for that item.
A PIMItem is a grouping of related fields. Each field consists of a label, a data type, value(s), and attribute(s). Several examples are shown in the following table:
For information on specific field attributes specifically for BlackBerry devices, see this section on using BlackBerry PIM Extensions .
For background information on PIM, see the original JSR 75 specification.
The JDE API contains PIM List interface that corresponds to each of the core BlackBerry applications:
| BlackBerry application name | PDAP interface name |
| Address Book | BlackBerryContact |
| Calendar | BlackBerryEvent |
| MemoPad | BlackBerryMemo |
| Tasks | BlackBerryToDo |
To add a PIM item to a PIM list, invoke the relevant create method for the list type. For example, to add a contact to a contact list, create the contact instance, add the contact names, and invoke commit().
Contact contact = contactList.createContact(); String[] name = new String[contactList.stringArraySize(Contact.NAME)]; contact.commit(); |
You must first decide which labels, data types, and attributes to set, and then add those fields to the PIM item. For detailed information and sample code, see the section entitled "Explicit Field Use with Field Checking" in javax.microedition.pim.Contact, javax.microedition.pim.Event, and javax.microedition.pim.ToDo.
Invoke the relevant getXXX() method on the PIMItem to retrieve a particular value from a field. Always invoke countValues() to check if a field has a value before invoking getXXX(), and check if the fields are supported before using them.
NOTE: Invoking getXXX() when countValues() returns zero (0) throws in a RuntimeException (such as IndexOutOfBoundsException).
Click here to view a code sample for retrieving field data from PIMItems.
// Ensure that the NAME field has a value before invoking |
To remove a particular PIM item, call the remove item method on the appropriate PIM list.
Click here to view a code sample for removing PIMItems.
if(contact != null) |
Exporting is converting a PIMItem to a stream of bytes that can be imported by another PIM application. To export PIM data to a supported serial format, invoke PIM.toSerialFormat(PIMItem, OutputStream, String, String), passing as arguments an OutputStream to which the serialized PIMItem is written, the character encoding to use when writing to the output stream, and the supported data exchange format to convert to. Supported character encodings include "UTF8," "ISO-8859-1," and "UTF-16BE."
Click here to view a code sample for exporting PIMItems.
ByteArrayOutputStream outputStream = new ByteArrayOutputStream(); |
To import a PIMItem, invoke fromSerialFormat(InputStream, String), passing as arguments the InputStream from which the serialized PIMItem is written, and the character encoding to use. Supported character encodings include "UTF8," "ISO-8859-1," and "UTF-16BE."
NOTE: Only one PIMItem object can be decoded using a single fromSerialFormat(InputStream, String) invocation.
Click here to view a code sample on how to import contact items from an InputStream.
public void importContacts(InputStream inputStream, String transferEncoding, ContactList contactList) |
Beginning with the BlackBerry JDE version 4.6.0, the EventList interface supports multiple calendars. You can access individual calendars by invoking PIM.listPIMLists(pimListType), passing as argument the calendar PIMList type.
String[] eventLists = pim.listPIMLists(PIM.EVENT_LIST); |
The listPIMLists() method returns a String array containing the unique names for each list that currently exist. The first String item returned from PIM.listPIMLists(pimListType) is the default calendar.
Services changes on the device can cause the default calendar to change. Implement ListChangeListener and specify it to BlackBerryPIM.addListChangeListener() to be notified when the default PIM list changes. The defaultListChanged() method is invoked when the default PIM list changes.
In addition to fully supporting the features in the javax.microedition.pim package, a number of BlackBerry PIM extensions are found in the net.rim.blackberry.api.pdap package. The RIM extensions to the PIM API allow access to BlackBerry-specific features, including:
All BlackBerry-specific fields that are not supported by JSR 75 are defined in the relevant BlackBerrryContactList, BlackBerryToDoList, or BlackBerryEventList interface.
MemoPad is a BlackBerry application not supported by the J2ME PIM implementation. See BlackBerryMemoList for more information and sample code for using the MemoPad.
To set recurrances for ToDo items, invoke setRepeat(RepeatRule value), passing in a RepeatRule object as a parameter to specify the recurrance. To get information on existing ToDo recurrances, invoke getRepeat() for the ToDo item, which returns relevant RepeatRule object.
To display standard user interface for adding contacts to an address book, invoke the choose() method for the BlackBerryContactList instance.
Click here to view a code sample on how to display a standard user interface for an address book.
public Contact askUserToChooseContact() {
PIM pim = PIM.getInstance(); } |
You can design your application to allow BlackBerry device users to perform remote GAL lookups for contacts if your system uses a BlackBerry Enterprise Server (BES) as part of its messaging infrastructure. GAL lookups are performed by invoking BlackBerryContactList.lookup. This method is overridden to accept either a Contact or a String as the search parameter. The items() method of the RemoteLookupListener object specified to the method is invoked when a result is returned from the BES.
Click here to view a code sample on how to do a GAL lookup.
final class RemoteLookupDemo implements RemoteLookupListener
{
public void items(Enumeration results)
{ |
You can launch PIM applications using the native invoke APIs. For additional information on invoking applications, see the Application Integration overview.
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.