J2ME Personal Information Management (PIM) - An Overview

Providing the ability to access the native personal data on mobile devices

The Personal Information Management (PIM) API, as defined by JSR 75, provides a way to access the native personal data on the mobile devices, be it the Contacts, Tasks or Appointments. In this article, we will have a close look at the API, discuss the development, security and deployment considerations of a PIM MIDlet and compare PIM with another J2ME API, the Record Management Store (RMS).

Share:

Soma Ghosh (soma.sghosh@gmail.com), Technical Architect, US Foodservice

Soma Ghosh, a graduate in Computer Science and Engineering has designed and developed a wide range of eCommerce and Internet based applications and authored several articles on J2ME. She takes keen interest in application development on mobile devices. She is currently associated with IT Department in US Foodservice and can be reached at soma.sghosh@gmail.com.



07 December 2009

Also available in Chinese Japanese

Personal Information Management (PIM) in mobile environment

As new devices make to the market, the availability of Address Book, Calendar and Task list on mobile devices is a bare necessity. The J2ME applications also feel the need to have access to these data. The optional package JSR 75 Personal Information Management (PIM) package provides this capability.

It not only allows the access to native personal information which comprises contacts, appointments and tasks, also to information based on SIM cards attached to devices, Local and Remote Personal Information databases.

The PIM package has capability to export and import of data from vCard and vCalendar, the Internet standard formats for Address Book and Calendar respectively. It also has the security features to prevent unauthorized classes from retrieving personal information.

The other optional package, JSR 75 File Connection provides a way to access the native file system which is out of scope for our discussion.


The J2ME PIM package

The Java PIM package is represented by the javax.microedition.pim package.

The significant interfaces defined by this package are:

  1. Contact – This Interface represents a single contact on the Address Book.
  2. ContactList – This Interface represents Address Book which is a list of Contacts.
  3. Event – This Interface represents a single Calendar Event.
  4. EventList – This Interface represents a list of Calendar events.
  5. ToDo – This Interface represents a single Task in the Task List.
  6. ToDoList – This Interface represents the Task list.

The major class defined by this package is:

PIM – The PIM class defines methods that can create an index of all existing Lists, open and edit those lists as well as import and export from Internet standard formats for Contact and Calendar, the vCard and vCalendar.

Contact and ContactList

A Contact represents a single entry in the Address Book. The major fields in a Contact are Name, Address, Email, Birthday, Photo and Telephone.

In order to ensure portability across platforms, it is advisable to use the method isSupportedField() provided by Super Interface PIMList.

Listing 1, below shows how a Contact can be added to Address Book:

Listing 1. Add Contact to Address Book
ContactList addressBook = null;
 try {
    addressBook = (ContactList) PIM.getInstance().openPIMList(PIM.CONTACT_LIST, 
                                                                     PIM.READ_WRITE);
 } catch (PIMException e) {
    // Exit Application
 }


Contact singleContact = addressBook.createContact();
String[] name = new String[addressBook.stringArraySize(Contact.NAME)];

