Professional Documents
Culture Documents
JSR-211 - Devx
JSR-211 - Devx
Although this article focuses on the JSR 211 implementation on the MIDP platform, the API is
designed for use on both MIDP and PBP (Personal Basis Profile) compliant devices. On this
second case, the usage of the API should be possible via an Xlet or any properly packaged
program. Examples on this scenario won’t be covered on this article.
All the ideas behind the JSR 211 are based on the Content Handler concept. According to this
execution model, a given MIDlet can, for instance, register itself into the device’s operational
system to manipulate files belonging to the image/png MIME-type, and determinate that its sole
responsibility is to visualize this kind of file. Once this registration is done, the MIDlet becomes the
registered application which “knows” how to show visualizations of the referred Content Type, and
from this moment onwards, any requests for visualization of a png file would automatically activate
the MIDlet (either requested by Java applications or not). The picture below, borrowed from the
CHAPI specification, shows where the API implementation fits on the J2ME architecture: although
it presents a new set of classes for developers to use on their Java Applications, the major changes
are focused on the virtual machine’s AMS (Application Management System), which is responsible
for the interactions between the MIDlets and the underlying operating system.
The invocation concept of the content handlers is based on URIs, in a way that the MIDlet that
invokes a content handler doesn’t specify which application is being called – it only informs the
content which will be handled (indicated via its URI, in a similar way to the platformRequest
method on the MIDlet class), the operation to be executed (editing, saving, creating, etc), and any
other parameters which might be needed for execution.
In specific cases where more than one Content Handler is registered for a specific file type (for
instance, when there are two MP3 players on the device), the invoking application can indicate
which application to open by specifying its ID. The execution of chained (sequential) content
handlers is also a feature predicted by the API, and would allow more than one application to
process the content in sequence, each one handing the execution to the next.
The specification states two possible execution modes for the content handling process, depending
on the device’s multitasking capabilities. In devices where the parallel execution of applications
(multitasking) is possible, the API dictates that the content handler can be executed in a higher
priority thread, and then send an answer back to the invoker application (which is once again
brought to the foreground) without any need to finalize the invoker before the content is handled.
The usage priority for the display is also affected by this execution model: the API specifies that the
requests for screen drawing (such as callings to paint() method or access to the Display object)
made by the application which is currently in background (e.g. the invoker, at the time the request is
being handled) have lower priority than calls made by the application on foreground.
On devices where only one application can be executed at a time, the invoker must be finished
before the content handler executes, and the content handler has to finish before the invoker can get
a response back.
null, null);
display.setCurrent(alert);
}
} catch (IOException ex) {
Alert alert = new Alert(“”, “Could not go there”, null, null);
display.setCurrent(alert);
}
The invocation of a handler is made via the Registry.invoke() method. This method returns a
boolean value, which indicates if the invoker must be closed before the content handling takes
place.
Our example also includes the handling for an expected response: by calling the
Registry.getResponse() method, it is possible to recover the Invocation object containing the result
of the processing made by the Content Handler. All the Invocation attributes (action, args, url,
status, etc.) can be freely accessed, making the response handling a rather simple procedure as well.
public VCardViewer() {
// Register the listener to be notified of new requests
handler = Registry.forClass(this.getClass().getName());
handler.setListener(this);
}
During the example initialization, the call to the Registry.forClass() method returns an instance of
the ContentHandler object associated with the MIDlet (this instance is associated when the MIDlet
is registered as a Content Handler. We will talk about this procedure later on this article). Using this
instance, we can access the pending requisitions and process them as desired. The MIDlet is
notified about pending requisitions through the invocationNotify() method from the ContentListener
class (following the request-response model commonly adopted on other APIs, such as the Wireless
Messaging API), and can retrieve the invocation data by calling the getRequest() method.
Once the Invocation object is accessible, the content can be retrieved by using the Generic
Connection Framework, and accessed as a streaming of data. The Invocation object also grants
access to all the attributes which were configured during the instantiation of the Invocation: action,
arguments, status, etc.
Among the attributes on this descriptor, only the ones starting by MicroEdition-Handler preffix
really deserve a detailed explanation in our context:
MicroEdition-Handler-<number>: these attributes describe the handlers included in the Midlet
Suite. The arguments are the name of the MIDlet which is responsible to handle the content (in our
case, VcardViewer and VCardEditor), the supported MIME-types, the supported operations (only
open and edit, in our case) and the suffix of the supported files.
MicroEdition-Handler-<number>-<locale>: stores descriptive names of the actions. These names
can be retrieved by applications using the ActionNameMap class, and are usually useful for
exhibition on the user interface. The locale suffix allows them to be internationalized to different
languages (en-US, br-PT, etc)
MicroEdition-Handler-ID: The unique identifier of this content handler package on the device.
This identifier doesn’t need to be supplied, since it can be generated by the underlying
implementation.
Although not as recommended as the static registration, the dynamic registration of MIDlets is also
possible. The sample code below registers a MIDlet as the content handler for image/png files and
defines that the MIDlet will be responsible for handling opening requests
(ContentHandler.ACTION_OPEN) for this kind of file. The registration is made via the
Registry.register() method call. Complementarily, the Registry.unregister() method allows the
unregistration of an application previously defined as a content handler. Content Handlers are also
unregistered automatically when their corresponding MIDlets are removed (uninstalled) from the
device.
try {
// Create a content handler instance for our Generic PNG Handler
String[] chTypes = { “image/png” };
String[] chSuffixes = { “.png” };
String[] chActions = { ContentHandler.ACTION_OPEN };
String chClassname = “example.content.PNGHandler”;
ContentHandler handler =
Registry.register(chClassname, chTypes, chSuffixes, chActions);
} catch (ContentHandlerException ex) {
// Handle exception
}
Conclusions
The CHAPI is an optional package, and the final specification will be available on August. Due to
it’s extreme usefulness and the new level of interaction it brings to the J2ME world, it is possible
that many manufactures decide to implement this JSR on their MIDP 2.0 compliant devices in a
short period of time. We really hope so!
Links
JSR 211 – Content Handler API - http://www.jcp.org/en/jsr/detail?id=211
Official JSR page, where the public specification and latest Javadoc can be found.
Herval Freire (herval@sollipsis.com) is a Sun Certified Java Programmer (SCJP), Web Components
Developer (SCWCD) and Micro Application Developer (SCMAD), and works as a senior consultant on
wireless and mobility projects.