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.
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. |
The specification is presented in HTML and is split into two major specification areas:
This document uses definitions based upon those specified in IETF RFC 2119 (See http://www.ietf.org).
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. |
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. |
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.
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.
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:
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.
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:
PIM.openContactList(),
PIM.openEventList()
, and PIM.openToDoList()
).PIM.listContactLists(),
PIM.listEventLists()
, and PIM.listToDoLists()
)
MUST be the unique name of the designated default list
for that PIM list type.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.
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.
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.
This section discusses concepts that are fundamental issues for the implementers of the PIM API package.
PIMElement.toSerialFormat()
and PIMElement.fromSerialFormat()
).
The standard fields for a PIM element already have
mappings defined in the API to their corresponding vCard
and vCalendar tags. It is the responsibility of the PIM
API implementation to map any extended fields supported
in the PIM lists to valid vCard and vCalendar tags,
according to the syntax defined for those API
definitions. Implementations may map extended fields to
the extended field syntax defined in those APIs (i.e.
prefixed with "X-"), or implementations may map
extended fields to actual field tags not explicitly
supported in the PIM API (e.g. ANNIVERSARY). If an
implementation maps extended fields to actual field tags,
the implementation is responsible to ensure that the
element will produce a valid vCard or vCalendar entry
when exported or imported.PIMElement.getFieldLabel
and PIMElement.getFieldDataType
.
Even though these methods are in the PIMElement class,
this does not imply that data types and field labels per
element must be supported (e.g. supporting a different
field label for the same field for every element).
Implementations MAY support field labels per element. If
not, implementations should use the same field labels for
a field in every element belonging to the same list (e.g.
the same field label applies to the NAME_FAMILY field for
all elements in a particular list). 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/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.