|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|
|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.|
|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.|
|ContentHandlerException||A ContentHandlerException is thrown to report errors specific to registration and invocation of content handlers.|
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:
Registry- invokes, registers, unregisters and queries content handlers
ContentHandler- provides the details of a registration and to handle requests to an application
Invocation- contains the parameters passed to and returned from a content handler and used to select a content handler to invoke
ContentHandlerServer- processes requests to handle content
RequestListener- notifies the content handler of pending requests
ResponseListener- notifies the application of pending responses
ActionNameMap- maps actions to action names
ContentHandlerException- reports content handler errors
ContentHandlerPermission- Content Handler Permission
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
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
instance and initializes it with the parameters. The application calls
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
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
Invocation. New requests are retrieved from
ContentHandlerServer.getRequest method. The content
handler can register a listener with
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
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
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.
microedition.chapi.versioncan be used to determine whether CHAPI is implemented, and if it is, the version number. If this specification is implemented in a CLDC Java runtime environment, the property
microedition.chapi.versionMUST have the value "1.0" or "1.0.1" as returned from the
java.lang.System.getPropertymethod. For all other Java runtimes, the property value returned must be "1.0.1".
javax.microedition.io.HttpConnectioninterface and corresponding protocol.
httpsis supported by the Generic Connection Framework.
fileis supported by the Generic Connection Framework.
Invocationclass and invocation mechanism MUST support passing and returning the values in an Invocation including the URL, Type, Action, ID, Args, Data, and InvokingAppName, InvokingAuthority, and InvokingID, etc. as data totaling at least 16384 bytes. Each character of a String is counted as two bytes. It must be able to pass and return at least 10 arguments in the arguments array.
Connector.openwere used to access the content.
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 package type
supported by the device, the CHAPI implementation MUST provide and
register a content handler to perform the installation. Typically, this
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.
Preregistered content handlers for installing Java applications, such as MIDlet Suites,
MUST be registered with actions
and may have additional actions. This means that it
MUST be possible to invoke the installer with any of the actions above
null (without any action).
The behavior of the actions
null are the same as if the user
had initiated the installation and provides the same user experience via interactive
feedback, prompting, and other conveniences provided to the user such as launching the
"install_only" SHOULD limit interactions with the user to those that are
necessary and essential to the installation of the application. The installation process
should be streamlined and must omit all unnecessary prompts and convenience functions.
Ideally, there would be no interaction required by the user. The essential functions include
the user's ability to monitor progress of the installation and to cancel the installation.
The application MUST be installed and made available but MUST NOT be launched as a result
of the installation. Any static registrations like Push Registry or Content Handler
registrations are however handled as in the normal installation process.
The installation MUST
include all of the required security and user prompts as specified in
the appropriate profile and download specification.
If a response has been requested by the calling application by calling setResponseRequired(true), the caller MUST be notified of success or failure of the installation using OK, ERROR or CANCELLED responses after the installation attempt has finished. Regardless of any prompts or other actions by the installer or other applications the invoking application MUST be able to get the response and process it though there may be a delay due to limitations on available resources. The status of the invocation has the following meanings:
OK: Application has been installed successfully; including the case where the same version requested was previously successfully installed.
ERROR: Application was not successfully installed. The Invocation.getArgs() method MUST return a single String containing the description of the error. For MIDP, it MUST be the installation status report error number and description (as defined in MIDP Provisioning).
CANCELLED: The request was cancelled by the user.
If an application wishes to do a self update, it could invoke an install
on the URL of the updated application using action
Invocation.setResponseRequired(true) and then it should exit.
Since the application to be installed is the invoking application
itself and response required has been set, the updated application
will be launched and it will receive a notification after the
installation regardless of whether the update succeeded or failed, but
as the invoking application not as the installed application.
During an update, if the application does not exit voluntarily and the
installation cannot proceed while the application is running,
the AMS SHOULD force it to exit before continuing with the installation.
After installation, the response, if any, MUST be delivered to the
(version of the) application present after the installation.
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.
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 below when they appear 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.
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 MUST be 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.
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. 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.
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
attribute. If a content handler ID or application 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.
If a content handler ID is longer than the implementation supports
then the installation must fail.
For MIDP, the failure mode is documented in the
"Content Handlers and the Mobile Information Device Profile" section with
a "939 Content handler install failed".
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
attribute and optional attributes
MicroEdition-Handler-<n>-ID: <ID>, and
All of the attributes for a registration have the same value of
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:
MicroEdition-Handler-<n> - Attribute for
registrations. Multiple registrations can be provided in an
application package. The numeric value for
<n> starts at 1
and MUST use consecutive ordinal numbers for additional entries. The
first missing entry terminates the list. Any additional entries are
Attribute to define the action names appropriate for the actions of the
nth content handler for the indicated locale. The locale
string should be properly formatted as defined in class
If the corresponding
attribute references this locale attribute then there MUST be an action
name for each action in the corresponding
attribute. If the number of action names does not match the number of
actions, then the installation MUST fail. If there are multiple action
names, separate them with a comma ("," = U+002C). Action names MUST allow
embedded whitespace. Leading and trailing whitespace is deleted
from each action name. If a locale attribute is present but is not
referenced by a
then it is not used for the registration.
MicroEdition-Handler-<n>-ID - Attribute to
declare the unique ID for this content handler. The content handler ID
is set during installation and returned from the method
If not provided, a unique value MUST be provided by the implementation.
MicroEdition-Handler-<n>-Access - Attribute
to control the access and visibility of the content handler. It
contains a list of the IDs of content handlers or applications that are
allowed access and visibility to the content handler. If omitted, all
applications will be allowed access and visibility to the content
handler. If there are multiple IDs, separate them with a space (" " =
U+0020). IDs MUST NOT contain whitespace. Leading and trailing
whitespace is deleted from each ID.
classname - Application that is responsible for
handling the content. Leading and trailing whitespace is deleted.
type(s) - Content type(s). If there are multiple
types, separate them with a space (" " = U+0020). Types MUST NOT
contain a space. Leading and trailing whitespace is deleted from each
suffix(es) - Zero or more suffix strings. If
there are multiple suffixes, separate them with space (" " = U+0020).
Suffixes MUST NOT contain a space. Leading and trailing whitespace is
deleted from each suffix.
action(s) - Zero or more actions. If there are
multiple actions, separate them with a space (" " = U+0020). Actions
MUST NOT contain a space. Leading and trailing whitespace is deleted
from each action.
locale(s) - Zero or more locales. If there are
multiple locales, separate them with a space (" " = U+0020). Locales
MUST NOT contain a space. Leading and trailing whitespace is deleted
from each locale string. Each locale string is used to identify the
attribute that contains the action names.
ID - Content handler or application ID. Leading
and trailing whitespace is deleted.
; 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)
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
attribute are used to make a new
ActionNameMap. The arrays of
types, suffixes, actions, action name maps, ID, and access controls are
the classname as a content handler.
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 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
and the type
Preregistered content handlers for installing Java applications,
MUST be registered to handle file suffixes ".jad" and ".jar".
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
If the content handler MIDlet should be selectable by the user then the
MIDlet-<n> attribute must be supplied.
Note: the MIDP specification requires that there be at least the
MIDlet-<1> attribute regardless of the number
of content handlers.
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. See the Example of MIDlet Suite Java Application Descriptor section. For untrusted applications, 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
attribute defined by MIDP OTA is present, then an installation status
report MUST be sent. The installation notifications are:
938 Content handler conflicts with other handlers
939 Content handler install failed
910 Application authorization failure
javax.microedition.content.ContentHandleris not requested or not granted.
905 Attribute Mismatch
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
attribute followed by a hyphen ("-" = U+002D) and the value of the
attribute followed by a hyphen ("-" = U+002D) and the
All spaces (" " = U+0020) must be translated to underscore ("_" =
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 either the application descriptor or
manifest, the implementation MUST supply a default ID as defined above
using the classname from the
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
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
classname in the
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
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 further upgrades unless superseded by a new static registration for the same classname. Retained dynamic registrations are considered to be defined in the updated application.
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
method MUST throw a
java.lang.SecurityException if the
permission is not granted.
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
A JAD file is a text file that you can create with any text editor. Its lines have this syntax:
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:
|PREV PACKAGE NEXT PACKAGE||FRAMES NO FRAMES|
Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.