C H A P T E R 5

Porting CHAPI

This chapter describes how to port the Content Handler API (CHAPI) optional package (JSR 211) for the Java ME platform. The CHAPI optional package permits the enhanced integration of Java ME platform applications into a device's application environment and manages the handling of Uniform Resource Identifiers (URIs) based on a MIMEtype or scheme. The CHAPI optional package provides the capabilities for browsers and native applications as well as Java ME platform applications to invoke other Java ME platform applications that dynamically extend the media types and capabilities supported by the device's application environment. For more information about JSR 211, see http://www.jcp.org/en/jsr/detail?id=211.

CHAPI Code Structure

This document focuses on the porting layer which contains all of the platform dependent functionality. In order to port CHAPI to a new platform, you must implement all the functions in the porting API.

The CHAPI file system is structured as follows.

CHAPI_root/src

  classes

  config       - Configuration files used in the CHAPI build process

  core

    jams

      classes

    nams

      classes

    native     - All the native sources and include files

      platform_a - Porting API implementation for platform "a"

      platform_b - Porting API implementation for platform "b"

      javacall - JavaCall API implementation

      share    - Platform independent sources

        inc    - Include files that define the CHAPI porting API

      stubs    - Stubs for the porting API functions

  i3test

The files listed in TABLE D-1 are particularly important during porting.

TABLE 5-1 Important Files Used in Porting
File	Description
`src/config/` `subsystem.gmk`	Rules and variables used to build the CHAPI subsystem. Change this file only if you add, move, rename, or delete files.
`src/core/native/share/inc/` `jsr211_registry.h`	Header file that contains the CHAPI porting API functions and structures. All functions required for porting are declared in this file.
`src/core/native/stubs/` `jsr211_registry_impl.c`	Stubs for the CHAPI porting API function implementations.
`src/core/native/reference/` `jsr211_registry_impl.c`	Examples of the CHAPI porting API functions.
`src/core/native/share/` `jsr211_nams_installer.c`	Implementation of the following functions: `jsr211_verify_handlers()` `jsr211_store_handlers()` `jsr211_remove_handlers()` These functions are invoked when MIDlet suites are installed or removed from the native AMS runtime.
`src/core/native/share/` `jsr211_deploy.c`	Internal content handler data structures and registration implementations are defined in these files. These structures are defined separately for the native AMS (NAMS) and Java platform AMS runtimes. `jsr211_check_internal_handlers()` is implemented in these files. This function is invoked during CHAPI initialization.

Porting Layer Functionality

Most CHAPI functionality is implemented at the Java platform level and need not be ported. The content handler registry is the only platform-dependent functionality and must be ported. Native support for the content handler functionality is defined in javax.microedition.content.Registry (see the CHAPI specification). The content handler registry is implemented in native code for the following reasons.

To store content handler description more efficiently. The native system is more efficient for storing the complicated content handler description data model.

To enable CHAPI to interact with the native application registry. This interaction enables CHAPI to use platform content handlers to process Java ME application content handling requests.

To enable CHAPI to process the platform's application content handling requests for types supported by the registered content handlers.

To allow the native AMS to register new content handlers during the installation of new MIDlet suites. Conversely, it allows the native AMS to remove the content handlers that belong to a MIDlet suite that is being uninstalled.

A native registry is responsible for the following functionality:

Suite ID

Class name

The following optional attributes can also be provided:

Authenticated authority

MIME types

Suffixes

Actions

Action names for given locales

Access restrictions

The content handler registration method is also provided. The following registration methods are supported:

Static - The content handler is registered during the installation of a new MIDlet suite. Statically registered handlers can only be removed from the registry when their MIDlet suite is removed.

Dynamic - User applications register the content handler by calling the register() method. User applications can remove dynamically registered handlers by calling the unregister() method.

Unregister content handlers based on their IDs.

Search content handlers by the following:

Attribute value

Search condition (see the description of enum values in jsr211_registry.h)

Case sensitivity

List registered content handlers' values for a specified attribute.

Load content handler attribute values for a specified content handler ID.

