Package javax.microedition.content

The Content Handler API and execution model allow an application to invoke registered J2ME and non-Java applications by URL, by content type, or by content handler ID.

See:
          Description

Interface Summary
ContentHandler A ContentHandler provides the details of a content handler registration.
ContentHandlerServer ContentHandlerServer provides methods to get new Invocation requests, to finish the processing of requests and to get the access control information.
RequestListener The listener is notified to indicate that an new Invocation request is available.
ResponseListener A ResponseListener interface to be notified when an Invocation response is available.
 

Class Summary
ActionNameMap An ActionNameMap provides a mapping between actions and corresponding action names.
Invocation An Invocation contains the parameters that are passed from an invoking application to a content handler and the results that are returned to the application.
Registry The Registry provides method to invoke, register, unregister, and query information about content handlers.
 

Exception Summary
ContentHandlerException A ContentHandlerException is thrown to report errors specific to registration and invocation of content handlers.
 

Package javax.microedition.content Description

The Content Handler API and execution model allow an application to invoke registered J2ME and non-Java applications by URL, by content type, or by content handler ID. Content handlers can chain to other content handlers to respond to invocations.

The functions of content handler classes are:

Applications use CHAPI in two ways, as an invoking application or as a content handler application. The invoking application is primarily concerned with the functions of the Registry and Invocation classes. As a client, the application makes requests to display or act on some content. The application makes a request by supplying parameters that identifies the content by URL or the content type, or the ID of the content handler, and possibly an action to perform. If the application needs to know when a request is complete or to get a result it can require a response from the content handler. The application creates an Invocation instance and initializes it with the parameters. The application calls the Registry.invoke method to start the request. Only if the invoking application is expecting a result does it need to retrieve the response using Registry.getResponse. The application can register a listener with Registry.setListener to be notified when the response is available.

A more advanced client application may want to use the detailed information about content handlers stored in ContentHandler objects including the types, suffixes, and actions, or information about the content handler application including its authorization, application name and version, and content handler ID. If the application allows the user to choose the action to be performed, it should use the handler's ActionNameMaps to get locale appropriate action names.

As a server, the content handler application responds to invocation requests from clients. The content handler application uses the methods of ContentHandlerServer and Invocation. New requests are retrieved from the ContentHandlerServer.getRequest method. The content handler can register a listener with ContentHandlerServer.setListener to be notified when new requests are available. The content handler uses the parameters in the Invocation to process the request. If a URL was supplied, the content can be retrieved with the Invocation.open method using the Generic Connection Framework. The content handler uses the URL, type, and action to determine how it should act on the content. When the content handler is done with each request it returns updated parameters and arguments and a status with the ContentHandlerServer.finish method.

A more advanced content handler application can both be a client and a server. Methods on the Registry are used for the advanced functions. New requests can be chained to previous requests with the invoke method. The content handler may restrict access and visibility to itself during registration. An detailed example is provided in Appendix A.

Implementation Requirements

Installing Content Handlers

Content handlers may be installed on the device either before they are needed or when they are needed. The content handler API can be used to trigger the installation process to install the content handlers on the device. For at least one downloadable application packaging type supported by the device, the CHAPI implementation MUST provide and register a content handler to perform the installation. Typically, this includes application/java-archive.

An application can invoke CHAPI with the URL of an application package. The appropriate installation process for the device MUST be used to attempt to install the content handler. The installation MUST include all of the required security and user prompts as specified in the appropriate profile and download specification. If the installation process fails for any reason, including the user's decision to cancel the installation, then the Invocation will fail with the Invocation.CANCELLED status. The status response must be delivered to the invoking application, if required in the request.

Interacting with the Application Life Cycle

Content handlers are applications and are subject to the same security, integrity, installation, upgrade, and other requirements as any other application in the applicable Java runtime environment. Authentication of applications and application classes MUST conform to the requirements of the applicable Java runtime environment.

Each Java runtime environment has its own application packaging and runtime requirements. Each content handler application MUST conform to these requirements. Each Java runtime specifies how applications are uniquely identified, for example, by a classname of the application class. For the MIDP Profile, a content handler MUST be packaged as a MIDlet suite and each content handler MUST implement the MIDlet life cycle. It is NOT necessary for the content handler to be registered as a user visible MIDlet with a MIDlet-<n> attribute. If the content handler MIDlet should be selectable by the user then the MIDlet-<n> attribute must be supplied.

Installation and removal of content handlers utilizes the normal mechanisms of the Java runtime environment. During installation, any content handlers MUST be registered using the attributes defined in the application packaging. Typically, they will be present in an application descriptor or JAR manifest. When a content handler application is removed, all of the static and dynamic registrations of the content handler application MUST be released.

Handling Display Transitions - Foreground and Background

