|
PIM Optional Package 1.0 Final Release |
|||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||
See:
Description
| Packages | |
| javax.microedition.pim | The PIM package defines APIs to access Personal Information Management (PIM) data. |
This document, PIM Optional Package Specification, defines the APIs that comprise the Personal Information Management (PIM) optional package for Java 2� Platform, Micro Edition (J2ME�).
This document defines a set of APIs known as the Personal Information Management (PIM) APIs for Java� 2 Platform, Micro Edition (J2ME�). These APIs are included in J2ME profiles as an optional package. Optional packages are API sets that may be licensed and added on top of J2ME configuration and profile implementations by vendors independent of the JSR process. This allows VM implementations to increase the functionality they offer while still providing APIs that are defined as a standard by the Java community.
The PIM APIs were developed by as part of JSR 75. There is no dependency of these PIM APIs upon any other APIs produced in JSR 75, and the PIM APIs can be licensed and packaged separately from any other J2ME configuration, profile, or optional package.
This document and 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.
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. |
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, located on SIM cards attached to the device, 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. That allows the PIM APIs to be deployed as an optional API package on any J2ME profile that supports CLDC 1.0 or higher.
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.
Because of its optional nature, this package of APIs may not always be available
on every platform. Each profile and platform may have their own methods for
J2ME package discovery as there is no universal method existing at this
time. An additional method for package discovery of the PIM APIs is by
using a system properties query. To discover this package, call
System.getProperty with a key of
microedition.pim.version. If the API is present, the
value returned is the version of the API (e.g. "1.0"). If the API is not
present then the key is also not present and null
is returned.
There are three types of PIM lists accessible through this API: ToDoList,
EventList, and ContactList. PIM implementations MUST support at least one type
of PIM list (either ToDoList, EventList, or ContactList). For example, an
implementation may choose to support only ContactList PIM access should the
ToDoList and EventList databases 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.openPIMList(int,
int) and PIM.openPIMList(int, int, String))
MUST return a PIMException when invoked with the correspoding PIM
list type. 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 ToDoList, 2 EventList,
and 0 ContactList. 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 PIM.openPIMList(int, int 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.openPIMList(int, int)).
PIM.listPIMLists()) 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 are not required to persist all fields originally contained in an PIM item imported into a list describing a native PIM database. Implementations MAY choose to persist only the fields that are supported in the underlying native PIM database. Handling of those fields that are not supported in the underlying PIM databases is left up to the implementation. For instance, assume a platform's native address database only supports one address per entry. Then assume an address item is created from a vCard data string containing two addresses. If that item is imported to the native address database through a corresponding PIM list, the PIM list 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 extended fields and mapped correctly by the implementation to their corresponding vCard or vCalendar type field.
vCard 2.1 is the default vCard version supported in the PIM API and MUST be supported if the implementation supports contact lists. UTF-8 MUST be supported on the platform as a character encoding method for vCard 2.1 entries ("charset" in vCard 2.1 terminology). Additionally, the Quoted-Printable and Base64 encodings for binary content as defined by RFC 1521 must be supported by an implementation. Implementations MAY also support other character encoding methods in addition to UTF-8.
Implementations MAY also support other versions of the vCard specification. If other versions are supported, both importing and exporting in that vCard format must be supported (i.e. import only or export only is not allowed; it must be both).
vCalendar 1.0 is the default vCalendar version supported in the PIM API and MUST be supported if the implementation supports event lists or to do lists. UTF-8 MUST be supported on the platform as a character encoding method for vCalendar 1.0 entries ("charset" in vCalendar 1.0 terminology). Additionally, Quoted-Printable and Base64 encoding for binary content as defined by RFC 1521 must be supported by an implementation. Implementations MAY also support other character encoding methods in addition to UTF-8.
Implementations MAY support other versions of the vCalendar specification. If other versions are supported, both importing and exporting in that vCard format must be supported (i.e. import only or export only is not allowed; it must be both).
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 item, the PIM list serializes these calls
properly, and no database corruption occurs as a result. However, the latter of
the writes is subsequently overwritten by the other, which may cause problems
within the application.
Synchronization issues may also exist if a platform allows access to the native underlying database outside of the Java realm (e.g. through native platform synchronization or through native PIM applications). In these cases it is the platform's responsibility to enforce exclusive access to the PIM data between the J2ME application and native applications to ensure proper serialization and updating of the data.
However, the PIM API is not required to handle multitasking environments and concurrent access to PIM data. For example, in multitasking environments categories in a particular Contact list may be modified by a native application concurrently when a Java application is accessing the same Contact list. In these scenarios, there is no guarantee that the Java PIM lists accurately reflect real-time changes to the underlying PIM databases. The result in these cases are implementation dependent (e.g. some may not reflect the changed categories until the categories are specifically read using PIMList.getCategories, while others may accurately update the Java PIM list's category list). In general, this PIM API is targeting constrained devices that usually allow one application to be running at a single instance on the platform. In these cases, the synchronization issues are non-existent.
It is the responsibility of the J2ME platform that the PIM APIs are deployed on to provide a security model supporting the security of the PIM APIs. Specifically:
javax.microedition.pim
package that throw SecurityExceptions.The implementation of the model is left up to the including profile or platform.
If the including profile is MIDP 2.0 (as defined by JSR 118), then included with this specification is an addendum outlining a Recommended Practice for using the FileConnection APIs within the MIDP 2.0 security model. That addendum can be found here.
This section discusses concepts that are fundamental issues for the implementers of the PIM API package.
PIM.toSerialFormat()
and PIM.fromSerialFormat()).
The standard fields for a PIM item 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 SHOULD map extended fields to corresponding actual
field tags not explicitly supported in the PIM API if possible (e.g. a sound
extended field should map to vCard property SOUND). If an implementation maps
extended fields to actual field tags, the implementation is responsible to
ensure that the item produces a valid vCard or vCalendar entry when exported or
imported. If not mapped to explicit vCard or vCalendar tags, implementations
SHOULD map extended fields to the extended field syntax defined in those APIs
(i.e. prefixed with "X-").PIMItem.EXTENDED_FIELD_MIN_VALUE
and PIMItem.EXTENDED_ATTRIBUTE_MIN_VALUE, respectively.Table: Contact Field Mappings
| Contact Field and Attributes | vCard 2.1 Property Name/Property Parameters | vCard 3.0 Type Property Name/Property Parameters |
|---|---|---|
| ADDR | ADR | ADR |
| ADDR_COUNTRY | 7th address component in the semi-colon separated string type value in ADR | 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 | 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 | 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 | 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 | 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 | 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 | 3rd address component in the semi-colon separated string type value in ADR |
| BIRTHDAY | BDAY | BDAY |
| CLASS | Implementation specific mapping | CLASS |
| EMAIL/INTERNET | EMAIL/INTERNET | |
| FORMATTED_ADDR | LABEL | LABEL |
| FORMATTED_NAME | FN | FN |
| NAME | N | N |
| NAME_FAMILY | 1st name component in the semi-colon separated string type value in N | 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 | 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 | 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 | 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 | 5th name component in the semi-colon separated string type value in N |
| NICKNAME | NICKNAME | NICKNAME |
| NOTE | NOTE | NOTE |
| ORG | ORG | ORG |
| PHOTO | PHOTO (inline specification of photo) | PHOTO (inline specification of photo) |
| PHOTO_URL | PHOTO/VALUE=URL | PHOTO/VALUE=URL |
| PUBLIC_KEY | KEY (inline binary specification) | KEY |
| PUBLIC_KEY_STRING | KEY (default text string) | KEY |
| REVISION | REV | REV |
| TEL | TEL/VOICE | TEL/VOICE |
| TITLE | TITLE | TITLE |
| UID | UID | UID |
| URL | URL | URL |
| ATTR_ASST | Implementation specific mapping | Implementation specific mapping |
| ATTR_AUTO | CAR property parameter | CAR property parameter |
| ATTR_FAX | FAX property parameter | FAX property parameter |
| ATTR_HOME | HOME property parameter | HOME property parameter |
| ATTR_MOBILE | CELL property parameter | CELL property parameter |
| ATTR_OTHER | Implementation specific mapping | Implementation specific mapping |
| ATTR_PAGER | PAGER property parameter | PAGER property parameter |
| ATTR_PREFERRED | PREF property parameter | PREF property parameter |
| ATTR_SMS | MSG property parameter | MSG property parameter |
| ATTR_WORK | WORK property parameter | WORK property parameter |
| ATTR_NONE | no mapping | no mapping |
Table: Event Field Mappings
| Event Field | vCalendar 1.0 Property Name/Property Parameters |
|---|---|
| ALARM | DALARM/DATE-TIME (implementations may also additionally set AALARM in concert with this property) |
| CLASS | CLASS |
| END | DTEND |
| LOCATION | LOCATION |
| NOTE | DESCRIPTION |
| REVISION | LAST-MODIFIED |
| START | DTSTART |
| SUMMARY | SUMMARY |
| UID | UID |
Table: ToDo Field Mappings
| ToDo Field | vCalendar 1.0 Property Name/Property Parameters |
|---|---|
| CLASS | CLASS |
| COMPLETION_DATE | COMPLETED |
| COMPLETED | COMPLETED (presence of field indicates completed is true) |
| DUE | DUE |
| NOTE | DESCRIPTION |
| PRIORITY | PRIORITY |
| REVISION | LAST-MODIFIED |
| SUMMARY | SUMMARY |
| UID | UID |
PIM.contactSerialFormats(),
PIM.eventSerialFormats(), and PIM.toDoSerialFormats()
must follow a consistent naming convention. The naming convention is the common
name of the data format in all capital letters, followed by a slash ("/")
followed by the version number of the data format. For example, "VCARD/2.1",
"VCARD/3.0" and "VCALENDAR/1.0". The formats required by this spec and/or any
formats required by an including profile must be returned first in the string
arrays returned from the aforementioned methods (i.e. "VCARD/2.1" must be the
first item in the array returned from PIM.contactSerialFormats() and
"VCALENDAR/1.0" must be the first item in the arrays returned from PIM.eventSerialFormats()
and PIM.toDoSerialFormats(). The following table outlines the
naming convention for some current well known PIM protocols.| PIM Data Format | PIM API String |
|---|---|
| vCard 2.1(http://www.imc.org/pdi/vcard-21.txt) | VCARD/2.1 |
| vCard 3.0 (http://www.ietf.org/rfc/rfc2426.txt) | VCARD/3.0 |
| vCalendar 1.0 (http://www.imc.org/pdi/vcal-10.txt) | VCALENDAR/1.0 |
| iCalendar (a.k.a. VCALENDAR 2.0) (http://www.ietf.org/rfc/rfc2445.txt) | VCALENDAR/2.0 |
PIMList.getSupportedFields()
in an order similar, if not identical, to the display ordering of those same
fields in any corresponding native PIM application. This allows Java
applications using the PIM APIs to maintain a semblance of platform continuity
in their application (i.e. trying to maintain look and feel of the platform's
applications).
|
Final Release Rev. 1.00 |
|||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||