The Content Handler API is specified to integrate with the application management framework of either CLDC/MIDP or CDC/PBP. This design is for the integration with CLDC/MIDP in the MIDP stack project. The design will work with either Single or Multiple VM implementations of the VM . Part of the adaptation will be in CHAPI and part in the MIDP stack multi-tasking APIs.

The purpose of the Content Handler API is allow a seamless user experience between applications that are displaying content. For example, a browser may contain a link to an address book entry (VCard) when the user follows the link the browser is terminated and the address book application is started with the URL in the link. The invoking application uses CHAPI to dispatch to the appropriate application and the integration with the AMS provides the mechanism to launch the appropriate content handler. The content handler fetches the content and displays it to the user.

The seamlessness of the content handler is enhanced with the provision to guide the user through the installation of an appropriate content handler, if one is not present on the device. The application discovery application and installation applications are the content handlers for MIDlet suites JAD and JARs.

Table of Contents

• Functionality

• Specification

• Unit Testing

• Examples

• User Experience Requirements

• Design

CHAPI Functionality

CHAPI provides a number of high level functions as a direct result of implementing the specification. The detailed list of functions of the implementation are listed in the {@link com.sun.content.test Introduction to the Unit Tests} that have been developed with the implementation.

• Support for Java invocation of Java content handlers

• Support for native invoking Java content handlers (Not Phase 1)

• Support for Java invoking native content handlers (Not Phase 1)

• Caching of content by invoking Java application, read by Java content handler

Dependencies

• MVM re-architecture

• AMS interfaces for MIDletSuite installation and removal

• Event Interfaces

CHAPI Specification

The specification a separate pdf that defines the formal specification. The overview and package documentation for the package {@link javax.microedition.content} is identical to the official specification.

CHAPI Unit Testing

The CHAPI unit testing is described in the package {@link com.sun.content.test}.

CHAPI Example Applications

The example programs used for demonstrations or for simple code samples are found in the packages {@link example.text} and {@link example.browser}.

User Experience Requirements

CHAPI has a number of new elements that require changes to the User Experience of MIDP stack.

Installation:

• A new permission is added to restrict which MIDlet suites can be installed as ContentHandlers.

  • New permissions require new messages in the ResourceConstants.java and LocalizedStrings.java files.

  • Title: "OK to register application?"

  • Question: "%1 wants to register as a content handler. Is this OK?"

• Content handler specific attributes are added to the application descriptor file and they may be formatted incorrectly resulting in errors that prevent installation. Just as with other application descriptor attribute problems there is not much that can be said in terms the user would understand. The current message is: “"%1 cannot be installed because critical information is not formatted correctly or is invalid. Contact your application provider to correct this situation.” I recommend that the same message be used.

• Content handler applications are registering for content types. It is possible that the requested types, names or suffixes are already registered to another content handler application. It is possible to identify the specific (MIME) types that conflict and the other application that have them reserved. However, the detailed type information is not meaningful to phone users. Probably the most useful message would only identify that the new application requires the same resources as an existing application and that it would need to be removed before the new application can be installed.

Dynamic Content Handler Download

Content handlers can be installed on demand when they are first referenced. The installation process can be transparent to the application but will not be transparent to the user. The bulk of the installation process is identical to that for any MIDlet suite. The steps are outlined below:

1. Prompt the user to say that no content handler in installed for type <x> and asking if one should be located.

2. Query a pre-configured provisioning server with the type of the content handler needed. If the provisioning server returns an error, inform the user and return a failure to the application.

3. Prompt the user to ask if the content handler application should be installed.  This is the same as the current installer question. If the user says NO, then return a failure to the application.

4. Install the application following the current dialogs for size, etc. during installation.

5. Prompt to indicate the installation is done.

6. Return to the normal processing which will invoke the just installed content handler.

Through some kind of policy or user choice I'd like to see the minimum number of prompts to speed the user through the process. I could see two modes:

• Fully automatic: No prompts are given, only the progress of the installation is shown. Failures due to size, etc do interrupt the user experience so the user knows why it failed (but may not be able to do anything).
  The prompts in steps 1, 3, 5 are not performed.

• Confirm: Only Prompt 3 is used to allow the user to confirm installation of the content handler. This the most informative and provides the user the control over the installed applications.
  Prompts 1 and 5 are not used.

Seamless User Interface Transitions

When an application invokes a ContentHandler, the transition of the user interface display from the invoking application to the invoked application must be managed carefully to provide a seamless user experience. The display manager and application manager must be implemented to avoid extra prompts during transitions.

Integration with MIDP stack

This section describes the integration with the MIDP implementation.

There are NO platform dependent components to the implementation.

Parts of the MIDP workspace will need to be modified to support integration of CHAPI.

The modifications will allow the MIDP workspace to built with and without CHAPI.

The CHAPI specification and implementation are maintained in a separate workspace. However, this workspace depends heavily on the MIDP stack workspace.

CHAPI Design

Single vs Multiple VM mode

Single VM mode corresponds to the sequential execution of applications that is necessary when using a KVM VM that can support only a single application at a time. When a new application is invoked the current application must terminate first. The invocation queues will be implemented in native memory instead of files since the native memory will be stable across VM restarts. In the case where there are native APIs to perform invocations the queues will need to be in a stable state when the VM is suspended.

Multiple VM Mode uses the ability of the VM to support multiple applications concurrently. Instead of having to stop and VM and restart it to run the next application, the next application is started without stopping the invoking application. With current use of native applications and a native environment that cannot support both the VM and a native application running concurrently it technique may be necessary to allow the VM to be suspended (no bytecode execution). In the case where there are native APIs to perform invocations the queues will need to be in a stable state when the VM is suspended.

Content Handler Registry

The Content Handler Registry is a persistent store of all of the content handler registration attributes. It is stored in a file using the Storage component. The file is stored in the appdb directory along with the other files. The persistent store is updated atomically with each call to the ContentHandler register or unregister method.

The public {@link javax.microedition.content.ContentHandler} class delegates most functions to the {@link com.sun.midp.content.RegistryImpl} class. The Registry uses a singleton instance as the only access to the registry. A security token with the “MIDP” permission is required to get the Registry.

The details of the Registry functions and design is described in the {@link com.sun.midp.content.RegistryImpl} class.

Application Installation

During installation of a MIDlet suite the {@link com.sun.midp.installer.Installer} checks for the presence of the content handler attributes and invokes the preinstall, install and restore methods of {@link com.sun.midp.content.CHManagerImpl CHManagerImpl} to perform the additional steps. It will parse the attributes and assemble the set of registrations needed for the suite. The {@link com.sun.midp.content.CHManagerImpl#preInstall preInstall} method checks for proper syntax of the attributes and checks for conflicts with other MIDlet suites. In the {@link com.sun.midp.content.CHManagerImpl#install install} method the old registrations for the suite, if any, are removed and the new registrations are made. If the registration fails for some reason after that point the {@link com.sun.midp.content.CHManagerImpl#restore restore} method is used to restore the MIDlet suite's previous registations.

Application Invocation

The queue of pending invocations is maintained for each application. Logically, there is a queue for each target content handler. Each invocation identifies the transaction it is part of, the invoking application and the target of the invocation along with the type and arguments.

Queuing of Invocations

Tbd:

MIDletSuiteStorage

The storage for the Content Handler Registry is provided by the MIDletSuiteStorage class. When a suite is removed all of its registered handlers are removed also.