Design

This MIDlet suite contains two MIDlets:

Audio Handler
Text Handler (not included in the JAD attributes by default)

Text Handler functions as the main MIDlet, which can either display text content, launch platform Gallery application for viewing pictures, or, when enabled, launch Audio Handler when audio content needs to be invoked.

Usage and architecture

You can use the MIDlets in the following ways:

Handle text content in the same MIDlet: Text Handler MIDlet handles the content type "text/plain". When such a file is requested by the MIDlet, the text is displayed using the TextViewer class in the MIDlet.
Invoke native content handlers: Apart from "text/plain" and "audio/x-wav", the MIDlet suite does not include handlers for any additional content types. So, when an image file is requested in this MIDlet, the MIDlet invokes the native content handler for that content type.
Invoke audio content in another MIDlet, when enabled: Text Handler does not have the ability to handle audio content, but it is set to invoke Audio Handler when "audio/x-wav" content is requested. Audio Handler is then launched and handles the audio content.

Text and image use cases are demonstrated by an example. When Text Handler starts, there is a menu that contains all available choices. You can also add links to the list by selecting the Add command:

Figure: Use case choices

The text is displayed in the same MIDlet, the audio is played in the invoked Audio Handler instance, and the native handler is used for the image file:

Figure: Application registering before displaying content

This content type registration is defined in the JAD file, which is shown below. Note the MicroEdition-Handler parameters, which contain the class name of the MIDlet and the content type that the MIDlet is registered to handle. Another important parameter is Nok-Resource-File-Name, which is a custom JAD attribute defined in the ChoiceList class. This parameter contains a link to a text file, links.txt, which in turn contains the links to the content that are displayed in the main menu. A second MIDlet, Audio Handler, is registered dynamically in the JAD file.

MIDlet-1: Text Handler,/texticon.png,com.nokia.example.contenthandler.texthandler.TextHandler
MIDlet-2: Audio Handler,/audioicon.png,com.nokia.example.contenthandler.audiohandler.AudioHandler
MIDlet-Jar-Size: 104346
MIDlet-Jar-URL: ContentHandler.jar
MIDlet-Name: ContentHandler
MIDlet-Vendor: Nokia
MIDlet-Version: 1.0
MicroEdition-Configuration: CLDC-1.1
MicroEdition-Handler-1: com.nokia.example.contenthandler.texthandler.TextHandler,text/plain, .txt, open, en-US
MicroEdition-Handler-1-Access: com.nokia.example.contenthandler
MicroEdition-Handler-1-ID: com.nokia.example.contenthandler.texthandler
MicroEdition-Handler-1-en-US: Open
MicroEdition-Handler-2: com.nokia.example.contenthandler.audiohandler.AudioHandler, audio/wav, .wav, open, en-US
MicroEdition-Handler-2-ID: com.nokia.example.contenthandler.audiohandler
MicroEdition-Handler-2-en-US: Open
MicroEdition-Profile: MIDP-2.0
Nok-Resource-File-Name: /com/nokia/example/contenthandler/links.txt

Figure: Application registering as a handler of plain text files at startup

The links.txt file contains the following rows (lines marked with two slashes are handled as comments):

Text - txt readme.txt (http)~http://wordpress.org/extend/plugins/about/readme.txt
//Audio - wav life.wav (http)~http://www.wav-sounds.com/funny/life.wav
Image - jpg Moon.jpg (http)~http://upload.wikimedia.org/wikipedia/commons/c/c9/Moon.jpg
Text - txt UseYourOwn.txt (http)~http://localhost/AddYourOwn.txt
//Audio - wav UseYourOwn.wav (http)~http://localhost/AddYourOwn.wav
Image - jpg UseYourOwn.jpg (http)~http://localhost/AddYourOwn.jpg

The text preceding the ~ symbol is shown to the user in the main menu and the URL after the ~ symbol is the link to the actual file. In this example, the files are retrieved from the root of a local web server. The server is configured on the same computer as the emulator that runs this example. If you place the files on an external web server or use your own customized files, you need to edit this file accordingly.

The MIDlet consists of the following classes:

TextHandler—Main MIDlet of the suite. It handles the "text/plain" content type using the TextViewer class.
AudioHandler—Additional component, a second MIDlet, to TextHandler. It plays "audio/x-wav" content from invoked connections. AudioHandler does not invoke content itself; it can only handle incoming requests from the content invoker, which in this example is TextHandler.
TextViewer—Displays the invoked text content in a Form. The class establishes an HTTP connection with the invocation URL to retrieve the content.
ChoiceBean—A simple bean class used for managing the choice list displayed to the user when the MIDlet starts.
ChoiceList—Creates the main menu List, which contains the choices for the user.

Cross-platform compatibility

Invocation of applications is based on standardized JSR-211 Content Handler API, which allows MIDlets to be registered as handlers for specific MIME file types. When the user selects a URL pointing to a file with a MIME type, the platform invokes the correct file handler for that MIME type. However, the exact implementation of this functionality varies between devices.

On Series 40 devices, you can invoke a MIDlet as the file handler for its own links, meaning the files are opened in the MIDet itself (as is done with text files in this example), or you can invoke the device's default file handler from the MIDlet, meaning the files are opened in a separate application (as is done with image files in this example, which open in the native Gallery application). Invoking a custom file handler MIDlet from another MIDlet is only possible on some Series 40 devices.

This example includes the Audio Handler MIDlet, which is designed to handle the opening and playing of WAV files. However, since this functionality is currently not fully supported on Series 40 devices, with the exception of a few devices such as the Nokia 6260 slide, the required JAD attributes are not present in the JAD file included in the MIDlet project package. This means that, if you install the JAD file as it is provided, only the Text Handler MIDlet is installed. If you want to try to install the Audio Handler MIDlet as well, add the attributes listed below to the JAD file.

Note: It has been reported that by adding these attributes to the JAD file, some devices may display a "Conflicting applications" error.

To enable the Audio Handler MIDlet, add the following attributes to the JAD file:

MIDlet-2: Audio Handler,/audioicon.png,com.nokia.example.contenthandler.audiohandler.AudioHandler
MicroEdition-Handler-2: com.nokia.example.contenthandler.audiohandler.AudioHandler, audio/wav, .wav, open, en-US
MicroEdition-Handler-2-ID: com.nokia.example.contenthandler.audiohandler
MicroEdition-Handler-2-en-US: Open

Implementation

For information about implementing the MIDlet, see section Implementation.