overview-summary.html

J2ME手机编程规范JSR-75文档

The designation is used in two locations:</p>

<ul>
    <li>The default list for a PIM list type MUST be accessed
        through the open list method with no parameters (i.e. <code>PIM.openPIMList(int,
        int)</code>).</li>
    <li>The first element in the String array returned by the
        PIMList list method (i.e. <code>PIM.listPIMLists()</code>)
        MUST be the unique name of the designated default list
        for that PIM list type.</li>
</ul>

<h2>Native Database Support</h2>

<p>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.</p>

<p>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.&nbsp; Handling of those fields that are not
supported in the underlying PIM databases is left up to the
implementation.&nbsp; For instance, assume a platform's native
address database only supports one address per entry.&nbsp; 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.</p>

<h2>vCard and vCalendar Support</h2>

<p>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.</p>

<p>The PIM API does not explicitly support all fields described
in the vCard and vCalendar data formats.&nbsp; 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.&nbsp;</p>

<p>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 &quot;X-&quot;) 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.</p>

<p><b>vCard 2.1</b> is the default vCard version supported in the
PIM API and MUST be supported if&nbsp; the implementation
supports contact lists.&nbsp; UTF-8 MUST be supported on the
platform as a character encoding method for vCard 2.1 entries
(&quot;charset&quot; in vCard 2.1 terminology).&nbsp;
Additionally, the Quoted-Printable and Base64 encodings for
binary content as defined by RFC 1521 must be supported by an
implementation.&nbsp; Implementations MAY also support other
character encoding methods in addition to UTF-8.&nbsp;</p>

<p>Implementations MAY also support other versions of the vCard
specification.&nbsp; 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).&nbsp;&nbsp;</p>

<p><b>vCalendar 1.0</b> is the default vCalendar version
supported in the PIM API and MUST be supported if the
implementation supports event lists or to do lists.&nbsp; UTF-8
MUST be supported on the platform as a character encoding method
for vCalendar 1.0 entries (&quot;charset&quot; in vCalendar 1.0
terminology).&nbsp; Additionally, Quoted-Printable and Base64
encoding for binary content as defined by RFC 1521 must be
supported by an implementation.&nbsp; Implementations MAY also
support other character encoding methods in addition to
UTF-8.&nbsp;&nbsp;</p>

<p>Implementations MAY support other versions of the vCalendar
specification.&nbsp; 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).&nbsp;&nbsp;</p>

<h2>Access Synchronization</h2>

<p>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 <code>Contact.commit()</code>
concurrently on the same contact item, 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. </p>

<p>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.</p>

<p>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 will
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.</p>

<h2>Security</h2>

<p>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:</p>

<ul>
    <li>The security model MUST support access rights for read
        only, write only, and read write. </li>
    <li>The security model MUST be applied in those methods in
        the <code>javax.microedition.pim</code> package that
        throw SecurityExceptions.</li>
</ul>

<p>The implementation of the model is left up to the including
profile or platform. </p>

<h2>Implementation Notes</h2>

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

<ul>
    <li><strong>Extended Field Handling</strong>: Implementations
        are required to generate and interpret valid vCard and
        vCalendar entries in the import and export methods of
        PIMList (i.e. <font face="Times New Roman"><code>PIM.toSerialFormat()</code></font>
        and <font face="Times New Roman"><code>PIM.fromSerialFormat()</code></font>).
        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
        will produce 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 &quot;X-&quot;).</li>
</ul>

<ul>
    <li><strong>Extended Field and Attribute Constant Values</strong>:
        All extended fields or extended attributes provided by an
        implementation MUST have a constant value greater than or
        equal to <code>PIMItem.EXTENDED_FIELD_MIN_VALUE</code>
        and <code>PIMItem.EXTENDED_ATTRIBUTE_MIN_VALUE</code>,
        respectively.</li>
</ul>

<ul>
    <li><strong>Category Names</strong>: The PIM API specifies
        that category names are handled in a case sensitive
        manner. However, this does not require that the
        underlying native PIM database also provide case
        sensitive category names. If the underlying PIM database
        is case insensitive, the implementation may map
        categories names to their case insensitive equivalents on
        persistence of the items. For example, should two items
        be assigned to categories &quot;WORK&quot; and
        &quot;work&quot; respectively and then persisted, both
        may be persisted to the same underlying category of
        &quot;work&quot; in the native database. Subsequent
        retrieval of those items and querying their categories
        would reveal the identical categories of &quot;work&quot;
        and &quot;work&quot; respectively.</li>
