25 JSR 211: Content Handler API (CHAPI)

JSR 211 defines the Content Handler API (CHAPI). The basic concept is that MIDlets can be launched in response to incoming content (files). Modern mobile phones can receive content using SMS, infrared, Bluetooth, e-mail, and other methods. Most content has an associated content type. CHAPI specifies a system by which MIDlets can be launched in response to specific types of content.

See Section 25.1, "Using Content Handlers" and Section 25.4, "Running the CHAPIDemo Content Browser".

25.1 Using Content Handlers

In the Oracle Java ME SDK Content Handlers are integrated in a project as application descriptors. Content Handlers you define are packaged with the application.

Follow these steps to work with content handlers in the CHAPIDEMO sample application (see Section 25.4, "Running the CHAPIDemo Content Browser").

In the Projects window, right-click CHAPIDemo and choose Properties from the context menu.
In the Category pane, select Application Descriptor, and click the Content Handlers tab.
In the Content Handlers table, each line in the list represents the settings for a content handler.

Description of the illustration content-handler-tab.gif
- To create a new content handler, press Add, or to edit an existing content handler, press Edit. Both actions open the Content Handler Properties window. See Section 25.2, "Defining Content Handler Properties".
- To adjust the order of the content handlers, select one and using the Move Up and Move Down buttons. To remove a content handler from the list, select it and press Remove.
- See Section 25.2, "Defining Content Handler Properties" and Section 25.4, "Running the CHAPIDemo Content Browser"

25.2 Defining Content Handler Properties

In the Projects window, right-click on a project and choose Properties from the context menu. In the Category pane, select Application Descriptor, and click the Content Handler tab. Pressing Add or Edit opens the Content Handler Properties window.

Description of chapi-contenthandler.gif follows

Description of the illustration chapi-contenthandler.gif

In the Class field, choose a class name from the dropdown menu.
ID is a required identification string when you invoke a content handler and control access.
In Content types, list the content types for which this content handler is responsible. Use Add Type and Remove to manage the list.
In Suffixes, provide a list of URL suffixes that act as a substitute for an explicit content type.
In Access allowed to, list IDs for content handlers that are allowed access to this content handler. If the list is empty, access to this content handler is granted to every content handler.

25.3 Defining Content Handler Actions

Content handler actions give invoking applications a choice about how to handle content. An Action is associated with an existing content handler. An image viewer content handler, for example, might include an action for viewing the image at its original size and another action that makes the image fill the available screen space.

In the Projects window, right-click on a project and choose Properties from the context menu. In the Category pane, select Application Descriptor, and click the Content Handler tab. Press Add or Edit to open the Content Handler Properties window and click the Actions tab, as shown here.

Description of chapi-actions.gif follows

Description of the illustration chapi-actions.gif

The Actions list contains the internal names of the actions for this content handler. Locales is a list of all the locales for which human-readable action names are provided. Localized Actions is a grid which contains the human-readable action names for various locales. Each locale is represented by a row, while the actions are listed as columns. You can see all the human-readable action names for a particular locale by reading across a single row.

25.4 Running the CHAPIDemo Content Browser

This demo is a content browser that takes advantage of the content handler registry. It enables you to view different types of content from different sources.

Note:

For the demo to work this project must reside in the Java ME SDK installation's \apps subdirectory. You must create this directory yourself.

Go to File > New Project and in the Categories window select Samples > Java ME SDK 3.2 and single-click CHAPIDemo. Click Next.

Save the sample project in installdir\apps\CHAPIDemo. Click Finish.

Right-click the project and choose Properties. Choose the Running category, and select Execute through OTA and click OK.
Run the project.

You might see security messages as CHAPIDemo registers itself.

You might also see a request for permission to use airtime. To speed up the demo interaction, select "Ask once per application use" and select the Yes soft key (if you do not check this option you can still use the demo but you see the airtime message more frequently).
Launch CHAPIDemo.

On the Favorite Links page, choose CHAPI Demo. Press Select or choose the menu soft button and choose Go.

The Text Viewer displays a Media Player URL and links to various media files.
Install the Media Player to view media.
- Click the URL http:handlers/MediaHandler.jad, or, use arrow keys to highlight the URL and from Menu, select Go.
- The application asks, "Are you sure you want to install Media Handler?" Select Yes.
  
  An authorization Information screen is displayed.
- Select the Install soft key. The installation is confirmed.
  
  The installation finishes and you return to the Text Viewer. The Media Handler shows as a separate application in the AMS.
Select and view the different image, video, audio and text URLs.

Click on a link to open that media in the viewer, or, use arrows to highlight the link, then select Go from the soft menu.

Select the Back soft key to return to the Text Viewer.