|Java™ 2 Platform, Micro Edition Content Handler API (Final Release, June 3, 2005)|
|PREV NEXT||FRAMES NO FRAMES|
|Content Handler Interfaces|
|javax.microedition.content||The Content Handler API and execution model allow an application to invoke registered J2ME and non-Java applications by URL, by content type, or by content handler ID.|
The Content Handler API and execution model let an application
invoke registered J2ME and non-Java applications by URL, by content
type, or by content handler ID.
The application can use actions provided by the handler on the
invoked content. For example, the application can use the handler to
get a specific display, or it can use other content handler capabilities
such as open, print, and play.
For example, an application such as a MIDP MIDlet or a Personal
Profile Xlet can
be registered to handle the MIME type
Other applications can then request the handler to display the
image. The handler can provide multiple actions
that control how the content is displayed, modified, or
returned. The execution model
leverages the device's application management software (AMS) to
provide a smooth user experience, to
control the execution of the applications, to conserve resources,
and to enforce the security policy of the device and the Java
This optional package is designed to be compatible with any J2ME profile including the Mobile Information Device Profile Version 2.0, Mobile Information Device Profile Version 1.0, Information Module Profile Version 1.0, the Personal Basis Profile, and other compatible profiles.
The specification includes functions to:
Registration allows a packaged J2ME application, for example an Xlet in a Personal Basis Profile (PBP) application, to be associated with one or more content types and to be invoked from other applications to handle content. Multiple content handlers can be registered for the types, suffixes and actions. An application can use the URL, type, ID, or action to invoke the content handler. The handler to be invoked is selected based on the type, ID, and action requested.
The interactions between the invoking and invoked applications are carefully managed so that applications can be active either in parallel or in sequence, depending on the Java runtime environment. The passing of parameters to the content handler and returning of results to the invoking application are managed when the content handler is finished with each request. If the resources and policy of the device allow concurrent execution, then the invoking and invoked applications may both be active at the same time. In this case, the device will control the sharing of device resources such as keyboard, display, and media functions.
Each application executes in the appropriate runtime. For example, a MIDlet suite will run in a MIDP runtime. Typically, only a single MIDlet can be active at a time. In this case, the MIDlet is instructed to exit so that the content handler can start. When the content handler is finished with a request, if it is a MIDlet, it is instructed to exit so that the invoking application can be restarted to process the status and results. On CDC, a properly packaged Xlet or main program can be used. The invoking and invoked Xlets can be active at the same time as supported by the Java runtime environment.
Non-Java applications may be integrated into the registration and invocation process. The device's browser is one of the most important applications that should be invokable by the content handler mechanism. The browser can use this mechanism to invoke other content handlers. The details of the integration and user interactions are beyond the scope of this specification, since they depend on the device and operating environment.
Use cases can help illustrate the functions and behavior which are provided by content handlers and are available to an application.
New game levels can be distributed as links on a web page or in an email message. When the user invokes the link, the corresponding game application is started and the game level automatically downloaded into the game.
A software company can use Short Messaging Service (SMS) to periodically send discount coupons to its customers. The SMS contains a link to the coupon. When the user invokes the link, the coupon application will show the coupon and display a preview. The link can contain the account information for the store to streamline ordering and payment. When the user chooses to pay for the application, it starts the download and installation process.
The user receives an SMS with a link to a snapshot. When the user invokes the link, the snapshot is displayed by the image viewer.
If the application for the snapshot is not installed, some devices can contact a provisioning server with the type of image and return a link to the application that can display it. Invoking the link will start its installation on the device and then chain to the application to display the snapshot.
A content handler is a credit card handling application. It handles a user's digital credit-card information stored in the device. During a mobile payment scenario, a user checks out music-clips at a music site via the browser and proceeds to check out. The user has previously downloaded a credit card handling J2ME content handler from the wireless operator's site, which is used by the music site. The browser invokes the J2ME credit card handler at the time of payment. After purchase, the link to the content would be invoked to download and install the content.
A game developer wants to keep users up-to-date on new capabilities. The game itself checks with the server to see if there are new features that match the user's experience and profile. A link for a game update is displayed if appropriate. When the user chooses to upgrade, invoking the link installs the new or updated application and restarts the game.
For a device with local content storage, such as audio, mp3, or image files, a content browser could provide the organization of the content. When the user chooses some content, the browser could invoke the appropriate content handler. The browser could provide a choice of the actions for the user such as edit, view, or play the content. Installing new content handlers can automatically add support for new types.
An application may want to provide easy integration with another application in the same suite. The application would invoke the messaging client on the device, which will be well known and can be invoked directly by using its content handler ID. This would be appropriate for common generic applications and also for specific linkages between applications. A typed document or content object does not have to exist to invoke the application.
A user is composing an email and must look up an email address. The email application invokes the address book so the user can choose the address. If the desired address is not present, the user may choose to use another network information application to look it up. Once the address is found, it is returned and added to the local address book. The user selects the address to return to the email client.
The following reference architecture provides a basis for discussing the interfaces and behavior of CHAPI. It is an example only; implementations are free to use other architectures and designs to meet the CHAPI and behavioral requirements. The block diagram below indicates general relationships between the CHAPI package, the native operating system (OS), the Java Runtime environment (Configuration and Profiles), and other optional packages that may be present in an implementation.
Figure 1: A Java and Native Runtime Environment Including the Content Handler API
The elements in Figure 1 are described below.
Native OS: The Native OS is responsible for interactions with the hardware, and for providing abstractions for input/output, file access, networking, etc.
AMS: The Application Management System (AMS) of the device is a generic term used to describe the component(s) responsible for installation, execution, and life-cycle management of applications. The AMS also includes over-the-air provisioning of Java applications. Figure 1 illustrates that in the case of CHAPI, AMS is also responsible for brokering invocations and message passing between Java and native runtime environments. This enables Java applications and content handlers to invoke native content handlers and vice-versa.
Configuration (CLDC/CDC): A J2ME configuration is defined as a set of optimized Java APIs, class libraries, and a virtual machine which targets a family of devices with similar size and capability requirements. CHAPI is compatible with all versions of the Connected Limited Device Configuration (CLDC) and the Connected Device Configuration (CDC).
Profile (MIDP/FP/PBP/IMP): A J2ME Profile targets a specific family of devices and provides APIs which are required in addition to the configuration APIs. CHAPI is compatible with all versions of the Mobile Information Device Profile (MIDP), Foundation Profile (FP), Personal Basis Profile (PBP), Personal Profile (PP), and Information Module Profile (IMP).
Other Optional Packages: Other Optional Packages refers to the various implementations of other Java specifications that may be present in a CHAPI implementation.
Content Handler API (CHAPI): CHAPI exposes the APIs that allow access to content handler instances, content represented by URI schemes or MIME-types. CHAPI also uses some of the AMS functions.
Native (Non-Java) Applications: Non-Java applications in the CHAPI context refer to content handlers. These applications execute in the native runtime or browser environment.
Java Applications: Java applications in the CHAPI context refer to Java content handlers.
CHAPI will work with the DRM implemented on the device and shall not bypass any mechanisms of the device for implementing or enforcing content controls.
The following examples illustrate how the components described in the reference architecture interact while processing selected use cases.
Use Case 3 addresses the need for an application to dispatch a URL to the appropriate content handler, in this case a snapshot. The request is made without the invoking application being aware of the content type, or any need to supply additional arguments. Figure 2 illustrates how an implementation might support the APIs and shows the sequence of interactions between the components and an application and content handler which use the APIs.
Figure 2: Sequence of Interactions between Components in a Simple Invocation
The sequence describes the application invoking the URL, the steps necessary to identify the type of the content (.png), which the content handler is to invoke, the steps the content handler uses, the details of starting the application, and the return of status to the invoking application. The invoking application and the content handler application can be running in parallel.
1a. The application uses CHAPI to invoke the URL
Since only the URL is supplied, the type information must
be determined by accessing the URL.
2a. The CHAPI implementation cooperates with the AMS to retrieve the content from the application server.
2b. The content and type information are returned from the application server and is cached in cooperation with the AMS for use in step 7.
3a. The type information is used to retrieve the content handler from the registry of types and handlers.
3b/1b. The CHAPI method returns to the application, indicating that the invocation is proceeding.
4. The AMS starts the content handler application, if it is not already active.
5a. The content handler calls CHAPI to get the invocation parameters.
5b. An Invocation object is returned that provides access to the URL, type, action, and other arguments.
6a. The content handler uses the invocation object to open the content.
6b. The content saved in step 3 is made available to the application by using a Generic Connection Framework Connection object.
7. The application displays the information and interacts with the user as needed.
8a. When the user has finished with the content, the completion status of the Invocation is set to return status to the invoking application.
8b. The method setting the completion status returns.
9a. The application calls CHAPI to get the invocation response.
9b. The invocation response is returned to the application. The application can now query the completion status.
Use Case 8 describes an email address lookup that involves interactions between two CHAPI-enabled applications, the AMS, and a remote network service. The mail client makes a request for an email address. The local address book must handle that request and make an additional request to the network information application. The following sequence diagram illustrates the interactions.
Figure 3: Sequence of Interactions between Three Applications
Figure 3 contains the steps needed for a MIDP application to invoke the content handler for some web content, such as an image. The invoking application and the two content handler applications are MIDlets that, due to system constraints, cannot execute in parallel. The sequence diagram illustrates how the life cycle is used to start, stop, and restart the application and content handler. Note that if the application and content handler could execute in parallel, then steps 2, 7, 14, and 20 would not be necessary.
The email application uses CHAPI to invoke the type
The mapping from type to content handler ID is handled by the AMS.
The application must exit to allow the content handler to run if the implementation does not support both applications running at the same time.
The AMS invokes the content handler to start the address book application.
The address book content handler requests the Invocation to determine what it is being asked to do.
The URL contains a query for "tom" so the address book displays the matching contents. The user determines that the desired email address is not present and chooses a command to launch the network information application.
The network information application is launched using the type of
network information application,
text/vnd.411. The original
invocation must be saved until it receives a response from the network information
The address book application must exit so that the network information application can be launched.
The AMS invokes the network information application.
The network information application retrieves its parameters, including the query for "tom" and displays the interface to the service which locates email addresses on the Internet.
The network information application queries the address from the Internet.
The directory of email addresses from the Internet is displayed. The user selects an address to return.
The selected address is set as the return value.
The status of the latest request is set to OK.
The network information application must exit so that the address book can be resumed.
The AMS uses information saved in the request to re-invoke the address book.
The address book retrieves the response to its request for an email address in step 6.
The new address is added to the local address book and the user chooses it to address the current email.
The chosen email address is returned as the result of the previous Invocation saved in step 6.
The status of the previous request is set to OK.
The address book application must exit so that the email client can be restarted.
The invoking application information saved in the invocation is used to restart the email client.
The email client retrieves the email address from the response and inserts it into the message being composed.
|Java™ 2 Platform, Micro Edition Content Handler API (Final Release, June 3, 2005)|
|PREV NEXT||FRAMES NO FRAMES|