if (addressBook.isSupportedField(Contact.NAME_FORMATTED)
	singleContact.addString(Contact.NAME_FORMATTED, 
                        PIMItem.ATTR_NONE, "Mrs. Jane Doe");


The createContact() method creates a temporary empty Contact. A commit() call makes 
the Contact data persistent. It is advisable to close the lists by invoking the close()
 method after necessary operations have been performed.

try {
      singleContact.commit();
 } catch (PIMException e) {
      // Exception occured
 }

try {
// Other cleanup tasks
      addressBook.close();
 } catch (PIMException e) {

 }

Event and Event List

An Event represents a single entry in the Event database, for example; calendar on the mobile device. The critical fields are Location, Summary, Start date, End Date and Alarm notification. Listing 2 shows how an Event can be added to the Event database.

Listing 2. Add an Event
EventList eventList = null;
 try {
    eventList = (EventList) PIM.getInstance().openPIMList(PIM.EVENT_LIST, 
                                                            PIM.READ_WRITE);
 } catch (PIMException e) {
    return;
 }
 Event singleEvent = eventList.createEvent();
 if (eventList.isSupportedField(Event.SUMMARY))
      singleEvent.addString(Event.SUMMARY, PIMItem.ATTR_NONE, "Java Training");
 if (eventList.isSupportedField(Event.START))
      singleEvent.addDate(Event.START, PIMItem.ATTR_NONE, aDate.getTime());
 if (eventList.isSupportedField(Event.END))
      singleEvent.addDate(Event.END, PIMItem.ATTR_NONE, aDate.getTime());

try {
      singleEvent.commit();
 } catch (PIMException e) {
      // An error occured
 }
 try {
      eventList.close();
 } catch (PIMException e) {

 }

ToDo and ToDo List

The ToDo interface represents a single task on the Task database on the mobile device. The important fields are Note or Summary, Priority, Completion Date, Due Date and whether completed. Listing 3 shows how a ToDo can be persistently added to the database.

Listing 3. Add a Task
ToDoList tasks = null;
 try {
    tasks = (ToDoList) PIM.getInstance().openPIMList(PIM.TODO_LIST, 
                                                        PIM.READ_WRITE);
 } catch (PIMException e) {
    // An error occurred
    return;
 }
 ToDo singleTask = tasks.createToDo();
 if (tasks.isSupportedField(Event.SUMMARY))
      singleTask.addString(ToDo.SUMMARY, PIMItem.ATTR_NONE, "Shopping for Halloween");
 if (tasks.isSupportedField(Event.DUE))
      singleTask.addDate(ToDo.DUE, PIMItem.ATTR_NONE, new Date().getTime());

try {
      singleTask.commit();
 } catch (PIMException e) {
      // An error occured
 }
 try {
      tasks.close();
 } catch (PIMException e) {

 }

How PIM differs from RMS

Before going further on this discussion, let us review the concept of Record Management Store (RMS), another key functionality by J2ME. RMS allows J2ME applications to persistently store data locally. The components of RMS are as follows:

Records – Unlike the Database systems where each record has one or more fields, a Record in RMS is an individual data field. It does not have a pre-defined data type or size and can contain any data.

RecordStore – A RecordStore is a collection of Records and is accessible from J2ME applications by name.

This is how PIM differs from RMS while both are responsible for storing persistent data on the device.

  1. PIM stores and retrieves data to and from defined entities like the Address Book, Calendar and Task List. RMS, on the other hand, stores data to and retrieves data from a general database. A single entity in PIM is a Contact, Calendar entry or a Task while in RMS, it’s a byte array.
  2. PIM is not restricted to the local device. It can access data from an attached SIM or another remote device. RMS only accesses data to and from local device.
  3. PIM can export and import from external sources like vCalendar or vContact. RMS does not have any Export or Import capabilities.
  4. The interpretation of data in PIM is more flexible compared to RMS. Say, a Contact, defined in a standard format, can always be interpreted by another J2ME application with ease. A record in RMS is a byte array and other J2ME applications will need to have information on how to interpret.

An example – Add a contact

In this section, we will discuss a method mentioned as addContact() on how to add a contact to the Address Book. This method as in Code-4 can be invoked in a separate thread when a user command is submitted on the form. This method accesses data entered through UI Textfields.

Listing 4. addContact() method
// Import
import javax.microedition.lcdui.*;
import javax.microedition.midlet.*;
import javax.microedition.pim.*;


// Text input
TextField nameField;
TextField phoneField;

…

public void addContact () {

    ContactList contacts = null;

	try {
	    contacts = (ContactList) PIM.getInstance().openPIMList(PIM.CONTACT_LIST, 
                                                                PIM.READ_WRITE);
	} catch (PIMException e) {
	    // An error occurred
	    e.printStackTrace();
	 }

	 Contact contact = contacts.createContact();

	 String[] name = new String[contacts.stringArraySize(Contact.NAME)];

	 if (contacts.isSupportedArrayElement(Contact.NAME, Contact.NAME_GIVEN))
	       name[Contact.NAME_GIVEN] = nameField.getString();

	  if (contacts.isSupportedField(Contact.TEL))
	     contact.addString(Contact.TEL, Contact.ATTR_HOME, phoneField.toString());

try {

	 contact.commit();
		
} catch (Exception e) {}


	}

Runtime and security considerations

The PIM MIDlet should be run in a configuration that supports PIM i.e. JSR 75. We selected the below settings on Sun’s Wireless Toolkit 2.5 by clicking Settings and then API Selection. The same applies to selection of mobile devices for PIM MIDlet to run.

Figure 1. PIM MIDlet Runtime API Selection
PIM MIDlet Runtime API Selection

The MIDlet will require additional permissions while attempting to read and write the Contacts, Calendar or Task Lists. This can be accomplished by clicking Settings and selecting Permissions from the Wireless toolkit. All the Read and Write permissions for ContactList, EventList and TodoList have been provided.

Figure 2. PIM MIDlet Security considerations
PIM MIDlet Security considerations

Conclusion

In this article we discussed about another important functionality in J2ME called Personal Information Management (PIM) that allows access to the native data on the mobile device in the form of Contact, Task and Event. It also draws a comparison with RMS, another functionality that deals with device data. With the inherent export and import capabilities, it is now possible to sync up J2ME applications with vCard and vCalendar, the internet standard format for Contact and Calendar respectively. We concluded with the security and deployment requirements at runtime.

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into SOA and web services on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=SOA and web services
ArticleID=454188
ArticleTitle=J2ME Personal Information Management (PIM) - An Overview
publish-date=12072009