MIDlet Suites

 

MIDlet Suites

One of the central goals for the MIDP application model is to provide support for the controlled sharing of data and resources between multiple, possibly simultaneously running MIDlets. To accomplish this goal while retaining a secure environment, the MIDP Specification requires that any MIDlets needing to interact and share data beyond what is enabled with the RMS record sharing in MIDP 2.0 (refer to Section 14.2.2, "Shared Record Stores"), the MIDlets must be placed into a single JAR. This collection of MIDlets encapsulated in a JAR is referred to as a MIDlet suite.

The MIDlets within a MIDlet suite share a common name space (for persistent storage), runtime object heap, and static fields in classes. In order to preserve the security and the original intent of the MIDlet suite provider, the MIDlets, classes, and individual files within the MIDlet suite cannot be installed, updated, or removed individually—they must be manipulated as a whole. In other words, the basic unit of application installation, updating, and removal in MIDP is a MIDlet suite.

A MIDlet suite can be characterized more precisely by its packaging and its runtime environment. These characteristics are discussed in more detail next.

19.1.1 MIDlet Suite Packaging

A MIDlet suite is encapsulated within a JAR.[1] A MIDlet suite provider is responsible for creating a JAR that includes the appropriate components for the target user, device, network, and locale. For example, since the CLDC Specification does not include the full internationalization and localization support provided by Java 2 Standard Edition, a MIDlet suite provider must tailor the JAR components to include the necessary additional resources (strings, images, and so forth) for a particular locale.

^[1] JAR format specifications are available at http://java.sun.com/products/jdk/1.4.1/docs/guide/jar/index.html. Refer to the JDK JAR and manifest documentation for syntax and related details.

The contents of the MIDlet suite's JAR include the following components:

• the class files implementing the MIDlet(s),

• any resource files used by the MIDlet(s)—for example, icon or image files, and so forth, and

• a manifest describing the JAR contents.

All the files needed by the MIDlet(s) are placed in the JAR using the standard structure based on mapping the fully qualified class names to directory and file names within the JAR. Each period is converted to a forward slash, '/'. For class files, the .class extension is appended.

19.1.2 Application Descriptor

Each JAR may be accompanied by an optional[2] application descriptor (JAD file.) The application descriptor allows the application management software on the device to verify that the associated MIDlet suite is suitable for the device before loading the full JAR. It also allows MIDlet attributes to be supplied to the MIDlet suite without modifying the JAR.

[2] The application descriptor is optional for distributors of MIDlet suites (such as wireless network operators). However, all MIDP-compliant implementations must accept an application descriptor.

The application descriptor that has the MIME type 'text/vnd.sun.j2me.app-descriptor' and the file name extension '.jad'.

The contents of the application descriptor are described by the following BNF syntax:

appldesc: *attrline
attrline: attrname ":" WSP attrvalue WSP newlines
attrname: 1*
attrvalue: *valuechar | valuechar *(valuechar | WSP) valuechar
valuechar: 
newlines = 1*newline ; allow blank lines to be ignored
newline: CR LF | LF
CR = 
LF = 
WSP: 1*( SP | HT )
SP = 
HT = 
CTL = 
separators = "(" | ")" | "<" | ">" | "@" | "," | ";" | ":" | "'" | <">
           | "/" | "[" | "]" | "?" | "=" | "{" | "}" | SP | HT

19.1.3 MIDlet Attributes

The JAR manifest and application descriptor provide a means to encode information about the contents of the JAR. In particular, the JAR manifest specification provides for name-value pairs that MIDP uses in the manifest and application descriptor to encode MIDlet attributes. MIDlet attribute names are case-sensitive.

A predefined set of attributes is specified to allow the application management software to identify, retrieve, and install the MIDlet(s). Attribute names that start with "MIDlet-" or "MicroEdition-" are reserved for use by the MIDP expert group to define MIDP-specific MIDlet attributes. MIDlet suite developers can define their own MIDlet attributes provided that the new attributes do not start with the reserved "MIDlet-" or "MicroEdition-" prefixes. The MIDP Specification currently defines the MIDlet attributes shown in Table 19.1 on page 328. All attributes appearing in the application descriptor are made available to the MIDlet(s) through the MIDlet.getAppProperty method.

