Package Summary

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 `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 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:

- Invoke a content handler and get a response
- Register a content handler
- Query registrations
- Respond to an invocation

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

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.

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.

## Terminology used in this specification

The Content Handler API uses the following terms:

- Access Restriction: A content handling application can restrict which applications can access its content handlers.
- Action: An invoking application can request that the content handler perform an action on the content.
- Action Name: Locale-appropriate string to present an action to a user.
- ActionNameMap: A mapping between actions and action names for a single locale.
- Application: An application is a program that conforms to the lifecycle of the platform. It has entry points that allow it to be started and stopped. For MIDP, each MIDlet is an application.
- Application Chaining: The ability of an application to invoke another application and that application can invoke another and return results back up the chain.
- Application ID: A unique identifier for an application.
- Application Lifecycle: The sequence of steps defined by the appropriate Java runtime environment for starting, stopping and controlling an application.
- Application Package: A bundle of one or more applications, each application includes classes, resources and meta-data describing the bundle and its requirements to run. Typically, a Java archive (JAR) and an application descriptor. The syntax and format is specific to a Java platform.
- Arguments: A sequence of strings passed from the invoking application to the content handling application which can be modified and returned to invoking application.
- Authentication: The platform capability to verify the origin of applications including content handler applications.
- Authority: A credential used to authenticate an application.
- Background: The state in which an application does not have access to the display and can not interact with the user.
- Content: Any text, image, sound, or other file or files identified by a URL that can be fetched and used by the device.
- ContentHandler: A Java object containing the types, suffixes, actions and action names, etc. supported by a registered content handler.
- Content Handler: An application that registers itself to display or act on content based on content type, suffix, or content handler ID.
- Content Handler ID: A unique identifier for a content handler.
- ContentHandlerListener: An interface to be notified when a new request or response is available.
- ContentHandlerServer: A content handler application uses this interface to process requests.
- Content Type: A string identifying the type of content, such as a MIME-type.
- Dynamic Registration: A content handler registration made using the API.
- Foreground: The state in which an application has access to the display and can interact with the user.
- Invocation: A Java object containing the URL, type, ID, and arguments that are parameters in a Request or Response.
- Invoking Application: The application that invokes a request to a content handler.
- Java runtime environment: The Java runtime environment consists of the Java Virtual machine and libraries provided by the configuration, profiles and optional packages.
- Locale String: A string identifying a language, optional country, and optional variant.
- Registration: The types, suffixes, actions, actions names, and application classname registered for a content handler.
- Registry: A Java object that maintains the set of registered handlers and which is used to make an invocation request and get the response.
- Request: An Invocation object containing the parameters passed to a content handler.
- Response: An Invocation object containing the result returned from a content handler.
- Static Registration: A registration performed during installation.
- Status: The status of an Invocation request or response.
- Suffix: A short string compared with a URL to locate a content handler if specific type information is not available. For example, a file ending such as ".png".

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

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.

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.