PIM basics
Before jumping into the installation of the BlackBerry JDE and building the
application, let's cover some PIM basics.
PIM data elements
The most common and universal data elements on a mobile device, including the BlackBerry platform, include:
- Addresses or contacts
- Such as your cousin's work phone number
- Calendar/date-book events
- Such as a lunch meeting with a prospective client next Thursday
- To-do items
- For example, bring home milk and eggs from the grocery store
These data elements have been with us forever, or at least since the
Palm Pilot revolutionized the Personal Digital Assistant (PDA) market a few years ago. Collectively, the data elements are known as PIM items.
Every major mobile platform supports these data elements and supports the common
desktop software such as Microsoft® Outlook, Lotus Notes®, and many other productivity
application suites. An entire industry of synchronization software has grown up
around the seemingly simple, yet difficult, task of synchronizing PIM data among
various data sources. Synchronization of data between the BlackBerry device and the
desktop (or server environments) is a broad topic and is not the focus of this tutorial.
This tutorial focuses on interacting with the PIM data directly on the device for
two reasons:
- Many users don't actually sync their data with a desktop application.
If they sync at all, it is with a Web-based social-networking application.
- More importantly, at the core of a social-networking application is your PIM
data. Social networking is about connecting, sharing, and, arguably, peering into what your friends and associates are doing — right now.
Next, you'll learn about some of the packages and classes available in the BlackBerry SDK for interacting with the PIM database.
PIM data APIs
PIM data is used primarily by three applications on the BlackBerry: the address
book, the calendar application, and the tasks application. With these
applications, data is entered, stored, retrieved, and manipulated. Figure 1 shows
a simple event recorded for a dinner at 5 p.m.
Figure 1. Event in the BlackBerry calendar application
This event is shown in the calendar application. The summary of the event is "Dinner
with In-Laws" and the location is Taco Bell. Drilling down into the event shows more
information.
Figure 2. Details of an event
You can set the start and end times of the event, specify a reminder for the event, and
even mark the event as recurring, among other things. This is all good, but this
tutorial is more interested in how you can interact with the data programmatically, so
let's look at the Event data class in more detail.
When working with the BlackBerry SDK/APIs for PIM data, you need to be aware of two levels of classes:
javax.microedition.pim- A package containing the generic PIM data. The classes in this package are found on devices beyond the BlackBerry and represent the core
PIMItems.
net.rim.blackberry.api.pdap- A package containing BlackBerry-specific extensions to the
javax.microedition.pim classes.
The Event class in the javax.microedition.pim package extends PIMItem, a more basic super class. The PIMItem is a generic PIM data element containing a collection of data fields. PIMItems may be organized into a PIMList, which is a collection of PIMItems. The specific fields supported by a particular platform may vary and are determined by the PIMList in which the PIMItem is stored.
Data fields within a PIMItem may be of a variety of data
types. The common data types are:
- String
- Stringarray
- Date
- Integer
- Boolean
- Binary
The PIMItem class includes, as you might suspect, several getters and setters for manipulating the data. Each data field includes:
- A label to describe it, such as phone number.
- Zero or more data values, which are a zero-indexed list of values. The
get and set methods have an index parameter to assist in managing this data.
- Attributes for the data values.
- A specific data type.
Field names are identified by integer values defined in the Contact, Event, and ToDo classes. Table 1 shows a sampling of field names and the data type found in the Event class.
Table 1. Sample Event data fields
| Field Name | Data Type |
|---|
| Summary, Location | String | | Start, End | Date | | Alarm | Integer |
The date value is actually stored as a long integer, which is compatible with the java.util.Date class. This will be used in the sample application code.
Retrieving PIM data
As mentioned, PIMItems, such as Events, Contacts, and ToDos, are stored in PIMLists. There may
be multiple PIMLists available on a device, though
typically, you'll encounter a single default list of PIM data. To gain access to the
lists of PIM data, you must first obtain a reference to the PIM database through the javax.microedition.pim.PIM class: PIM pim = PIM.getInstance();.
The static method getInstance() retrieves an instance of the
PIM database, which is required for subsequent operations. This class also includes
methods for opening existing PIMLists and for serializing a PIMItem to an input/output stream. These methods, toSerialFormat and fromSerialFormat, are typically used for backup or synchronization purposes. They are not used in this tutorial's sample application.
The sample application employs the openPIMList method to
obtain a PIMList containing PIMItems. There are two openPIMList
methods: one opens the default PIMList, and the other takes a String argument for a specific, named PIMList.
You can use the listPIMLists method to obtain a list of available PIMList names. This method returns a string array containing a PIMList name in each array element.
The proliferation of classes and methods including the word "lists" can be a little
confusing. Take care to note data types in the BlackBerry Java API documentation. The sample application simply accesses the default PIMList. Regardless of which openPIMList method is employed, there are two arguments required:
pimListType- May be
CONTACT_LIST, EVENT_LIST, or TODO_LIST
mode- May be READ_ONLY, WRITE_ONLY, or READ_WRITE
Once a PIMList is open, the application can access the
elements by employing an enumeration. To examine all of
the contacts within a particular CONTACT_LIST or PIMList, you could use the code in Listing 1.
Listing 1. Accessing contacts from the PIM database
BlackBerryPIMList contactList = (BlackBerryPIMList)
pim.openPIMList(PIM.CONTACT_LIST,PIM.READ_ONLY);
For (Enumeration eContacts = contactList.items();eContacts.hasMoreElements();)
{
Contact contact = (Contact) eContacts.nextElement();
// do something with contact
}
|
To access a field within a specific PIMItem, use the getString() method in Listing 2.
Listing 2. getString() method to access a field within a specific PIMItem
String emailAddress = c.getString(Contact.EMAIL,0);
|
The PIM database also allows categorization for easy management of PIM data. PIM categories are not discussed in this tutorial, but are straightforward to implement.
At this point, you know what PIM data looks like, where to find it, and how to access it.
In the next section, you'll construct a social-networking application for the BlackBerry.
| 