A goal of the Content Handler API is to promote a smooth or seamless user experience between the invoking application and content handler. Typically, if the invoking application has a user interface, one of its screens will be displayed to the user (that is, it will be in the foreground). If a user action causes an Invocation then the next screen the user sees should be the content handler for that invocation. If a foreground content handler finishes with an invocation that requires a response to the calling application that had the foreground immediately before the content handler was invoked, and there are no other requests buffered or being processed from the same calling application, then the foreground is returned to the calling application.

If there is a conflict between foreground transitions and external events or explicit user actions, then the external events or user actions should take precedence.

Static Registration of Content Handlers

Content handler registration can, and generally should, be handled during the installation of the application. The following attributes can be included in the JAR manifest of the application. Each Java runtime environment may define their own application packaging extensions. For MIDP, the attributes can be included in the Java Application Descriptor (JAD). If the attributes are present, they MUST be used by the installation process to register the content handlers. If the application is being upgraded from a previous version then static registrations that are not replaced by new registrations are removed. See the Example of MIDlet Suite Java Application Descriptor section.

Each content handler is uniquely identified by an ID. Content handler and application IDs MUST NOT contain control characters (U+0000 thru U+001F) or spaces (U+00020). The ID for content handlers is supplied in the MicroEdition-Handler-<n>-ID attribute. If an ID is not supplied then a default ID MUST be generated by the implementation. The ID MUST NOT be equal to any other registered handler ID. Every other ID MUST NOT be a prefix of this ID. The ID MUST NOT be a prefix of any other registered ID. If the ID conflicts with another ID the installation MUST fail.

Each static content handler registration contains the following information. Fields are separated using Unicode comma ("," = U+002C). Whitespace is deleted from the beginning and end of each value where whitespace consists of sequences of one or more Unicode horizontal tab (HT = U+0009) or space (" " = U+0020) characters. Each registration consists of information from a MicroEdition-Handler-<n> attribute and optional attributes MicroEdition-Handler-<n>-<locale>, MicroEdition-Handler-<n>-ID: <ID>, and MicroEdition-Handler-<n>-Access. All of the attributes for a registration have the same value of <n>. The numeric value for <n> starts at 1 and MUST use consecutive ordinal numbers for additional entries. The attributes are:

MicroEdition-Handler-<n>: <classname>, <type(s)>, <suffix(es)>, <action(s)>, <locale(s)>
MicroEdition-Handler-<n>-<locale>: <localized action names>
MicroEdition-Handler-<n>-ID: <ID>
MicroEdition-Handler-<n>-Access: <ID(s)>
    
where:

BNF syntax for parsing attribute values

The values of the attributes are parsed according to the BNF below. Whitespace (WSP) may be present around delimiters and is deleted from the beginning and end of each value.

; Syntax of the MicroEdition-Handler-<n> attribute
handler-value = classname ["," types [ "," suffixes ["," actions ["," locales]]]]
 
classname =  value-chars
 
types =  *type / type WSP types
type = value-chars
 
suffixes = *suffix / suffix WSP suffixes
suffix = value-chars
 
actions =  *action / action WSP actions
action = value-chars
 
locales =  *locale / locale WSP locales
locale = value-chars
 
value-chars = 1*(<any Unicode character except CTLs or WSP or COMMA>)
 
; Syntax of the MicroEdition-Handler-<n>-locale attribute
action-names =  action-name / (action-name "," action-names)
action-name = value-chars / (value-chars WSP action-name)
 
; Syntax of the MicroEdition-Handler-<n>-ID attribute
id-value =  1*(value-chars / COMMA)
 
; Syntax of the MicroEdition-Handler-<n>-Access attribute
access-values = id-value / (id-value WSP access-values)
 
; Delimiters
HT = %x09        ; Horizontal tab
SP = %x20        ; Space
COMMA = %x2C     ; Comma
WSP = *(SP / HT) ; Whitespace
CTLs = *(%x00 - %x1F)

Using the parsed values to register

The values parsed from the attributes are used to register the content handler. If there are multiple types, suffixes, actions, or locales, the order is significant; the values must appear in the same order when passed to the Registry.register method. Each locale string and the sequence of actions and action names in each MicroEdition-Handler-<n>-<locale> attribute are used to make a new ActionNameMap. The arrays of types, suffixes, actions, action name maps, ID, and access controls are used to register the classname as a content handler.

Access Restrictions and Application IDs

Content Handlers can control whether they are visible to and can be invoked by other applications and content handlers. The ID of the invoking application is matched against the list of IDs that are allowed access to the handler.

Note that the invoking application or content handler provides its own ID. The veracity of the ID can be cross checked with the authority information that provided for content handlers and invoking applications. If there is no authority information then the ID cannot be trusted.

Each Java runtime environment MUST provide a mechanism to associate an ID with each application. If an ID is not provided, then a default value must be provided. For MIDP, the default value is defined below.

Content Handlers and the Mobile Information Device Profile

For the MIDP Profile, the implementation MUST support download and installation of MIDlet suites that include content handlers. The implementation MUST provide and register content handler(s) to perform the installation for the type text/vnd.sun.j2me.app-descriptor and may support the type application/java-archive for JAR-only installation.

