ONJava.com    
 Published on ONJava.com (http://www.onjava.com/)
 See this if you're having trouble printing code examples


O'Reilly Book Excerpts: J2ME in a Nutshell

The Mobile Information Device Profile and MIDlets, Part 2

Related Reading

J2ME in a Nutshell
By Kim Topley

by Kim Topley

This is the second of a five part book excerpt series based on O'Reilly's J2ME in a Nutshell by Kim Topley. Part 2 focuses on MIDlets and their suites.


MIDlets and MIDlet Suites

Java applications that run on MIDP devices are known as MIDlets. A MIDlet consists of at least one Java class that must be derived from the MIDP-defined abstract class javax.microedition.midlet.MIDlet. MIDlets run in an execution environment within the Java VM that provides a well-defined lifecycle controlled via methods of the MIDlet class that each MIDlet must implement. A MIDlet can also use methods in the MIDlet class to obtain services from its environment, and it must use only the APIs defined in the MIDP specification if it is to be device-portable.

A group of related MIDlets may be collected into a MIDlet suite. All of the MIDlets in a suite are packaged and installed onto a device as a single entity, and they can be uninstalled and removed only as a group. The MIDlets in a suite share both static and runtime resources of their host environment, as follows:

As an example of the sharing of classes and data between MIDlets, suppose a MIDlet suite contains a class called Counter, intended to keep count of the number of instances of MIDlets from that suite are running at any given time.

public class Counter {
    private static int instances;
 
    public static synchronized void increment(  ) {
        instances++;
    }
 
    public static synchronized void decrement(  ) {
        instances--;
    }
 
    public static int getInstances(  ) {
        return instances;
    }
}

Only a single instance of this class will be loaded in the Java VM, no matter how many MIDlets from the suite that supplies it are running in that VM. This means that the same static variable instances is used by all of these MIDlets, and, therefore the increment and decrement methods all affect the same counter. The fact that these methods are synchronized protects the instances variable from concurrent access by any threads in all of the MIDlets.

MIDlet Security

For the developer, dealing with MIDlet security is a very simple issue, because there isn't any! The Java security model used in J2SE is both powerful and flexible, but it is expensive in terms of memory resources, and it requires a certain amount of administration that may be beyond the knowledge expected of a mobile device user. Therefore, neither CLDC nor MIDP includes any of the security checking of API calls that is available in J2SE, with the exception of the Runtime and System exit( ) methods, which can never be used by a MIDlet.

For the mobile device owner, this means that a MIDlet appears to be more of a potential threat than an applet would to a browser user, because the MIDlet is not constrained by the Java applet "sandbox" that the browser imposes via a SecurityManager. A mobile device owner needs to be careful when installing MIDlets and, preferably, he should accept software only from trusted sources. Unfortunately, at the time of writing, there is no way for the user to be completely sure who is actually providing a MIDlet or that the MIDlet code has not been interfered with en route to the device; the authentication mechanisms that provide this for the J2SE platform (i.e., public key cryptography and certificates) are not a standard part of the MIDP specification. The secure version of the HTTP protocol (HTTPS), which will help to alleviate this problem, is under consideration for inclusion in a future version of MIDP. In the meantime, there is limited security against malicious MIDlets. There are no MIDlet APIs that allow access to information already on the device, such as address and telephone number lists or calendars, and it is not possible for a MIDlet to directly control the device. As you'll see in Chapter 6, a MIDlet can store information on a device, but that storage is private to that MIDlet and its suite, so the MIDlet can harm only its own data.

MIDlet Packaging

MIDlets need to be properly packaged before they can be delivered to a device for installation. The MIDlet subclass that acts as the main entry point for the MIDlet, together with any other classes that it requires (apart from those provided by MIDP itself) and any images or other files to which it needs access at runtime, must be built into a single JAR file. Packaging information that tells the device what is in the JAR must be supplied in the JAR's manifest file. Similar packaging information is also provided in another file called the Java application descriptor (or JAD file for short), which is held separately from the JAR. A JAR may contain more than one MIDlet, in which case all the MIDlets are deemed to be in the same MIDlet suite. To put the same thing another way, all MIDlets that are in the same MIDlet suite must be packaged in the same JAR.

Both the manifest file and the JAD file are simple text files in which each line has the form:

attribute-name: attribute-value

The name and value are separated by a colon and optional whitespace. All the attributes that are of relevance to the installation of MIDlets have names with the prefix "MIDlet-". A complete list of these attributes, together with a short description of their associated values, can be found in Table 3-2. The values in the JAR and JAD columns indicate whether the attribute is mandatory (M), optional (O) or ignored (I) in the file corresponding to that column.

Table 3-2: MIDlet Packaging Attributes

Attribute Name

JAR

JAD

Value and Meaning

MIDlet-Name

M

M

The name of the MIDlet suite packaged in the JAR file. This name may be displayed to the user.

MIDlet-Version

M

M

The version number of the MIDlet suite packaged in the JAR file. Version numbers take the form a.b.c (for example 1.2.3), where larger values in each field indicate a newer version, with the leftmost field taking precedence. For example, version 1.2.5 is taken to be more recent than version 1.2.3, and, similarly, version 2.1.5 is newer than 1.3.7.

MIDlet-Vendor

M

M

The name of the MIDlet suite provider. This is free-form text that is intended for display to the user.

MIDlet-n

M

I

Attributes that describe the MIDlet in the MIDlet suite. The value n is replaced by a numeric value starting from 1 to identify individual MIDlets. The format of the value associated with this attribute is described in the text.

MicroEdition-Profile

M

I

The version or versions of the MIDP specification that the MIDlets in this suite can work with. Where more than one version appears, they must be separated by spaces. The versions specified are compared to those listed in the microedition.profiles property of the target device to determine whether the MIDlets are compatible with them. MIDP-1.0 is a typical value for this attribute.

MicroEdition-Configuration

M

I

The J2ME configuration required by the MIDlets in this suite. This value is compared to the target device's microedition.configuration property to determine compatibility.

MIDlet-Description

O

O

A description of the MIDlet suite intended to be displayed to the user.

MIDlet-Icon

O

O

An icon that may be used to represent the MIDlet suite during or following installation. The icon must be a Portable Network Graphics (PNG) file.

MIDlet-Info-URL

O

O

The URL of a file that contains further information describing the MIDlet suite. The content of this file may be displayed to the user to allow the user to decide whether to install the MIDlet suite.

MIDlet-Data-Size

O

O

The minimum amount of persistent storage that this MIDlet suite requires. This refers to space used for the long-term storage of data used by the MIDlet suite, not the space required to install and manage the MIDlet suite itself. It is specified in bytes. If this attribute is not supplied, it is assumed that the MIDlet suite does not require persistent storage. Whether or not MIDlets can use more persistent storage space than they initially request is device-dependent.

MIDlet-Jar-URL

I

M

The URL of the JAR file that contains the MIDlet or MIDlet suite described by these attributes. This attribute is used only in the application descriptor.

MIDlet-Jar-Size

I

M

The size of the MIDlet JAR file in bytes. This attribute is used only in the application descriptor.

MIDlet-Install-Notify

I

O

A URL used to report the success or failure of MIDlet installation performed from a remote server. This attribute is not included in the current MIDP specification, but it is supported by the Wireless Toolkit. See the later section "Delivery and Installation of MIDlets" for further details.

MIDlet-Delete-Confirm

I

O

A message to be displayed to the user before the MIDlets are deleted from the device on which they are installed. Like MIDlet-Install-Notify, this attribute is not currently included in the formal specification.

MIDlet-specific attributes

O

O

MIDlet developers can provide limited configurability for MIDlets by including attributes that can be retrieved at runtime.

As you can see, many of the attributes must be supplied in both the manifest file, which resides in the JAR, and in the JAD file, which does not. To see why, it is necessary to understand why two files are used.

The job of the manifest file is to indicate to the device the name and version of the MIDlet suite in the JAR and to specify which of the class files it contains correspond to the individual MIDlets. In order to make use of this information, however, the device must download the JAR and extract the manifest. Having done this, it can then display the values associated with the MIDlet-Name, MIDlet-Version, and MIDlet-Vendor attributes and the optional MIDlet-Description and MIDlet-Icon attributes. These attributes allow the user to decide whether the MIDlets should be installed. However, the JAR for a MIDlet suite might be quite large and may take some time to retrieve over the relatively slow networks to which mobile devices typically have access. If the only useful description of its content were in the JAR itself, a lot of time might be wasted transferring large files that are immediately rejected as uninteresting.

To solve this problem, some of the attributes from the manifest file, together with extra information, is duplicated in the JAD file. Instead of downloading the whole JAR, a MIDP device first fetches its JAD file, which is much smaller than the JAR and can be transferred quickly. The device then displays the JAD file's contents to the user so that she can decide whether to fetch the JAR file. The JAD contains some attributes that come from the manifest file and others that do not appear in the manifest. The common attributes are as follows:

These attributes (with the possible exception of the last one) can all be presented to the user as an aid to deciding whether the content of the corresponding JAR file is interesting enough to download. The first three of these attributes are mandatory in both JAR and JAD files, and the MIDP specification requires that their values be identical. The remaining attributes are all optional. If they appear in both the manifest and the JAD file, the value in the JAD file takes precedence over that in the manifest (and at this stage, the device can see only the value in the JAD file).

The JAD file also contains two other attributes that are not present in the manifest file:

The MIDlet-Jar-Size attribute can be displayed to the user to help determine how long it will take to fetch the JAR; it also enables the user to guess whether the device has enough free space to install the JAR. Assuming the user decides to install the MIDlet suite, the next step is to fetch the JAR itself, which can be found by using the value of the MIDlet-Jar-URL attribute.

Suppose a company called "Wireless Java Inc." creates a suite of MIDlets called WirelessTrader that allow a user to do online stock trading from a MIDP device. The suite contains two MIDlets, one for trading, the other for simply browsing through stock prices. The main classes for these two MIDlets are called com.wireless.TradeMIDlet and com.wireless.BrowseMIDlet, and they make use of common code in the com.wireless.Utils class. The manifest for this suite would look something like this:

MIDlet-Name: WirelessTrader
MIDlet-Vendor: Wireless Java Inc.
MIDlet-Version: 1.0.1
MIDlet-Description: A set of MIDlets for online trading.
MIDlet-Icon: /com/wireless/icons/wireless.png
MIDlet-Info-URL: http://www.wireless.com/trader/info.html
MIDlet-Data-Size: 512
MicroEdition-Profile: MIDP-1.0
MicroEdition-Configuration: CLDC
MIDlet-1: StockTrader,/com/wireless/icons/trader.png,com.wireless.TradeMIDlet 
MIDlet-2: StockBrowser,/com/wireless/icons/browser.png,com.wirelessBrowseMIDlet

In the JAR, this file would appear as META-INF/MANIFEST.mf. The JAR would also include the following files:

Note the following about the attributes in the manifest file and the content of the JAR:

The JAD file for this suite can be constructed like this:

MIDlet-Name: WirelessTrader
MIDlet-Vendor: Wireless Java Inc.
MIDlet-Version: 1.0.1
MIDlet-Description: A set of MIDlets for online trading.
MIDlet-Info-URL: http://www.wireless.com/trader/info.html
MIDlet-Data-Size: 512
MIDlet-Jar-Size: 10312
MIDlet-Jar-URL: http://www.wireless.com/trader/Midlets.jar

This file contains the information that the device displays to the user, together with the URL of the MIDlet suite JAR. In this case, the common attributes have the same values in the manifest and the JAR, but it is possible to override the MIDlet-Description, MIDlet-Icon, MIDlet-Info-URL, and MIDlet-Data-Size attributes by specifying different values in the JAD file.

Related Articles:

The Mobile Information Device Profile and MIDlets, Part 5
This is the final excerpt in a series on MIDP and MIDlets from J2ME in a Nutshell, focusing on the delivery and installation of MIDlets.

The Mobile Information Device Profile and MIDlets, Part 4
In Part 4 of this five-part excerpt from J2ME in a Nutshell, author Kim Topley shows you how to develop MIDlets.

The Mobile Information Device Profile and MIDlets, Part 3
Part three of a five-part book excerpt from O'Reilly's J2ME in a Nutshell by Kim Topley. This installment focuses on a MIDlet's three states: paused, active, and destroyed.

The Mobile Information Device Profile and MIDlets, Part 1
This is the first of a five part book excerpt series based on O'Reilly's J2ME in a Nutshell by Kim Topley. Part one is an overview of the Mobile Independent Device Profile and the MIDP Java platform.

In order to be fully portable, the JAD file should be encoded using ISO-8859-1, because all MIDP implementations are required to support this character encoding. The successful use of any other encoding depends on the target device, which may not support the encoding, and the way in which the JAD file is transported to the device. If, for example, the file is fetched using HTTP, the Content-Type header can be used to specify the encoding as described in the later section "Delivery and Installation of MIDlets." In some cases, it is useful to be able to include in the JAD file Unicode characters that are not available in the ISO-8859-1 encoding or that are not easy to access from a standard keyboard. The MIDP reference implementation allows you to use Unicode escape sequences of the form \uxxxx to overcome encoding limitations. For example, the following line includes the copyright character (Unicode value 00A9) in the MIDlet suite description:

MIDlet-Description: A set of MIDlets for online trading. \u00A9 Wireless Java Inc.

Although this feature is available in the MIDP reference implementation, it is not mentioned in the MIDP specification, so there is no guarantee that real devices will actually support it.

At runtime, a MIDlet can access files from its JAR using the getResourceAsStream( ) method of java.lang.Class. Any file in the JAR, apart from class files, can be accessed this way. This is typically how you would include images or text files that should be displayed in the user interface, an example of which will be shown in Chapter 4. A MIDlet can also define its own private attributes in the manifest file and the JAD and retrieve them at runtime, as you'll see in "Developing MIDlets" later in this chapter.

Next time, learn MIDlet Execution Environment and Lifecycle.

Kim Topley has more than 25 years experience as a software developer and was one of the first people in the world to obtain the Sun Certified Java Developer qualification.


View catalog information for J2ME in a Nutshell

Return to ONJava.com.

Copyright © 2009 O'Reilly Media, Inc.