Java 2 Platform, Micro Edition Content Handler API v1.0.1

Java Platform, Micro Edition Content Handler API

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.


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 Basis Profile Xlet can be registered to handle the MIME type image/png. 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 runtime environment.

This optional package is designed to be compatible with J2ME configurations and profiles and requires at least one of:

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. For example, on PBP, 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.

Summary of Requirements

The application management software (AMS) provides for the installation, removal, and execution of applications. The requirements and behavior are summarized here for the convenience of the implementer but is not exhaustive.

Use Cases

Use cases can help illustrate the functions and behavior which are provided by content handlers and are available to an application.

Use Case 1: Distributing new game levels

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.

Use Case 2: Sending coupons to customers

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.

Use Case 3: Receiving a snapshot

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.

Use Case 4: Buying a Music-Clip

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.

Use Case 5: Upgrading software with new features

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.

Use Case 6: Invoking content stored on the device

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.

Use Case 7: Invoking a specific application

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.

Use Case 8: Getting an email address from a local or remote phone book

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.

Reference Architecture

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.

CHAPI Architecture

Figure 1: A Java and Native Runtime Environment Including the Content Handler API

The elements in Figure 1 are described below.

Terminology used in this specification

The Content Handler API uses the following terms:

Digital Rights Management

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.

Application Interactions

The following examples illustrate how the components described in the reference architecture interact while processing selected use cases.

Use Case 3: Receiving a snapshot

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.

Use Case 3: Receiving a snapshot

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 http://host/app.png. 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: Invocation Across Multiple Applications

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.

Use Case 8: Invocation Across Multiple Applications

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.

  1. The email application uses CHAPI to invoke the type text/vcard. The mapping from type to content handler ID is handled by the AMS.
  2. The application must exit to allow the content handler to run if the implementation does not support both applications running at the same time.

  3. The AMS invokes the content handler to start the address book application.

  4. The address book content handler requests the Invocation to determine what it is being asked to do.

  5. 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.

  6. 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 lookup.

  7. The address book application must exit so that the network information application can be launched.

  8. The AMS invokes the network information application.

  9. 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.

  10. The network information application queries the address from the Internet.

  11. The directory of email addresses from the Internet is displayed. The user selects an address to return.

  12. The selected address is set as the return value.

  13. The status of the latest request is set to OK.

  14. The network information application must exit so that the address book can be resumed.

  15. The AMS uses information saved in the request to re-invoke the address book.

  16. The address book retrieves the response to its request for an email address in step 6.

  17. The new address is added to the local address book and the user chooses it to address the current email.

  18. The chosen email address is returned as the result of the previous Invocation saved in step 6.

  19. The status of the previous request is set to OK.

  20. The address book application must exit so that the email client can be restarted.

  21. The invoking application information saved in the invocation is used to restart the email client.

  22. The email client retrieves the email address from the response and inserts it into the message being composed.

Maintenance Release
September 17, 2009

Submit a comment or suggestion on this specification. This specification is protected under the JSPA version 2.6.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright © 2006-2009 Sun Microsystems, Inc. 4150 Network Circle, California, 95054, U.S.A.
All Rights Reserved. Use is subject to license terms.