During the installation of a MIDlet suite, each content handler MUST be registered using the attributes defined in the Java Application Descriptor and/or in the Manifest. For untrusted application, attributes in the JAD override corresponding attributes in the Manifest. For trusted applications, according to the MIDP specification, if attributes appear in both the JAD and manifest then the corresponding attribute values MUST be equal.

Content handlers MUST be installable using the MIDP OTA installation mechanism. Any failure related to content handler registration attributes or incorrect or invalid information related to the MIDlet suite must cause the installation to fail. If the MIDlet-Install-Notify attribute defined by MIDP OTA is present, then an installation status report MUST be sent. The installation notifications are:

If the content handler or application ID is not provided by the application then the implementation is required to provide a value. The default ID value is formed as the concatenation of the value of the MIDlet-Vendor attribute followed by a hyphen ("-" = U+002D) and the value of the MIDlet-Name attribute followed by a hyphen ("-" = U+002D) and the classname. All spaces (" " = U+0020) must be translated to underscore ("_" = U+005F).

The MicroEdition-Handler-<n>-ID attribute contains the content handler ID. If the MIDlet suite is trusted, then this attribute and value must be present in both the manifest and application descriptor and the values must be the equal or it must not appear at all. If not present in the application descriptor or manifest, the implementation MUST supply a default ID as defined above using the classname from the MicroEdition-Handler-<n> attribute.

MIDP applications that do not register as content handlers need an application ID to be allowed access to restricted content handlers. The MIDlet-<n>-ID attribute contains the application ID for the MIDlet registered with the MIDlet-<n> attribute. When the application has gained access to the Registry the ID is available using the Registry.getID method. If the MIDlet suite is trusted, then this attribute and value must be present in both the manifest and application descriptor and the values must be the equal or it must not appear at all. If an ID is not provided, the implementation MUST supply a default ID as defined above using the classname in the MIDlet-<n> attribute.

The user friendly application name MUST be provided by ContentHandler.getAppName. If the content handler's classname is also registered as a MIDlet using a MIDlet-<n> attribute then the application name is the name (first) value of the attribute, otherwise, the application name is the value of the MIDlet-Name attribute.

Updates to content handlers are treated the same as updates to any MIDlet suite. The updated content handlers MUST be successfully registered. If there are any dynamic registrations, then they MUST be retained across the upgrade unless superceded by a new static registration for the same classname.

A trusted MIDlet suite MUST request and be granted the javax.microedition.content.ContentHandler permission to perform either static or dynamic registrations consistent with the device's security policy. The Registry.register method MUST throw a java.lang.SecurityException if the permission is not granted.

The permission, javax.microedition.content.ContentHandler, for registering content handlers SHOULD be included in the auto-invocation function group as defined in the MIDP 2.0 Recommended Security Policy. The policy allows an untrusted application to register handlers with a user prompt each time (oneshot). For trusted applications, the user can also choose blanket and session interaction modes.

The MIDP specification defines the concept of a Trusted MIDlet suite in which the AMS is able to authenticate the application. The mechanism defined as "Trusted MIDlet Suites Using X.509 PKI" is one mechanism for authenticating a MIDlet suite. When the AMS can authenticate the MIDlet suite, it MUST be considered authenticated for the purposes of this API. The authority for a signed MIDlet suite is the value of the Subject field of the signing certificate. An application gets the authority using the ContentHandler.getAuthority method. The format of the authority for X.509 certificates is defined by the MIDP 2.0 Printable Representation of X.509 Distinguished Names as defined in class javax.microedition.pki.Certificate.

Example of MIDlet Suite Java Application Descriptor (JAD)

A JAD file is a text file that you can create with any text editor. Its lines have this syntax:

attribute:value

The following is an example of the contents of a MIDlet suite Java application descriptor file. The bold text indicates additions to support content handlers.

MIDlet-1: Image Viewer,, example.imageviewer.ImageViewer
MicroEdition-Handler-1: example.imageviewer.ImageViewer, image/png, .png, open, en-US fr fi-FI
MicroEdition-Handler-1-en-US: Open
MicroEdition-Handler-1-fr: Voir
MicroEdition-Handler-1-fi-FI: Avaa
MicroEdition-Handler-1-ID: com.sun.example.imageviewer
MicroEdition-Handler-1-Access: com.sun.example
MicroEdition-Handler-2: example.Browser, text/html, .html, open, en-US
MicroEdition-Handler-2-en-US: Open
MIDlet-Permissions: javax.microedition.io.Connector.http,javax.microedition.content.ContentHandler
MIDlet-Jar-Size: 2751
MIDlet-Jar-URL: imageviewer.jar
MIDlet-Name: Image Viewer
MIDlet-Vendor: Sun Microsystems, Inc.
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC-1.0
MicroEdition-Profile: MIDP-2.0
     

The JAD file has these attributes:

Since:
CHAPI 1.0






Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.