In general, attributes can be located in either the application descriptor or the JAR manifest; however, some attributes must be located in specific places, as described next.

Of the predefined attributes in Table 19.1 on page 328, the following must be in the JAR manifest:

• MIDlet-Name

• MIDlet-Version

• MIDlet-Vendor

The following attributes must be in the application descriptor, if present:

• MIDlet-Name

• MIDlet-Version

• MIDlet-Vendor

• MIDlet-Jar-URL

• MIDlet-Jar-Size

The manifest or the application descriptor must contain the following attributes:

• A MIDlet-<n> for each MIDlet

• MicroEdition-Profile

• MicroEdition-Configuration

The manifest or the application descriptor can additionally contain the following attributes:

• MIDlet-Description

• MIDlet-Icon

• MIDlet-Info-URL

• MIDlet-Data-Size

• MIDlet-Permissions

• MIDlet-Permissions-Opt

• MIDlet-Push-<n>

• MIDlet-Install-Notify

• MIDlet-Delete-Notify

• MIDlet-Delete-Confirm

• Any application-specific attributes that do not begin with "MIDlet-" or "MicroEdition-"

A rudimentary form of version control between the JAR and the application descriptor is ensured by requiring that the attribute values for MIDlet-Name, MIDlet-Version, and MIDlet-Vendor be identical in the JAR manifest and the application descriptor. If they are not, then the system will assume a version mismatch, and the MIDlet suite will not be installed. All other MIDlet attributes names may also be duplicated. In the case of untrusted MIDlets, the values from the application descriptor will override the values from the JAR manifest. In the case of trusted MIDlets the values must be identical. See Section 18.3, "Trusted MIDlet Suite Security Model," for an expanded description of the trusted MIDlet security model.

As an example, the following shows a JAR manifest for a hypothetical MIDlet suite of card games provided by Motorola. The suite contains two MIDlets: Solitaire and JacksWild:

MIDlet-Name: CardGames
MIDlet-Version: 1.1.9
MIDlet-Vendor: Motorola
MIDlet-1: Solitaire, /Solitaire.png, com.motorola.Solitaire
MIDlet-2: JacksWild, /JacksWild.png, com.motorola.JacksWild
MicroEdition-Profile: MIDP-2.0
MicroEdition-Configuration: CLDC-1.1

The corresponding application descriptor for this MIDlet suite would look like this:

MIDlet-Name: CardGames
MIDlet-Version: 1.1.9
MIDlet-Vendor: Motorola
MIDlet-1: Solitaire, /Solitare.png, com.motorola.Solitare
MIDlet-2: JacksWild, /JacksWild.png, com.motorola.JacksWild
MicroEdition-Profile: MIDP-2.0
MicroEdition-Configuration: CLDC-1.1
MIDlet-Description: Really cool card games
MIDlet-Jar-URL: http://www.cardsrus.com/games/cardgames.jar
MIDlet-Jar-Size: 7378
MIDlet-Data-Size: 256

Table 19.1. MIDlet attributes

