25 JSR 211: Content Handler API (CHAPI)

25.1 Using Content Handlers

In the 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.

1. In the Projects window, right-click CHAPIDemo and choose Properties from the context menu.

2. In the Category pane, select Application Descriptor, and click the Content Handlers tab.

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

• In the Class field, choose a class name from the dropdown menu.

• ID is an identification string that can be used to 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 on the Actions tab, as shown here.

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 will be 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 allows you to view different types of content from different sources.

1. In the user interface, select File > Open Sample Project > CHAPIDemo.

   In the device selector, right-click on a device, select Run Project OTA, and choose CHAPIDemo.

   • You are asked to enter the password for the keystore. Type: keystorepwd

   • You are asked to enter the password for the "dummyca" key pair alias within the keystore. Type: keypwd

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

   The Text Viewer displays a Media Player URL and links to various media files.

2. Select Duke.png. Use the arrows to highlight the link, then select the file. Using CHAPI, the ImageViewer MIDlet runs and displays the Duke image. Select the Back soft key to return to the Text Viewer.

3. Install the Media Player to view media.

   • Select the URL http:handlers/MediaHandler.jad.

     Select the Menu soft button and select item 1, Go.

   • The application asks, "Are you sure you want to install Media Handler?" Select the Install soft key. For the rest of this demo, click Install if you are asked for confirmation.

     The installation finishes and you return to the Text Viewer.

4. View different media files.

   Select a URL from the list, select the Menu soft button and select item 1, Go.