24 JSR 211: Content Handler API (CHAPI)

24.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 "Running the CHAPIDemo Content Browser").

1. In the Projects window, right-click CHAPIDemo and select 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.

   Figure 24-1 The Content Handlers Tab

   
   Description of "Figure 24-1 The Content Handlers Tab"
   
   

   • 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 "Defining Content Handler Properties."

   • To adjust the order of the content handlers, select one and click Move Up and Move Down. To remove a content handler from the list, select it and press Remove.

   • See Defining Content Handler Properties and "Running the CHAPIDemo Content Browser."

24.2 Defining Content Handler Properties

In the Projects window, right-click a project and select 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.

Figure 24-2 The Content Handlers Properties Window

Description of "Figure 24-2 The Content Handlers Properties Window"

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

24.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 a project and select 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.

Figure 24-3 The Content Handlers Properties Window

Description of "Figure 24-3 The Content Handlers Properties Window"

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.

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

1. Click the File menu and select New Project.

2. In the Categories window select Samples > Java ME SDK 3.3 and single-click CHAPIDemo. Click Next.

   Save the CHAPIDemo sample project in installdir\apps directory; for example, C:\Java_ME_platform_SDK_3.3\apps\CHAPIDemo. Click Finish.

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

   Not all features of the demo are available if you choose the Run command. Additionally, to see certain features of the demo, an HTTP server is required. The server is located in the installdir\apps directory. Also the audio and video files are located in the content directory, which must be located in the CHAPIDemo. directory (installdir\apps\CHAPIDemo\content).

   You might see security messages as CHAPIDemo registers itself.

4. Launch CHAPIDemo.

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

   You might 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).

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

5. Install the Media Player to view media.

   • Click the URL http:handlers/dist/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?" Click the Install soft key.

     An authorization Information screen is displayed.

   • Click the Install soft key.

     The installation is confirmed and you are returned to the Text Viewer. The Media Handler shows as a separate application in the AMS.

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