</ul>

<ul>
    <li><strong>Field Mappings for Known Serial Formats</strong>:
        The fields contained in the PIM items are mapped to
        corresponding fields in vCard or vCalendar
        specifications. If an implementation supports a
        particular vCard or vCalendar specification and supports
        any of these PIM standard fields in one or more of its
        PIM lists, then the implementation MUST use these
        mappings. The following tables identify those mappings.
        Additionally, categories for all PIM items (i.e.
        Contacts, Events, and ToDos) are mapped to the vCalendar
        and vCard CATEGORIES property name.</li>
</ul>

<blockquote>
    <p><em>Table: Contact Field Mappings</em></p>
</blockquote>

<table border="1" cellpadding="2">
    <tr>
        <th align="left" valign="top">Contact Field and
        Attributes</th>
        <th align="left" valign="top">vCard 2.1 Property
        Name/Property Parameters</th>
        <th align="left" valign="top">vCard 3.0 Type Property
        Name/Property Parameters</th>
    </tr>
    <tr>
        <td>ADDR</td>
        <td>ADR</td>
        <td>ADR</td>
    </tr>
    <tr>
        <td valign="top">ADDR_COUNTRY</td>
        <td>7th address component in the semi-colon separated
        string type value in ADR</td>
        <td>7th address component in the semi-colon separated
        string type value in ADR</td>
    </tr>
    <tr>
        <td valign="top">ADDR_EXTRA</td>
        <td>2nd address component in the semi-colon separated
        string type value in ADR</td>
        <td>2nd address component in the semi-colon separated
        string type value in ADR</td>
    </tr>
    <tr>
        <td valign="top">ADDR_LOCALITY</td>
        <td>4th address component in the semi-colon separated
        string type value in ADR</td>
        <td>4th address component in the semi-colon separated
        string type value in ADR</td>
    </tr>
    <tr>
        <td>ADDR_POBOX</td>
        <td>1st address component in the semi-colon separated
        string type value in ADR</td>
        <td>1st address component in the semi-colon separated
        string type value in ADR</td>
    </tr>
    <tr>
        <td>ADDR_POSTALCODE</td>
        <td>6th address component in the semi-colon separated
        string type value in ADR</td>
        <td>6th address component in the semi-colon separated
        string type value in ADR</td>
    </tr>
    <tr>
        <td>ADDR_REGION</td>
        <td>5th address component in the semi-colon separated
        string type value in ADR</td>
        <td>5th address component in the semi-colon separated
        string type value in ADR</td>
    </tr>
    <tr>
        <td>ADDR_STREET</td>
        <td>3rd address component in the semi-colon separated
        string type value in ADR</td>
        <td>3rd address component in the semi-colon separated
        string type value in ADR</td>
    </tr>
    <tr>
        <td>BIRTHDAY</td>
        <td>BDAY</td>
        <td>BDAY</td>
    </tr>
    <tr>
        <td>CLASS</td>
        <td><em>Implementation specific mapping</em></td>
        <td>CLASS</td>
    </tr>
    <tr>
        <td>EMAIL</td>
        <td>EMAIL/INTERNET</td>
        <td>EMAIL/INTERNET</td>
    </tr>
    <tr>
        <td>FORMATTED_ADDR</td>
        <td>LABEL</td>
        <td>LABEL</td>
    </tr>
    <tr>
        <td>FORMATTED_NAME</td>
        <td>FN</td>
        <td>FN</td>
    </tr>
    <tr>
        <td>NAME</td>
        <td>N</td>
        <td>N</td>
    </tr>
    <tr>
        <td>NAME_FAMILY</td>
        <td>1st name component in the semi-colon separated string
        type value in N</td>
        <td>1st name component in the semi-colon separated string
        type value in N</td>
    </tr>
    <tr>
        <td>NAME_GIVEN</td>
        <td>2nd name component in the semi-colon separated string
        type value in N</td>
        <td>2nd name component in the semi-colon separated string
        type value in N</td>
    </tr>
    <tr>
        <td>NAME_OTHER</td>
        <td>3rd name component in the semi-colon separated string
        type value in N</td>
        <td>3rd name component in the semi-colon separated string
        type value in N</td>
    </tr>
    <tr>
        <td>NAME_PREFIX</td>
        <td>4th name component in the semi-colon separated string