PIM API Specification

JCP Public Draft Specification

Java 2 Platform, Micro Edition


Copyright 2002, PalmSource, Inc. ALL RIGHTS RESERVED.


Preface

This document, PIM API Specification, defines a set of APIs known as the Personal Information Management (PIM) APIs for JavaTM 2 Platform, Micro Edition (J2METM). These APIs MUST be included and implemented in the PDA Profile, but also may be included in other J2ME profiles as an optional package.

This specification is a work in progress, and still has some open issues that the expert group will resolve before the specification is final. This is intended to give the public a good indication of the kind of functionality that the JSR 75 expert group is intending to produce.

This document all all associated documents are subject to the terms of the JCP agreements (i.e. JSPA and/or IEPA), available at http://www.jcp.org. The version of the Java Community Process (JCP) procedures followed is version 2.1, dated July 10, 2001.

Revision History

Table 1 Revision History

Date Revision Description
December 17, 2001 0.10 Initial revision of a separate spec for the PIM API Optional Package.
March 4 , 2002 0.11 Proposed Community Review version; no changes in this document from 0.10.
March 5, 2002 0.12 Community Review version; no changes.
April 8, 2002 0.13 Post Community Review ; clarify the PIM optional package and its target platform. Released to expert group only since not all CR comments incorporated yet.
April 19, 2002 0.14 Another post Community Review Draft. Various updates to spec based on community review and expert group feedback. Needed to resync base point for expert group discussions.
May 6, 2002 0.15 Proposed Public Review Draft. Submitted to expert group for approval.
May 15, 2002 0.16 Second proposed Public Review Draft and one submitted for actual Public Review. Contains resolved issues from expert group discussions.

 

How This Specification Is Organized

The specification is presented in HTML and is split into two major specification areas:

 

Document Conventions

Definitions

