This document, Personal Digital Assistant Profile (JSR-75) Specification, defines the Personal Digital Assistant Profile (PDAP) for JavaTM 2 Platform, Micro Edition (J2METM). This is the Public Review draft specification of JSR-075. 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.
Your comments on this specification are welcome and appreciated. Please send your comments and feedback to:
You will receive acknowledgement that your comments have been received within a few days. Should you not receive acknowledgement, or have any problems or issues with accessing this specification or providing feedback, please contact the JSR 75 Specification Lead directly (see http://www.jcp.org/jsr/detail/75.asp for details).
| Date | Revision | Description |
| September 25, 2001 | 0.01 | First formal draft based on PDAPEG emails, discussion notes, and written proposals distributed throughout the group for the past year. |
| October 3, 2001 | 0.02 | Weekly update based on teleconference and review changes. |
| October 9, 2001 | 0.03 | Weekly update based on email changes and with additions to security area. |
| October 17, 2001 | 0.04 | Weekly update based on email and 10/10/01 teleconference comments. |
| October 23, 2001 | 0.05 | Weekly update based on emails and addition of missing sections. |
| November 16, 2001 | 0.07 | Latest update based on emails and teleconferences with expert group (skipped version 0.06 to keep in line with JavaDoc API version numbers). |
| November 28, 2001 | 0.08 | Last update based on emails and teleconferences with expert group prior to 12/3/01 community draft face to face review meeting. Integrated this description specification with the JavaDoc API description. |
| December 12, 2001 | 0.09 | Updated spec based on face to face meetings on 12/3/01-12/4/01 and emails as of 12/12/01, in preparation for Community Draft. |
| December 20, 2001 | 0.10 | First proposed Community Draft version. |
| March 4, 2002 | 0.11 | Second proposed Community Draft version, after finalizing API details for the PDAP user interface and the CLDC base. |
| March 5, 2002 | 0.12 | Third proposed Community Draft version and the one submitted for Community Review. Minor editorial changes. |
| April 8, 2002 | 0.13 | Post Community Draft. Updated based on expert group and community review feedback. Released internally to expert group only since not all CR comments have been 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 the one submitted for Public Review. Contains updates based on expert group resolution of open issues. |
The audience for this document is the Java Community Process (JCP) expert group defining this profile, implementers of the PDA Profile (PDAP), and application developers targeting the PDAP.
A J2ME profile defines device-type-specific sets of APIs for a particular vertical market or industry. Profiles are more precisely defined in the related publication, Configurations and Profiles Architecture Specification, Sun Microsystems, Inc.
The specification is presented in HTML and is split into three major specification areas:
This document, produced as a result of Java Specification Request (JSR) 75, defines the Personal Digital Assistant Profile (PDAP) for the Java 2 Platform, Micro Edition (J2METM). The goal of this specification is to define the architecture and the associated APIs required enabling an open, third-party, application development environment for personal digital assistants, or PDAs.
The PDAP is designed to operate on top of the Connected Limited Device Configuration 1.1 (CLDC NG) that is described in Connected, Limited Device Configuration, Next Generation (JSR-139), Sun Microsystems, Inc., and the Mobile Information Device Profile (JSR-37), Sun Microsystems, Inc.
The Personal Digital Assistant Profile Expert Group (PDAPEG) produced this specification. The following companies and individuals, listed in alphabetical order, are members of the PDAPEG:
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 requirements listed in this chapter are additional requirements above those found in both the Connected, Limited Device Configuration, Next Generation 1.1 (JSR-139), Sun Microsystems, Inc., and in the Mobile Information Device Profile 1.0 (JSR-37), Sun Microsystems, Inc., both of which are prerequisites for the PDA profile.
As mentioned before, the main goal of the PDA Profile is to establish an open, third party application development environment for PDAs. To achieve this goal, the PDAPEG defines a PDA to be a device that should have the following minimum characteristics above and beyond those characteristics defined by the CLDC 1.1 and MIDP 1.0:
For devices with the aforementioned hardware characteristics, there is still a broad range of possible system software capabilities. Many devices in the MIDP category also may have the capabilities listed so far, as well as many sub-notebook devices. Also, all PDA devices can be classified as MIDP devices whereas not all MIDP devices can be classified as PDA devices. Because of the subset-superset relationship between MIDP devices and PDA devices, all of the MIDP software requirements apply to PDA devices. However, the additional software requirements that separate PDAs from the rest of small handheld devices are as follows:
The PDA profile is targeted for the class of devices known as Personal Digital Assistants (PDAs). PDAs are generally small, handheld devices whose primary functions to date have been centered on the ability to maintain personal information for a user in a mobile environment. The functionality known as Personal Information Management (PIM) primarily includes address book information, to do lists, and calendar event management. PDAs provide this information in a highly mobile environment due to its small device nature. They also typically have the ability to share the information with desktop PCs or other PDAs through data exchanges.
Bounding this base functionality is the physical characteristics of PDAs. PDAs are first and foremost small mobile devices that a user can easily carry with them every day and have readily within reach. Secondly, they can be very affordable devices for the consumer space or slightly more expensive models with more power for the enterprise markets. These characteristics bound the typical software and hardware capabilities of these devices. Some typical characteristics of PDAs include:
These PDA characteristics distinctly separate them from sub-notebooks, laptop computers, and embedded devices which have much more processing capabilities. Because of these limited characteristics, PDAs find their best fit within the resource-constrained device set defined by the J2ME CLDC.
This chapter describes the architecture of the PDA profile and its relationship to other profiles and configurations in the J2ME space.
The PDA profile resides within the J2ME platform. Within J2ME, two configurations exist that describe the low-level APIs and optimized virtual machines targeted at broad categories of devices. The PDA profile resides on the Connected, Limited Device Configuration (CLDC) that targets small, resource-constrained devices, such as mobile phones, mainstream personal digital assistants, and small retail payment terminals.
On top of configurations reside profiles. Profiles detail the JavaTM technology APIs, built on top of and utilizing the underlying configuration, necessary to provide a complete runtime environment for a specific kind of device. The PDA profile targets handheld personal digital assistants. The PDA profile also includes the Mobile Information Devices Profile (MIDP) in its implementations to re-use many of the APIs already defined in that profile for small, mobile devices. Figure 1 shows the PDA profile and its position in the J2ME space.
Figure 1 J2ME Configurations and Profiles
The PDA Profile specification version 1.0 is based on the MID Profile 1.0 and the CLDC 1.1 specifications. PDAP 1.0 implementations MUST include, as a minimum, compliant implementations of MIDP version 1.0 and CLDC versions 1.1 within a complete PDAP implementation ("compliant" means that the MIDP and CLDC implementations pass the corresponding TCKs for those API sets).
CLDC 1.1 is a required base for the PDAP due to the PDAP inclusion of an AWT subset. The AWT for the PDAP requires a configuration with floating point support. CLDC 1.1 adds floating point support to its base configuration and is therefore the most suitable configuration for the PDAP.
PDAP 1.0 implementations may use future CLDC (or even CDC) versions as its base, as long as those future versions are fully compatible with CLDC 1.1. PDAP 1.0 implementations MUST support the complete set of CLDC 1.1 APIs.
From a programmer's perspective, it is strongly recommended that PDAP applications and suites are coded using only those CLDC and CDC APIs from CLDC 1.1 for maximum platform portability since CLDC 1.1 APIs are the only CLDC APIs that are guaranteed to be available to a PDAP 1.0 application on all PDAP VMs.
The PDA profile is the second profile to be defined for the Connected, Limited Device Configuration of the J2ME. The first profile, the Mobile Information Devices Profile (MIDP), defined a complete set of APIs for small, portable devices that included APIs for application semantics, user interface, persistence storage, and networking. The MIDP targeted small handheld devices with limited resources and occasional data network connectivity, such as cell phones and small PDAs.
MIDP 1.0 is a required based for the PDAP so that the PDAP can access APIs for features common among mobile devices. This provides the PDAP with concrete networking connectivity through HTTP, record management, compatibility with mobile device environments, and optionally an application provisioning model.
The relationship between the PDA profile and the MID profile is defined by the following requirements:
PDA profile implementations MUST include a complete and compliant MID profile implementation as well as implementing all required PDA profile APIs.
PDA profile implementations MUST conform to all requirements for the MID profile as outlined in the MIDP specification as well as all requirements outlined in the PDAP specification.
These statements define a subset-superset relationship between MIDP and PDAP. The reasons for this MIDP-PDAP superset relationship is as follows:
PDAP 1.0 implementations may use future MIDP versions as its base, as long as those future versions are fully compatible with MIDP 1.0. PDAP 1.0 implementations MUST support the complete set of MIDP 1.0 APIs.
From a programmer's perspective, it is strongly recommended that PDAP applications and suites are coded using only those MIDP APIs from MIDP 1.0 for maximum platform portability since MIDP 1.0 APIs are the only MIDP APIs that are guaranteed to be available to a PDAP 1.0 application on all PDAP VMs.
The PDA profile has the following overall footprint estimate for a typical implementation:
| Full CLDC 1.1 and MIDP 1.0 Implementations: | 500 KB |
| PDAP User Interface libraries: | 540 KB |
| PIM APIs: | 20 KB |
| Generic Connection Framework Additions: | 10 KB |
| PDAP Security Model: | 10 KB |
The PDAP defines an application model that is a direct extension of the MIDlet application model from the MIDP. The concepts of MIDlets and MIDlet suites are directly applicable to PDAP applications and its suites. The elements critical to deployment and execution of PDAP applications are:
A PDAP implementation MUST support all of the requirements for application support as outlined by the MIDP specification except otherwise noted in this chapter. A PDAP implementation MUST also support the PDAP specific requirements listed in this chapter.
The PDAP execution environment centers on the PDAlet and a
PDAlet suite. A PDAlet is defined as an application that
utilizes APIs defined in the PDA Profile such that it can only be
executed successfully on a VM that implements the PDAP API set. A
PDAlet is a conceptual entity referring to the capabilties and
requirements of the suite; there is no explicit PDAlet class in a
PDAlet suite. A PDAlet is identified by the use of the PDAlet-<n>
attribute in a PDAlet suite's manifest, as described later in
this chapter.
A PDAlet can be viewed by a programmer as a MIDlet with extended capabilities and restrictions specifically tailored for PDAs. This view aids in the composition of JAD files, manifests, and applications for PDAlets since all of the rules and concepts of MIDlets also apply in the PDAP space, along with additional PDAP specific rules and concepts.
PDAP provides the classes that implement the PDAP APIs. PDAP classes MUST NOT be superceded by any PDAlet suite classes. A PDAP implementation also provides MIDP and CLDC APIs. These APIs also MUST NOT be superceded by any PDAlet suite classes.
As stated in the CLDC specification, the part of a KVM that
controls application execution is referred to as the application
management system, or AMS. The AMS can determine if the
application to be executed is a PDAlet by the manifest attribute
PDAlet-<n>. PDAlets utilize the PDAlet-<n>
attribute while MIDlets utilize the MIDlet-<n>
attribute.
MIDlets are defined in the MIDP specification. The difference between a MIDlet and a PDAlet is that MIDlets use only MIDP APIs and does not use PDAP APIs during their execution life, while PDAlets use PDAP APIs during their execution life. Any MIDlet that uses a PDAP API is no longer classified as a MIDlet and conceptually is classified as a PDAlet. For example, the following code represents a very simple MIDlet:
public class DoNothingApp extends MIDlet {
public void startApp() {
}
public void pauseApp() {
}
public void destroyApp() {
}
}Taking the same code from above and adding a reference to a PDAP defined API then conceptually makes the application a PDAlet since the application now relies on and uses PDAP defined APIs:
public class DoNothingApp extends MIDlet {
public void startApp() {
java.awt.Toolkit tk = java.awt.Toolkit.getDefaultToolkit();
}
public void pauseApp() {
}
public void destroyApp() {
}
}PDAlets use the MIDP application life cycle as defined in the
MIDP specification. As such, all PDAlets MUST provide a class
that extends the javax.microedition.midlet.MIDlet
class. This class is then specified in the PDAlet suite's
manifest with the PDAlet-<n> attribute.
The AMS for a PDAP implementation MUST support situations in which a PDAlet has no active user interface (UI). During the lifecycle of a PDAlet, it is possible that the PDAlet will have no user interface element visible in the display at a given instant. Specifically, there are three scenarios in which a PDAlet may have no active UI:
This state of a PDAlet having no active UI is referred to in this specification as the Active-without-UI state. During these situations in which a PDAlet does not have any active UI, it is left up to the AMS implementation to determine what display, if any, is displayed during the PDAlet's execution.
Note that the state of the PDAlet's user interface does not change the state of the PDAlet. Specifically, the PDAlet remains in the MIDP-defined active state during the time in which the PDAlet does not have any UI, as well as during the time in which the PDAlet does have a UI. The PDAlet remains in the active state so that the PDAlet can maintain control of its resources and continue execution of its code.
To support situations in which a PDAlet requires no active UI, an application should call Display.setCurrent(null) in accordance with the MIDP recommendations for foreground and background applications.
Disposing all Frames does not implicitly destroy a PDAlet; the PDAlet is still in an active state but no longer has any UI. To destroy or close the PDAlet, PDAlets must explicitly use the MIDP-defined method of destroying applications through the use of the notifyDestroyed() and destroyApp() methods.
AMS implementations SHOULD provide a mechanism to terminate PDAlets in the Active-without-UI state. For example, the AMS may display a dialog that an available terminate action over the resulting blank screen.
One or more PDAlets and one manifest are packaged in a single JAR file. This is referred to as a PDAlet Suite. Additionally, zero or more MIDlets may be packaged in a JAR file containing one or more PDAlets. Any PDAlet suite that contains at least one PDAlet is subject to all MIDlet suite packaging rules as well as the additional PDAlet suite packaging rules defined in this specification. The PDAlet suite may also optionally be accompanied by an application descriptor file during deployment.
The PDAP defines additional attributes that are available for inclusion in the manifest and the application descriptor file. The PDA profile specific attributes in the following table MUST be supported by a PDAP implementation.
Table 4 Additional PDAlet Attributes
| Attribute Name | Attribute Description |
PDAlet-<n> |
The name, icon, and class of the nth
PDAlet in the JAR file. These values must be in
that order and separated by a comma. <n> must be a
numeric value assigned according to the rules outlined in
the PDAP specification below.
|
MicroEdition-Profile-Opt |
A space-separated list of non-critical profiles that are supported and desired by this PDAlet suite. These profiles are non-critical to execution in that the suite or part of the suite can execute without these profiles. The suite's installation will not be cancelled if any of these profiles are not present since their inclusion is optional. |
A PDAP implementation MUST support manifests as defined by the MIDP specification with the addition of attributes specific to PDAP applications. This allows a single manifest to be used in a MIDP VM as well as a PDAP VM. For example, a MIDP application management system (AMS) would properly interpret the specific attributes known to MIDP and would treat all other attributes (including the PDAP specific attributes) as application specific data, thus allowing them in the manifest but ignoring their intended PDAP actions. On the other hand, A PDAP AMS would properly interpret both the MIDP attributes and the PDAP attributes and handle them accordingly.
The following attributes MUST be present in every PDAlet manifest:
MIDlet-Name MIDlet-Version MIDlet-Vendor PDAlet-<n> for each PDAlet MIDlet-<n> for each MIDlet MicroEdition-Profile MicroEdition-Configuration The following attributes MUST NOT be present in a PDAlet manifest:
MIDlet-Jar-URLMIDlet-Jar-SizeAll other MIDlet and PDAlet attributes MAY be present in a
PDAlet manifest as defined by the implemented MIDP specification
and this specification. Manifest attributes beginning with MIDlet-
or PDAlet- that are not duplicated in the
application descriptor are accessed in a PDAlet via the getAppProperty()
method. Attributes that begin with PDAlet- are
only available to PDAlets and not to MIDlets.
The MicroEdition-Profile attribute indicates all
of the profiles REQUIRED by the suite in order for the suite to
execute. PDAlets must specify, in a space-separated list,
all profiles that are critical for the suite's execution.
The values in the list may be in any order and the list may
contain spaces. PDAP implementations must verify that the
VM meets all of the listed profile requirements in order to
accept and execute the PDAlet suite. VMs that do not support all
of the profiles listed in the attribute must not installed and
execute the suite.
The MicroEdition-Profile-Opt attribute
complements the MicroEdition-Profile attribute in
that this attribute specifies profiles that are supported and
desired by the suite but are not critical to its execution. In
other words, if the profiles listed in the MicroEdition-Profile-Opt
attribute are not available in the VM, the suite can still
execute on the VM as long as all of the profiles of the MicroEdition-Profile
attribute are supported by the VM. If the profiles listed in the
attribute are available on the VM, then all of the attributes
associated with that profile are enabled within the manifest and
made available for execution.
The value of PDAP-1.0 is used to specify a PDA
profile suite in either the MicroEdition-Profile or
the MicroEdition-Profile-Opt attributes. This value
must be present in either the MicroEdition-Profile
or the MicroEdition-Profile-Opt attribute in the
manifest of a PDAlet suite in order for PDAlets specified by PDAlet-<n>
to execute.
The MicroEdition-Configuration attribute must
have a value of CLDC-1.1 or higher since CLDC 1.1 is
the minimum required configuration for PDAP 1.0.
Each fully qualified class name specified in the PDAlet-<n> and MIDlet-<n>
attributes must be unique among all class names specified or else
the suite will not be loaded. PDAlets SHOULD NOT be associated
with a MIDlet-<n> attribute since the AMS may
make only MIDP APIs available in the application's namespace.
The following rules apply to manifests describing a suite that contains PDAlets and/or MIDlets:
If there is any possibility of a PDAlet suite JAR file being exported from a PDAP implementation, the AMS SHOULD NOT remove obscured MIDlets. This is desirable so that the suite retains its integrity if it is transferred to a MIDP-only implementation.
The following examples describe the rules defined in the previous section.
A manifest containing only PDAlets starts its numbering from the number 1 and continues in successive sequential numbers with no duplication. For example, if there were a hypothetical card game PDAlet suite that contains 3 separate PDAlet applications, the manifest would contain the following:
MIDlet-Name: CardGames
MIDlet-Version: 1.0.0
MIDlet-Vendor: PalmSource, Inc.
MicroEdition-Profile: PDAP-1.0
MicroEdition-Configuration: CLDC-1.1
PDAlet-1: Poker, /poker.png, com.acme.cards.PDAPoker
PDAlet-2: ScoreManager, /manager.png, com.acme.cards.Manager
PDAlet-3: CardPlayers, /players.png, com.acme.cards.PlayersThis manifest specifies that the suite requires the PDAP 1.0 and CLDC 1.1 APIs in order to be installed and executed.
All MIDlets in a PDAlet manifest MUST be numbered sequentially starting with the number 1, as specified in the MIDP specification. All PDAlets in a PDAlet manifest share this same sequential numbering scheme and start their numbering from the last number used by the MIDlets in the PDAlet suite. The resulting combination of n MIDlets and PDAlets must be numbered sequentially from 1 to n with no missing or duplicate number assignments.
For example, if there were a hypothetical card game PDAlet suite that contains 5 separate applications (2 PDAlets - Manager and Players - and 3 MIDlets - Solitaire, Poker, and BlackJack), the manifest would contain the following:
MIDlet-Name: CardGames MIDlet-Version: 1.0.0 MIDlet-Vendor: PalmSource, Inc. MicroEdition-Profile: PDAP-1.0 MicroEdition-Configuration: CLDC-1.1 MIDlet-1: Solitaire, /solitaire.png, com.acme.cards.SolitaireMIDlet-2: Poker, /poker.png, com.acme.cards.PokerMIDlet-3: BlackJack, /bj.png, com.acme.cards.BlackJackPDAlet-4: ScoreManager, /manager.png, com.acme.cards.ManagerPDAlet-5: CardPlayers, /players.png, com.acme.cards.Players
This manifest specifies that the suite requires the PDAP 1.0
and CLDC 1.1 APIs in order to be installed and executed. The PDAP-1.0
value for the MicroEdition-Profile attribute implies
that MIDP 1.0 APIs are also required, by definition of PDAP 1.0,
so the MIDP-1.0 value is not required in the
attribute.
The manifest may also be used to specify that a PDAlet should be used in preference to a MIDlet in the same suite. This is accomplished by assigning the same sequence number to both a MIDlet and a PDAlet in the manifest. In a card game PDAlet example, assume that a PDAlet is added that is a PDAP implementation version of Poker. The following manifest would allow that PDAlet (numbered 2) to be used in preference to the MIDlet version of that application (MIDlet number 2), as shown by the following:
MIDlet-Name: CardGames MIDlet-Version: 1.0.0 MIDlet-Vendor: PalmSource, Inc. MicroEdition-Profile: PDAP-1.0 MicroEdition-Configuration: CLDC-1.1 MIDlet-1: Solitaire, /solitaire.png, com.acme.cards.SolitaireMIDlet-2: Poker, /poker.png, com.acme.cards.PokerMIDlet-3: BlackJack, /bj.png, com.acme.cards.BlackJackPDAlet-2: Poker, /poker.png, com.acme.cards.PDAPokerPDAlet-4: ScoreManager, /manager.png, com.acme.cards.ManagerPDAlet-5: CardPlayers, /players.png, com.acme.cards.Players
Note that the numbering of MIDlets and PDAlets remains sequential without duplication of numbers after resolving obscuring PDAs. In the example above, there will be only one visible application for each number 1 through 5 whether they are MIDlets or PDAlets.
This manifest specifies that the suite requires the PDAP 1.0
and CLDC 1.1 APIs in order to be installed and executed. The MIDP-1.0
value for the MicroEdition-Profile attribute
explicitly states that MIDP 1.0 APIs are also required. However,
this value is not required or needed since the inclusion of the PDAP-1.0
value implicitly requires the MIDP 1.0 APIs by definition.
The following manifest indicates that the PDAP 1.0 APIs are
required in order for this suite to be installed and execute its
critical PDAlets. This is indicated by the MicroEdition-Profile
attribute and its value of PDAP-1.0. This value by
definition also requires the MIDP 1.0 APIs, so all MIDlets in the
suite will also execute successfully. The manifest specifies two
PDAlets (Spreadsheeter and Documenter) and one MIDlet
(Databaser).
MIDlet-Name: MyOfficeTools MIDlet-Version: 1.0.0 MIDlet-Vendor: PalmSource, Inc. MicroEdition-Profile: PDAP-1.0 MicroEdition-Configuration: CLDC-1.1 MIDlet-1: Databaser, /db.png, com.acme.office.DatabaserPDAlet-2: Spreadsheeter, /ss.png, com.acme.office.SpreadsheeterPDAlet-3: Documenter, /doc.png, com.acme.office.Documenter
Note that the following manifest, with the addition of the MIDP-1.0
value in its MicroEdition-Profile attribute, is
functionally identical to the previous manifest because of PDAP
1.0's implicit inclusion of MIDP 1.0. In this case, the MIDP-1.0
value is not needed in the MicroEdition-Profile
attribute.
MIDlet-Name: MyOfficeTools MIDlet-Version: 1.0.0 MIDlet-Vendor: PalmSource, Inc. MicroEdition-Profile: PDAP-1.0 MIDP-1.0 MicroEdition-Configuration: CLDC-1.1 MIDlet-1: Databaser, /db.png, com.acme.office.DatabaserPDAlet-2: Spreadsheeter, /ss.png, com.acme.office.SpreadsheeterPDAlet-3: Documenter, /doc.png, com.acme.office.Documenter
The following manifest indicates that the PDAP 1.0 APIs are
not required in order for this suite to be installed and
executed. In this case, the only required API set is MIDP 1.0
(because of the MicroEdition-Profile attribute value
of MIDP-1.0); the PDAP 1.0 APIs are optional. The
manifest specifies two PDAlets (Spreadsheeter and Documenter) and
one MIDlet (Databaser).
MIDlet-Name: MyOfficeTools MIDlet-Version: 1.0.0 MIDlet-Vendor: PalmSource, Inc. MicroEdition-Profile: MIDP-1.0 MicroEdition-Profile-Opt: PDAP-1.0 MicroEdition-Configuration: CLDC-1.1 MIDlet-1: Databaser, /db.png, com.acme.office.DatabaserPDAlet-2: Spreadsheeter, /ss.png, com.acme.office.SpreadsheeterPDAlet-3: Documenter, /doc.png, com.acme.office.Documenter
This allows the JAR for this manifest to be installed and executed on a MIDP 1.0 only VM. The MIDP 1.0 AMS will identify MIDlet-1, Databaser, as the only MIDlet in the suite available for execution in the MIDP environment. PDAlet-2 and PDAlet-3 attributes are interpreted as application specific attributes and are not made available as PDAlets for execution.
When this same manifest is presented to a PDAP VM, its AMS
will identify that the manifest requires MIDP 1.0 but is
capable of using both MIDP 1.0 and PDAP 1.0, because of the MicroEdition-Profile
and MicroEdition-Profile-Opt attributes that it
recognizes. Therefore, MIDlet-1, PDAlet-2, and PDAlet-3 are all
made available in the PDAlet suite on a PDAP VM.
The application descriptor is used by the application management software to manage the PDAlet and is used by the PDAlet itself for configuration specific attributes. This optional descriptor, known as the JAD file, follows the same rules defined in the MIDP specification. PDAlet specific attributes may be contained in the JAD file and are any attributes that do not begin with “MIDlet-”, “PDAlet-”, or “MicroEdition-”.
The JAD file MAY contain all of the additional PDAP application attributes defined in this specification.
PDAs provide a varying degree of sophistication in the user interfaces that they provide. In general, PDAs provide a rich set of UI elements that are also common in many windowing subsystems, such as frames, menus, scrollbars, and buttons. PDAs also provide great freedom in the use of these widgets in order to create multifaceted user interfaces to support a wide variety of applications. Conversely, the user interface of PDAs are not as rich in content as J2SE devices because of limited screen capabilities, processor speed, and memory space that is common among PDAs.
By subsetting the MID profile, an existing user interface model is present in the PDA profile for programmers to use. However, the LCDUI does not present either the amount of control or the sophisticated set of widgets that PDAs in general offer. This would lead to a noticeable lack of functionality and flexibility in designing UIs for PDAs. Because of this, another UI solution is included in the PDA profile.
The criteria set forth for a suitable user interface for the PDA profile were:
The PDA profile solution for a user interface is the inclusion of the Java Abstract Windowing Toolkit (AWT). The AWT abstracts common UI elements (which also happen to appear natively on many PDAs) and gives the programmer control of UI presentation. Because of these benefits and its ability to match all of the PDAP goals in a UI, the AWT package is a natural fit for programming user interfaces present on PDAs.
Using AWT rather than creating a new UI has many benefits for the PDA Profile including:
All PDAs addressed by the PDA Profile cannot provide the full set of user interface capabilities that are present in the Java™ 2, Standard Edition (J2SE) AWT. This is due primarily to a PDA’s limited display space and memory constraints. The solution adopted by the PDA Profile is to use a proper subset of AWT that provides the most common UI elements and features required for PDA application development.
In the J2ME space, AWT is already used as the user interface APIs for two profiles. Each of the profiles defines a different subset of the J2SE AWT to use based on the needs and requirements of the profile. The profiles that already use an AWT subset include Personal Basis Profile (PBP) and the Personal Profile (PP). Even though the targeted class of devices is different for each profile, a semblance of consistency between the subsets reduces confusion and aid in possible compatibilities.
In an effort to preserve a semblance of consistency between the subsets and the proposed PDAP AWT, the following subset relationship is defined:
PDAP AWT < PP AWT
The PDAP AWT is a subset of the Personal Profile AWT. This relationships aids in potential compatibility between the profiles.
The PDA profile AWT uses a subset of the Personal Profile AWT building block as defined by the Personal Profile as its base. J2ME building blocks, as proposed and governed by JSR 68, allow reuse of APIs among profiles in the J2ME space to reduce API fragmentation and assist in API maintenance. The PDA Profile subsets the Personal Profile AWT by removing support for the following features which are not supported in a CLDC environment upon which the PDAP is based:
The AWT subset adopted by the PDA Profile may have the following characteristics and/or restrictions associated with an implementation due to device constraints.
PDAP implementations MUST support at least two colors, black and white. Implementations MAY support more colors through the RGB constructor for the Color class. Implementations MAY ignore color changes to standard components should the colors not be supported.
An implementation may prohibit setting the cursor in class java.awt.Component. In such a case, attempts to set the cursor will fail silently.
PDAP implementations MUST support Font.PLAIN. Other font support is platform specific and implementations are not required to implement all fonts defined in the API.
The PDA profile does not mandate the AWT to be thread-safe. Therefore application developers should avoid concurrent access to UI objects using different threads, or access to any part of the AWT from other than the event thread.
To avoid thread-safety issues, all modification to AWT components in a multi-threaded application should be done in the system event thread. To do this, the application should use the static invokeLater() and invokeAndWait() methods present in the EventQueue class.
The AWT for a PDAlet behaves very similarly to a J2SE application in terms of window management. In other words, frames, windows, and dialogs can all be instantiated anywhere within the PDAlet and then shown using their appropriate methods. A PDAlet may also have multiple frames, windows, and dialogs defined and instantiated within it.
The following terms (which should be consistent with the terms as used in J2SE AWT descriptions) are used in this section and defined here for clarity:
The window management rules for a PDAP implemenation are as follows:
The rationale for the rules listed above are intended to allow for a wide variety of different window management schemes. In particular, they allow the usual desktop approach of overlapping windows, where the user can move, resize, and activate them at will. The rules also allow other window management approaches that are suitable for devices with small screens. For example, an implementation might choose to make all its top-level windows occupy the full screen and not allow any resizing, providing a "deck of cards" metaphor, where only the topmost window is showing and all others are obscured. In this case, the system might allow the user to activate other windows by representing them on an icon dock or in a menu. Owners of visible modal dialogs may need to be treated specially in this scheme. A visible modal dialog blocks input to its owner window, so it is pointless to allow the user to activate such a window.
The PDA profile presents an AWT subset as its primary user interface, but the MID profile user interface, LCDUI, is also supported due to the inclusion in whole of the MID profile. Because both user interface models are present in the PDA profile, the interaction between AWT and LCDUI must be defined. The interaction will be defined as the following:
A PDAlet will allow operational interaction of the two UI sets but will not allow API interaction, in order to preserve each library’s independence from the other.
The interaction of AWT and LCDUI occurs only at the level of the LCDUI Display object and AWT top-level windows. Within a single PDAlet, the application may show both AWT Frames and LCDUI Displayables.
The MIDP Display is the complete application display context for the PDAlet. The PDAlet is therefore subject to the defined MIDP LCDUI rules in terms of the Display behavior. The following scenarios detail the Display interaction with AWT top-level windows (using the window terminology defined in section 5.3.5):
Display.setCurrent()
is invoked with a null
value, the entire PDAlet (regardless of any existing AWT
windows) may be put into the background. AWT
top-level windows may be closed as part of this action.
This does not automatically release the resources
associated with any existing AWT windows; those should be
explicitly released if desired through the Frame.dispose()
method. Display.setCurrent()
is invoked with a valid Displayable object, that
Displayble becomes active on the Display, hiding or
possibly obscuring the previously active UI entity
whether it is an AWT top-level window or a Displayable
object.Frame.show()
is invoked, that Frame becomes active, hiding (in the
case of only one window displayed at a time) or possibly
obscuring (in the case of multiple windows displayed at a
time) the previosuly active UI entity, whether it is an
AWT top-level window or a Displayable in the PDAlet's
Display. The Displayable object that was the current
Displayable for the PDAlet's Display is no longer the
current Displayable; calls to Display.getCurrent()
will return null.
The Displayable's isShown()
method may return false
since that Displayable is no longer active or shown.Frame.hide()
is invoked, that Frame is no longer visible. The AMS then
may make another AWT top-level window or the Display
containing a Displayable active if that Frame for which
the hide() was invoked was the active top-level window
(which UI entity will become active is implementation
specific).Mixing of UI components from the AWT and LCDUI models is not possible in the same UI container. For instance, it is not possible to put an LCDUI Item into an AWT Container, nor is it possible to put an AWT Component into an LCDUI Form.
All PDA profile implementations MUST include access to a PDA device's native Personal Information Management (PIM) data. This PIM data is central to the functionality that defines the class of devices known as PDAs. PIM functionality in the PDA Profile includes access to a device’s address book, calendar, and to do list.
The goals for the PIM APIs in the PDA Profile 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 PDAP PIM API can be found in the PIM API Specification. All PDAP implementations MUST implement this PIM API.
A standard Java API exists that also can access PIM functionality, and that is JavaPhone™. A subset of the JavaPhone API was considered for use as the PIM API for the PDAP. However, it was determined that JavaPhone does not suit the needs of the PDAP. Some of the major reasons include:
In addition to the requirements outlined in the PIM API Specification, the following conditions MUST be satisifed in a PDAP implementation:
javax.microedition.lcdui.Image.createImage(byte[],
int, int)java.awt.Toolkit.createImage(byte[])java.awt.Toolkit.createImage(byte[], int,
int)If the photo's field data is of type URI, the image can be created on the device using the following method by converting the byte array to a URL:
java.awt.Toolkit.createImage(java.net.URL)The PDA profile mandates complete support for the MID profile, which provides HTTP connections for networking. In addition to HTTP support as mandated by MIDP, a PDAP implementation MAY support the following optional Generic Connection Framework APIs, as dictated by hardware and operating system availability:
The Generic Connection Framework is used to established both
types of connections. The method javax.microedition.io.Connector.open()
is used with each connection's specific unique URI as the
method's input parameter.
If a particular PDAP implementation does not support either or
both of these connection types, a javax.microedition.io.ConnectionNotFoundException
is thrown when attempting to establish the connection using Connector.open() with
the connection’s associated string parameter.
Logical serial port communication through the Generic Connection Framework may be supported by a PDAP implementation if the device has the necessary operating system and hardware support. The established connection exchanges streams of data regardless of the underlying protocols and hardware used. For example, a serial port connection could be established over an IR port on a device if the underlying operating system allows that port to be configured as a logical serial port.
Detailed requirements on the serial port connection API can be found in the CommConnection class in the JavaDoc API Specification.
File system connectivity through the Generic Connection Framework may be supported by a PDAP implementation if the target device has the necessary operating system and hardware support for file systems. Connections to a file system may be opened to file systems located either on memory cards or in a device’s memory, depending on device and operating system limitations. The types of memory cards that contain file systems and could be supported include:
Detailed descriptions on the file system connection API can be found in the JavaDoc API Specification.
PDAP implementations of the file system connnection API MUST observe the following conditions and restrictions above what is described in the API:
Connector.open()
will throw a javax.microedition.io.IOException.
Note that this does not preclude the use of virtual file
systems, in which all files on a mounted system are
accessed transparently as 'local' files through the local
directory structure.The PDA profile contains multiple security features that protect the end user and the device from malicious access and use. First, the PDA profile required conformance to the dependent specifications for the CLDC 1.1 and MIDP 1.0 brings in the security aspects of those API sets (for instance, the CLDC and MIDP defined sandbox security model).
In addition to that, the PDA profile requires that a PDAP implementation MUST provide authorization security for access to privileged functionality. At a minimum, the security provided by an implementation MUST be the Basic Authorization Scheme as detailed in this specification.
This specification does not attempt to define a more sophisticated security model for the PDAP 1.0/MIDP 1.0 combination in the knowledge that the next generation of the MID profile (MIDP 2.0) will provide exactly that. Should a PDAP implementation be implemented on a MIDP 2.0 base, then the MIDP 2.0 security model takes precedence over the PDAP 1.0 security model and all requirements listed in this specification.
The list of PDAP functionality that a PDAlet suite MUST be explicitly granted access to is as follows:
Table 5 Privileged Functionality
| Required Privileged Functionality | Further Details | End User Description |
|---|---|---|
| Reading PIM databases | This includes reading from any PIM database as well as reading a list of available PIM databases. | The application is attempting to read an address book, a calendar, or a to do list on your device. |
| Reading and writing to PIM databases | The includes reading and writing to any PIM database. | The application is attempting to read and write to an address book, a calendar, or a to do list on your device. |
| Reading data with the "file" Connector protocol | This includes reading files and directories as well as reading the roots on a device and/or memory card. | The application is attempting to read files on your device and/or memory cards. |
| Reading and writing data with the "file" Connector protocol | This includes reading and writing to files and directories. It also includes creation of files and directories. | The application is attempting to read and write files on your device and/or memory cards. |
| Reading and writing data with the "comm" Connector protocol | This applies to all attempts to use input and output
streams and to opening the connection using Connector.open(). |
The application is attempting to communicate outside of your device via an infrared port or an external hardware connection. |
| Accessing the AWT System Event Queue | This is applied in java.awt.Toolkit.getSystemEventQueue(). |
The application is attempting to monitor activity for all open Java applications. |
| Listening to all AWT events | This is applied in java.awt.Toolkit.addAWTEventListener(). |
The application is attempting to listen to input from all open Java applications. |
A PDAP implementation MAY have finer grains of security for each privileged functionality listed above. For example, an implementation may provide further granularity for reading PIM databases by having separately grantable access to each type of database (such as Contacts, ToDo, and Events) rather than one access for all PIM databases. Another example is that a PDAP implementation may provide grantable access on a file name basis rather than granting access to all files through one authorization.
The PDA profile requires as a minimum that PDAP implementations provide a Basic Authorization Scheme implementation, in which the end user explicitly authorizes PDAlet suites to access privileged functionality. Authorization is given to PDAlet suites (not individual PDAlets) for privileged PDA profile functionality.
If a PDAlet suite attempts to access methods belonging to the
list of privileged actions, PDAP implementations MUST authorize
access prior to letting the PDAlet continue with the
action. Should the authorization be rejected, a java.lang.SecurityException
is thrown from the method invoked. Authorization may occur
during installation or deployment to the device, at run-time, or
anytime after installation of the PDAlet suite, but MUST occur
prior to execution of the privileged functionality.
In all cases, the notification to the user SHOULD contain an easy to understand description of the privileged functionality the authorization is occurring for. The end user descriptions provided in Table 5 can be used as a model for the descriptive text to display to the end user.
The actual form of authorizing a PDAlet suite with the user is left to the PDAP implementation. For example, one implementation may choose to prompt the user with a dialog on each attempt to access privileged features and require the user to either authorize or reject the attempt. Another example implementation may choose to have a configuration application for the VM that allows the user to authorize some or all PDAlets prior to their execution. Additionally, the PDAP implementation may retain the authorization settings for each PDAlet so that authorization is required only on first invocation and not on every subsequent invocation of the PDAlet.
Implementations MAY provide other security methods IN ADDITION TO the user authorization scheme, such as certificate authentication, signing of JAR files, and domain authorization schemes. These additional security methods MAY take precedent as the security authority over the user authorization scheme in order to deny an authorization attempt without resorting to actual user authorization For example, PDAP implementations may reject attempts to read and write to memory that contains sensitive operating system files without prompting the user about access to these files. The additional security methods MUST NOT use its precedence over user authorization to grant access to privileged functionality without explicitly notifying the user (e.g. the implementation may use a domain based security model to grant access to a particular feature without the user authorizing the access, but the user must still be explicitly notified of the access).
As previously mentioned, this specification does not attempt to define a more sophisticated security model for PDAP 1.0/MIDP 1.0 combination in the knowledge that the next generation of the MID profile (MIDP 2.0) will provide exactly that. Should a PDAP 1.0 implementation be implemented on a MIDP 2.0 base, then the MIDP 2.0 security model may take precedence over the PDAP 1.0 Basic Authorization Scheme.
In this implementation scenario, PDAP 1.0 implementations are also subject to additional restrictions to ensure that privileged functionality is still subject to the security model. To this end, PDAP implementations MUST provide one or more MIDP 2.0 permissions for each of the PDAP privileged functionality listed in section 8.2 to provide security for that functionality.
The AWT API originates from a Personal Profile 1.0 definition,
and ultimately from a J2SE 1.1.8 definition. In these two
environments, a more sophisticated security mechanism is defined
in java.security.
The java.security
package is integrated with and encapsulates the privileged
functionality of the AWT (i.e. accessing the system event queue
and listening to all AWT events). Should a PDAP 1.0
implementation be implemented in a VM along with Personal Profile
1.0 or J2SE, the security policy defined by java.security may take
precedence for the AWT related privileged functionality over the
PDAP security model. For example, should a Personal Profile
implementation already have an external policy set for accessing
the AWT system event queue, that policy may take precedence over
the Basic Authorization Scheme in PDAP.