Attribute Name	Description
MIDlet-Name	The name of the MIDlet suite that identifies the MIDlets to the user.
MIDlet-Version	The version number of the MIDlet suite. The format is major.minor.micro, as described in the JDK Product Versioning Specification (see http://java.sun.com/products/jdk/1.2/docs/guide/versioning/spec/VersioningSpecification.html). It can be used by the system for installation and upgrade uses, as well as communication with the user. Default value is 0.0.0.
MIDlet-Vendor	The organization that provides the MIDlet suite.
MIDlet-Icon	The case-sensitive absolute path name of a PNG file within the JAR, which represents the MIDlet suite to the user.
MIDlet-Description	A short description of the MIDlet suite.
MIDlet-Info-URL	A URL for information further describing the MIDlet suite.
MIDlet-<n>	The name, icon, and class of the nth MIDlet in the JAR separated by a comma. The lowest value of <n> must be 1 and consecutive ordinals must be used. Name is used to identify the MIDlet to the user. Icon (optional) is the case-sensitive absolute path name of an image (PNG) within the JAR that the system should use for the icon of the nth MIDlet. Class is the name of the MIDlet class for the nth MIDlet.
MIDlet-Jar-URL	The URL from which the JAR was loaded.
MIDlet-Jar-Size	The size of the JAR in bytes.
MIDlet-Data-Size	The minimum number of bytes of persistent data required by the MIDlet. The default is zero.
MicroEdition-Profile	The J2ME profiles required, using the same format and value as the system property microedition.profiles (for example "MIDP-2.0"). The device must implement all of the profiles listed or the installation will not be attempted. Multiple profiles are separated with a blank (Unicode U+0020).
MicroEdition-Configuration	The J2ME Configuration required using the same format and value as the system property microedition.configuration (for example "CLDC-1.1").
MIDlet-Permissions	Zero or more permissions that are critical to the function of the MIDlet suite. See Section 18.3, "Trusted MIDlet Suite Security Model," for details of usage.
MIDlet-Permissions-Opt	Zero or more permissions that are non-critical to the function of the MIDlet suite. See Section 18.3, "Trusted MIDlet Suite Security Model," for details of usage.
MIDlet-Push-<n>	Register a MIDlet to handle inbound connections. Refer to Section 17.2.2, "Mechanics of Static Push Registration," for details.
MIDlet-Install-Notify	The URL to which a POST request is sent to report the installation status (whether a new installation or MIDlet suite update) of this MIDlet suite.
MIDlet-Delete-Notify	The URL to which a POST request is sent to report the deletion of this MIDlet suite.
MIDlet-Delete-Confirm	A text message to be provided to the user when prompted to confirm deletion of this MIDlet suite.

19.1.4 MIDlet Suite Execution Environment

The MIDP Specification defines the environment in which MIDlets within a suite execute. This environment is shared by all MIDlets within a MIDlet suite, and any MIDlet can interact with other MIDlets packaged in a suite. The runtime environment is logically composed of name spaces, as depicted in Figure 19.1. These name spaces determine how a MIDlet accesses an entity within that name space.

Figure 19.1. MIDlet suite name spaces

The logical name spaces in a MIDlet's runtime environment are as follows:

• Classes and native code that implement the CLDC and MIDP as well as any other CLDC profiles, optional packages, and licensee open classes. This is the only name space that is shared by all MIDlet suites on the device.

• Classes within the MIDlet suite's JAR.

• All non-class files in the MIDlet suite's JAR, such as icon or image files, and the JAR manifest. These files are accessible via the method java.lang.Class.getResourceAsStream.

• The contents of the Java Application Descriptor (JAD). The contents are accessible via the method javax.microedition.midlet.MIDlet.getAppProperty. (Note: the JAR manifest attributes are also accessible via this method.)

• A separate name space for RMS record stores (see Chapter 14, "MIDP Persistence Libraries").

All the classes needed by a MIDlet within a suite must be in the JAR or in the system libraries (system libraries typically include the CLDC and MIDP libraries as well as optional packages and manufacturer-specific libraries.) A MIDlet may load and invoke methods from any class in the JAR or in the system libraries. All of the classes within these scopes are shared in the execution environment, along with a single heap containing the objects created by MIDlets, MIDP libraries, and CLDC libraries. The usual locking and synchronization primitives of the Java programming language can be used where necessary to avoid concurrency problems.

The class files of the MIDlet are only available for execution and can neither be read as resources nor extracted for reuse, since the underlying CLDC implementation may store and interpret the contents of the JAR in any manner suitable for the device.

The non-class files within the JAR, including the JAR manifest, can be accessed using the method java.lang.Class.getResourceAsStream. The parameter to this method, a String object, represents a path that is interpreted in the following manner: If it begins with a '/', the search for the resource begins at the "root" of the JAR; however, if it does not begin with a '/', the resource is searched for along a path relative to the class instance retrieving the resource. For example, if a JAR has the following contents as shown in this JAR manifest:

META-INF/
META-INF/MANIFEST.MF
examples/
examples/HelloWorld.class

then, in the following code fragment, both getResourceAsStream calls will open an InputStream to the manifest.

Class C = Class.forName("examples.HelloWorld");
InputStream s1 = C.getResourceAsStream("/META-INF/MANIFEST.MF");
InputStream s2 = C.getResourceAsStream("../META-INF/MANIFEST.MF");