Porting API Implementation Cases

The features described in the previous section illustrate the need for the close integration of the CHAPI content handler registry and native platform application registry. How the integration is implemented depends on native platform registry features and the API. Some variation can exist in how functionality is distributed between the CHAPI registry and platform registry. Three different implementations are illustrated in the following figure.

FIGURE 5-1 CHAPI Registry Implementation Scenarios

The figure shows two Java platform applications (App1 and Game) and two native applications (App2 and Image Viewer). App1 uses CHAPI to open images in PNG format, whereas Game is registered as a handler for game level files.

App2 uses the platform registry to install the Java platform game level distributed in the game level file. The native image viewer is registered in the platform registry as the content handler for type PNG.

There are three implementations of the Porting/Internal API (PIAPI) depicted in the figure (Impl1, Impl2, and Impl3). Each interacts with the native platform registry differently, as follows:

Impl1 - This implementation represents the scenario in which the target platform does not have an application registry, or its API is not suitable for use with CHAPI. All the data related to registered content handlers descriptions is saved in internal CHAPI storage. This implementation does not allow Java Wireless Client software to use native platform applications because content handlers and native platforms cannot use Java Wireless Client software applications as content handlers. Therefore, in the example in the figure, App1 is unable to open a PNG image using CHAPI and App2 is unable to install the Java platform game level using a game level file.

Impl3 - This implementation represents the scenario in which the target platform has a full-featured application registry that can be used to store all the content handler description information. In this case, the implementation of PIAPI functions consists of calls translated to the native registry API, and there is no need to implement internal CHAPI storage. This implementation uses a fullfeatured platform registry for mapping CHAPI API registry storage requirements. For that reason, this implementation might be the most efficient and provide performance close to a platform-based registry.

Impl2 - This implementation represents the most realistic scenario. In this situation a native platform registry API allows CHAPI to access registered native platform content handlers and to be registered as a content handler for types that are supported by the Java platform handlers. There is no possibility to store additional Java platform content handler description data (such as supported actions, locales, action and map). Therefore, this implementation requires the availability of CHAPI internal storage in which to save additional content handler data. This implementation provides support for a full duplex Java platform mechanism for content handling processing.

The Impl2 and Impl3 implementations allow App1 to use CHAPI to execute the native image viewer to open PNG images. App2 is able to install the Java platform game level using its game level file as the content to be handled.

Porting CHAPI

The following steps provide a high-level overview of the tasks required to port the CHAPI optional package to a new device (referred to here as new-platform).

1. Create the new-platform directory in CHAPI-root/src/core/native.

2. Copy the files in CHAPI-root/src/core/native/stubs to the new-platform directory.

3. Implement the functions in CHAPI-root/src/core/native/new-platform/jsr211_registry_impl.c as appropriate for your platform.

4. Modify the file list or add new source files, if any, to INTERNAL_JSR_211_PLATFORM_FILES property in CHAPI-root/src/config/subsystem.gmk.

5. If an internal content handler is implemented (for example, GraphicalInstaller in the Java platform AMS runtime of MIDP), insert it as a filled internal_content_handler structure into the array internal_handlers in jsr211_deploy.c. This data is used by the method jsr211_check_internal_handlers() during internal handler registration.

6. If the platform has its own content handler application, it can also be registered as internal content handler. Implement the method jsr211_execute_handler() to ensure that the platform handlers are launched properly.

Porting Steps for the JavaCall API

The JavaCall API implementation exists in the CHAPI directory as another platform in src/core/native. The actual platform functionality has moved down to the JavaCall layer and currently appears as files in the top-level javacall directory.

The JavaCall API CHAPI interface is in javacall/interface/jsr211_chapi/javacall_chapi.h.

The only implementation provided is for win32. It is located in javacall/implementation/win32/jsr211_chapi/chapi.c.

To create a JavaCall API implementation for a new platform, implement the functions defined in javacall_chapi.h. Store your implementation in chapi.c in a directory corresponding to your platform.

Consult the JavaCall API documentation for full details on each function.