This document uses definitions based upon those specified in IETF RFC 2119 (See http://www.ietf.org).

Table 2 Specification Terms

Term Definition
MUST The associated definition is an absolute requirement of this specification.
MUST NOT The definition is an absolute prohibition of this specification.
SHOULD Indicates a recommended practice.  There may exist valid reasons in particular circumstances to ignore this recommendation, but the full implications must be understood and carefully weighed before choosing a different course.
SHOULD NOT Indicates a non-recommended practice.  There may exist valid reasons in particular circumstances when the particular behavior is acceptable or even useful, but the full implications should be understood and the case carefully weighed before implementing any behavior described with this label.
MAY Indicates that an item is truly optional.

Formatting Conventions

This specification used the following formatting conventions.

Table 3 Formatting Conventions

Convention Description
Courier Used in all Java code including keywords, data types, constants, method names, variables, class names, and interface names.
Italic Used for emphasis and to signify the first use of a term.

 

Overview

The primary goal of the PIM APIs is to provide access to Personal Information Management (PIM) data on J2ME devices. PIM data is defined as information included in address book, calendar application, and to do list applications. In addition, implementations can provide access to PIM databases that are not resident on the device but at well known locations, or to PIM databases created and managed by the Java VM itself. This allows implementations of the PIM API to provide PIM databases on devices that previously did not have them, as well as providing access to remote PIM databases from a J2ME device.

Applicable Platform

CLDC 1.0 is the minimum required platform for this API set. The APIs in this package only depends on APIs required by the CLDC 1.0 API set.

Specification Requirements

This section lists explicit requirements of this specification. Implementations of the PIM API must follow these requirements. Profiles including this PIM API package may require additional requirements above and beyond the ones listed here.

Compliant PIM API implementations:

API Goals

The goals for the PIM APIs are as follows:

Given these goals, a new API was devised to access PIM data in the most efficient manner possible.  The API resides in a new J2ME package, javax.microedition.pim. Detailed description of  the PIM API scan be found in the JavaDoc API Specification.

PIM List Support

There are three types of PIM lists accessible through this API: ToDo, Event, and Contact. PIM implementations MUST support at least one type of PIM list (either ToDo, Event, or Contact). For example, an implementation may choose to support only Contact PIM access should the ToDo and Event lists not exist or are not applicable on the implementation's platform. If a type of PIM list is not supported, then the methods used to access the unsupported PIM list (i.e. PIM.openContactList(), PIM.openContactList(String), PIM.openEventList(), PIM.openEventList(String), PIM.openToDoList(), or PIM.openToDoList(String)) MUST return a PIMException when invoked. PIM implementations SHOULD support all three types of PIM lists to enhance the compatibility of the implementation with all PIM API applications.

For each PIM list type that an implementation supports, at least one PIM list MUST be supported (e.g. at least one list must be able to be opened). Implementations MAY support any number of PIM lists of each PIM list type that it supports. For example, an implementation may have 1 ToDo list, 2 Event lists, and 0 Contact lists. Each PIM list must have a name assigned to it that is unique among all PIM lists of that same type on the platform. The name of each PIM list is used to open the list using an appropriate PIM method (i.e. PIM.openContactList(String), PIM.openEventList(String), or PIM.openToDoList(String)).

Additionally, if one or more lists exist for a particular PIM list type, one of those lists MUST be designated by the implementation as the default list for that PIM type. The designation is used in two locations:

Native Database Support

If a PIM API list is mapped to an underlying native PIM database, the PIM API list SHOULD be the default list for that given PIM list type. If more than one underlying native PIM database for a given PIM type (e.g. ContactList, EventList, or ToDoList) is also mapped to another PIM API list, only one of those PIM lists SHOULD be designated as the default.

Implementations MAY persist in the PIM lists only the fields from each PIM element that are supported in the underlying native PIM databases.  Handling of fields that are not supported in the underlying PIM databases is left up to the implementation.  For instance, assume one's native address database only supports one address per entry.  Then assume an address entry is created from an imported vCard containing two addresses. If that entry is added to the native address database through the PIM API, the implementation could ignore and discard the second address, it could map the address to an available custom field in the database, or it could append the address as a note to the entry.

vCard and vCalendar Support

The PIM API provides support for importing and exporting its PIM data in vCard and vCalendar formats. This support is provided so that the PIM API can communicate with external PIM databases via a well-known industry standard. This PIM API is not meant to be a Java version of the vCard and vCalendar standards; the PIM API's main goal is providing access to a device's native PIM data. vCard and vCalendar are only adopted for its applicability to communicating with other PIM databases in a standard way.

The PIM API does not explicitly support all fields described in the vCard and vCalendar data formats.  Support for vCard and vCalendar in the PIM APIs is defined such that all of the data accessible in a native PIM database through the PIM API can in turn be expressed as vCard or vCalendar data when importing or exporting. 

The PIM API PIM fields that are not also vCard or vCalendar defined fields are mapped to extended fields in those formats (i.e. prefixed with "X-") when exporting. vCard or vCalendar fields that are present in the underlying PIM databases but not expressed as explicit fields in the APIs are accessed as extend fields and mapped correctly by the implementation to their corresponding vCard or vCalendar type field.

Access Synchronization

No locking operations are provided in this API. PIM implementations ensure that all individual PIM list record operations are atomic, synchronous, and serialized so that no corruption occurs with multiple accesses. However, if an application uses multiple threads to access a PIM list, it is the application's responsibility to coordinate this access, or unintended consequences may result. For example, if two threads in an application both call Contact.commit() concurrently on the same contact element, the PIM list will serialize these calls properly, and no database corruption will occur as a result. However, one of the writes will be subsequently overwritten by the other, which may cause problems within the application.

Similarly, if a platform performs transparent synchronization of the underlying database for a PIM list or other access from below, it is the platform's responsibility to enforce exclusive access to the PIM data between the application and synchronization engine.

Implementation Notes

This section discusses concepts that are fundamental issues for the implementers of the PIM API package.

Table: Contact Field Mappings

Contact Field/Type vCard 3.0 Type Field/Parameter
ADDR_COUNTRY 7th address component in the semi-colon separated string type value in ADR
ADDR_EXTRA 2nd address component in the semi-colon separated string type value in ADR
ADDR_LOCALITY 4th address component in the semi-colon separated string type value in ADR
ADDR_POBOX 1st address component in the semi-colon separated string type value in ADR
ADDR_POSTALCODE 6th address component in the semi-colon separated string type value in ADR
ADDR_REGION 5th address component in the semi-colon separated string type value in ADR
ADDR_STREET 3rd address component in the semi-colon separated string type value in ADR
TEL TEL/VOICE
FAX TEL/FAX
EMAIL EMAIL/internet
BIRTHDAY BDAY
FORMATTED_NAME FN
NAME_FAMILY 1st name component in the semi-colon separated string type value in N
NAME_GIVEN 2nd name component in the semi-colon separated string type value in N
NAME_OTHER 3rd name component in the semi-colon separated string type value in N
NAME_PREFIX 4th name component in the semi-colon separated string type value in N
NAME_SUFFIX 5th name component in the semi-colon separated string type value in N
NICKNAME NICKNAME
NOTE NOTE
ORG ORG
TITLE TITLE
PUBLIC_KEY KEY
URL URL
UID UID
REVISION REV
PHOTO PHOTO
TEL/TYPE_OTHER Implementation specific
FAX/TYPE_OTHER Implementation specific
ADDR_*/TYPE_OTHER Implementation specific
EMAIL/TYPE_OTHER Implementation specific
TEL/TYPE_HOME TEL/HOME
FAX/TYPE_HOME TEL/HOME,FAX
ADDR_*/TYPE_HOME ADR/HOME
EMAIL/TYPE_HOME Implementation specific
TEL/TYPE_WORK TEL/WORK
FAX/TYPE_WORK TEL/WORK,FAX
ADDR_*/TYPE_WORK ADR/WORK
EMAIL/TYPE_WORK Implementation specific
TEL/TYPE_MOBILE TEL/CELL
FAX/TYPE_MOBILE TEL/CELL,FAX
EMAIL/TYPE_MOBILE Implementation specific
TEL/TYPE_PAGER TEL/PAGER
FAX/TYPE_PAGER TEL/PAGER,FAX
EMAIL/TYPE_PAGER Implementation specific
TEL/TYPE_AUTO TEL/CAR
FAX/TYPE_AUTO TEL/CAR,FAX
EMAIL/TYPE_AUTO Implementation specific
TEL/TYPE_ASSISTANT Implementation specific
FAX/TYPE_ASSISTANT Implementation specific
EMAIL/TYPE_ASSISTANT Implementation specific

Table: Event Field Mappings

Event Field vCalendar 1.0 Type Field/Parameter
END DTEND
START DTSTART
ALARM VALARM/DATE-TIME
SUMMARY SUMMARY
LOCATION LOCATION
NOTE DESCRIPTION
UID UID
REVISION LAST_MODIFIED

Table: ToDo Field Mappings

ToDo Field vCalendar 1.0 Type Field/Parameter
DUE DUE
COMPLETED COMPLETED
SUMMARY SUMMARY
NOTE DESCRIPTION
PRIORITY PRIORITY
UID UID
REVISION LAST_MODIFIED

Categories for elements are mapped to the vCalendar and vCard CATEGORIES type value.