There is one additional method in the MIDlet class and it is related to the MIDlet life cycle: resumeRequest(). A MIDlet in the Paused state can call this method to signal to the application manager that it wants to become Active. It might seem weird to think about a MIDlet in the Paused state running any code at all. However, Paused MIDlets are still able to handle timer events or other types of callbacks and thus have some chances to call resumeRequest(). If the application manager does decide to move a MIDlet from the Paused to the Active state, it will do so through the normal mechanism of calling startApp().

Requesting a Wakeup Call

    MIDlets can request to be launched at a later time, in essence requesting a wakeup call from the implementation. The method is defined in javax.microedition.io.PushRegistry, which is kind of a weird place for it. All of PushRegistry’s other methods have to do with launching MIDlets in response to incoming network connections; the class is fully described in a lesson later. The following method in PushRegistry requests that a named MIDlet be woken up at a specific time: public static long registerAlarm(String midlet, long time) throws ClassNotFoundException, ConnectionNotFoundException You need to supply the class name of a MIDlet in the MIDlet suite, and time specifies exactly when you want the MIDlet to be launched, in the standard form as the number of milliseconds since January 1, 1970. If you supply a class name that is not found in the current MIDlet suite, a ClassNotFoundException is thrown. If the implementation is unable to launch MIDlets at specified times, a ConnectionNotFoundException is thrown. If the MIDlet for which you are requesting a timed launch was previously registered for timed launch, this method returns the previous wakeup time.

A Bridge to the Outside World

    Many MIDP devices, especially mobile phones, have web browsers, using either the WAP or HTTP protocol. The MIDlet class supplies a bridge to these browsers and other capabilities: public final boolean platformRequest(String URL)throws ConnectionNotFoundException On a sophisticated device, the browser and the MIDlet suite may be able to run at the same time, in which case the browser will be launched and pointed to the specified URL. In this case, the method returns true. On smaller devices, the browser may not be able to run until the MIDlet is destroyed. In this case, platformRequest() returns false, and it’s the MIDlet’s responsibility to terminate. After the MIDlet terminates, it’s the implementation’s responsibility to launch the browser and  point it at the specified URL.In either case, platformRequest() is a nonblocking method. There are two special possibilities for the supplied URL. If you supply a telephone number URL of the form tel:<number> as specified in RFC 2806 (http://ietf.org/rfc/rfc2806.txt), the Implementation should initiate a voice call.If you supply the URL of a MIDlet suite descriptor or JAR, the implementation should eventually start the application manager and attempt to install the given MIDlet suite (after asking for your permission, of course).

Packaging MIDlets

    MIDlets are deployed in MIDlet suites. A MIDlet suite is a collection of MIDlets with some extra information. There are two files involved. One is an application descriptor, which is a simple text file. The other is a JAR file that contains the class files and resource files that make up your MIDlet suite. Like any JAR file, a MIDlet suite’s JAR file has a manifest file. If you use a tool like the J2ME Wireless Toolkit, you don’t need to worry much about MIDlet suite packaging because most of the details are handled automatically. If you want to understand things at a lower level, or if you’re just curious, keep reading for a complete description of MIDlet suite packaging. Packaging a MIDlet suite consists of three steps:

1. The class files and resource files that make up the MIDlets are packaged into a JAR file. Usually, you’ll use the jar command-line tool to accomplish this.

2. Additional information that’s needed at runtime is placed in the JAR’s manifest file. All JARs include a manifest; a MIDlet suite JAR contains some extra information needed by application management software.

3. An application descriptor file should also be generated. This is a file with a .jad extension that describes the MIDlet suite JAR. It can be used by the application management software to decide whether a MIDlet suite JAR should be downloaded to the device.

MIDlet Manifest Information

    The information stored in a MIDlet’s manifest file consists of name and value pairs, like a properties file. For example, an unadorned JAR manifest might look like this:

Manifest-Version: 1.0

Created-By: 1.4.2_04 (Sun Microsystems Inc.)

A MIDlet JAR manifest for HelloMIDlet looks like this:

Manifest-Version: 1.0

MIDlet-Name: HelloMIDlet

MIDlet-Version: 2.0

MIDlet-Vendor: Sun Microsystems

Created-By: 1.4.2_04 (Sun Microsystems Inc.)

MicroEdition-Configuration: CLDC-1.0

MicroEdition-Profile: MIDP-2.0

    The extra attributes describe software versions, class names, and other information about the MIDlet suite. The following attributes must be included: • MIDlet-Name: Despite the moniker, this attribute actually refers to the name of the entire MIDlet suite, not just one MIDlet.

•  MIDlet-Version: This describes the version of the MIDlet suite. It’s a number you pick yourself in the form major.minor.micro.

• MIDlet-Vendor: This is your name or the name of your company.

• MIDlet-n: For each MIDlet in the MIDlet suite, the displayable name, icon file name, and class name are listed. The MIDlets must be numbered starting from 1 and counting up.For example, several MIDlets in a single MIDlet suite could be listed like this:

    MIDlet-1: Sokoban, /icons/Sokoban.png, example.sokoban.Sokoban

    MIDlet-2: Tickets, /icons/Auction.png, example.lcdui.TicketAuction

    MIDlet-3: Colors, /icons/ColorChooser.png, example.chooser.Color

    MIDlet-4: Stock, /icons/Stock.png, example.stock.StockMIDlet

• MicroEdition-Configuration: This attribute describes the J2ME configurations upon which this MIDlet suite can run. Multiple configuration names should be separated by spaces.   

• MicroEdition-Profile: This describes the set of profiles upon which this MIDlet suite can run. For MIDP 2.0 applications, this is MIDP-20. For applications that can also run on the older MIDP 1.0 profile, use “MIDP-2.0 MIDP-1.0”. In addition to the required manifest attributes, the following attributes may be defined:

• MIDlet-Description: The description of the MIDlet suite goes in this attribute.

• MIDlet-Icon: Icons for individual MIDlets are described in the MIDlet-n attributes. This attribute specifies an icon to represent the entire MIDlet suite.

• MIDlet-Info-URL: If additional information about the MIDlet suite is available online, use this attribute to list the URL.

• MIDlet-Data-Size: If you know how many bytes of persistent data are required by the MIDlet suite, you can specify the number with this attribute.

¡Tip Don’t get tripped up by the attribute names. Many of them appear to refer to a single MIDlet, like MIDlet-Name and MIDlet-Description. In fact, these attributes describe an entire MIDlet suite. The only attribute that applies to a specific MIDlet is the MIDlet-n attribute, which is used to list each MIDlet in the suite. Several additional attributes may be included. Network APIs can be protected from unauthorized access using a permission scheme, which will be fully discussed later in this chapter. MIDlets can list necessary permissions and optional permissions in the MIDlet JAR manifest asfollows:

• MIDlet-Permissions: Use this attribute to list permissions that are critical to the operation of the MIDlet suite. Multiple permissions are separated by commas.

• MIDlet-Permissions-Opt: This attribute lists permissions that may be used but are not critical for this MIDlet suite. Finally, there is also a way for MIDlet suites to signal their dependence on optional APIs:

• MIDlet-Extensions: List the required Optional APIs used by this MIDlet suite in this attribute. The exact names are determined by the individual optional API specifications.

Application Descriptor

    The attributes in a MIDlet suite JAR are used by the application management software to run MIDlets within a suite. The application descriptor, by contrast, contains information that helps a device and/or the user decide whether or not to load a MIDlet suite. Because an application descriptor is a file separate from the MIDlet suite JAR, it is easy for a device to load and examine the file before downloading the MIDlet suite. As it happens, a lot of the information in the application descriptor has to be the same as the information that’s in the MIDlet suite JAR. For example, the application descriptor must contain the MIDlet-Name, MIDlet-Version, and MIDlet-Vendor attributes. In addition, it must include the following:

• MIDlet-Jar-URL: This is the URL where the MIDlet suite JAR can be found.

• MIDlet-Jar-Size: This is the size, in bytes, of the MIDlet suite JAR.

The application descriptor can optionally contain the MIDlet-Description, MIDlet-Icon,

MIDlet-Info-URL, and MIDlet-Data-Size attributes.

Devices and emulators vary widely in their handling of MIDlet suite descriptors. Some will fail installation if any fields in the descriptor are incorrect, while others are more lenient. A tool like the J2ME Wireless Toolkit is extremely useful in creating well-formed descriptors. The application descriptor is useful in over the air (OTA) deployment. A device (and theuser) can download and inspect the descriptor, a relatively short file, before deciding whether the entire MIDlet suite JAR should be downloaded and installed. For OTA provisioning, the server’s returned MIME type for the application descriptor should be text/vnd.sun.j2me.app-descriptor. This and more (a whole protocol) is described in the “Over the Air User Initiated Provisioning

Specification” section of the MIDP 2.0 specification.

MIDlet Properties

More About MIDlets

    Last month, you got a quick introduction to the process of building and running MIDlets. In this lesson, you’ll explore the more details about MIDlets.

The MIDlet Life Cycle

    MIDP applications are represented by instances of the javax.microedition.midlet.MIDlet class. MIDlets have a specific life cycle, which is reflected in the methods and behavior of the MIDlet class. A piece of device-specific software, the application manager, controls the installation, execution, and life cycle of MIDlets. MIDlets have no access to the application manager. A MIDlet is installed by moving its class files to a device. The class files will be packaged in a Java Archive (JAR), while an accompanying descriptor file (with a .jad extension) describes the contents of the JAR.

A MIDlet goes through the following states:

    1. When the MIDlet is about to be run, an instance is created. The MIDlet’s constructor is run, and the MIDlet is in the Paused state.

    2. Next, the MIDlet enters the Active state after the application manager calls startApp().

    3. While the MIDlet is Active, the application manager can suspend its execution by calling pauseApp(). This puts the MIDlet back in the Paused state. A MIDlet can place        itself in the Paused state by calling notifyPaused().

    4. While the MIDlet is in the Paused state, the application manager can call startApp() to put it back into the Active state.

    5. The application manager can terminate the execution of the MIDlet by calling destroyApp(), at which point the MIDlet is destroyed and patiently awaits garbage collection. A MIDlet can destroy itself by calling notifyDestroyed().Figure 3-1 shows the states of a MIDlet and the transitions between them.

    There is one additional method in the MIDlet class and it is related to the MIDlet life cycle: resumeRequest(). A MIDlet in the Paused state can call this method to signal to the application manager that it wants to become Active. It might seem weird to think about a MIDlet in the Paused state running any code at all. However, Paused MIDlets are still able to handle timer events or other types of callbacks and thus have some chances to call resumeRequest(). If the application manager does decide to move a MIDlet from the Paused to the Active state, it will do so through the normal mechanism of calling startApp().

Requesting a Wakeup Call

    MIDlets can request to be launched at a later time, in essence requesting a wakeup call from the implementation. The method is defined in javax.microedition.io.PushRegistry, which is kind of a weird place for it. All of PushRegistry’s other methods have to do with launching MIDlets in response to incoming network connections; the class is fully described in a lesson later. The following method in PushRegistry requests that a named MIDlet be woken up at a specific time: public static long registerAlarm(String midlet, long time) throws ClassNotFoundException, ConnectionNotFoundException You need to supply the class name of a MIDlet in the MIDlet suite, and time specifies exactly when you want the MIDlet to be launched, in the standard form as the number of milliseconds since January 1, 1970. If you supply a class name that is not found in the current MIDlet suite, a ClassNotFoundException is thrown. If the implementation is unable to launch MIDlets at specified times, a ConnectionNotFoundException is thrown. If the MIDlet for which you are requesting a timed launch was previously registered for timed launch, this method returns the previous wakeup time.

A Bridge to the Outside World

    Many MIDP devices, especially mobile phones, have web browsers, using either the WAP or HTTP protocol. The MIDlet class supplies a bridge to these browsers and other capabilities: public final boolean platformRequest(String URL)throws ConnectionNotFoundException On a sophisticated device, the browser and the MIDlet suite may be able to run at the same time, in which case the browser will be launched and pointed to the specified URL. In this case, the method returns true. On smaller devices, the browser may not be able to run until the MIDlet is destroyed. In this case, platformRequest() returns false, and it’s the MIDlet’s responsibility to terminate. After the MIDlet terminates, it’s the implementation’s responsibility to launch the browser and  point it at the specified URL.In either case, platformRequest() is a nonblocking method. There are two special possibilities for the supplied URL. If you supply a telephone number URL of the form tel:<number> as specified in RFC 2806 (http://ietf.org/rfc/rfc2806.txt), the Implementation should initiate a voice call.If you supply the URL of a MIDlet suite descriptor or JAR, the implementation should eventually start the application manager and attempt to install the given MIDlet suite (after asking for your permission, of course).

Packaging MIDlets

    MIDlets are deployed in MIDlet suites. A MIDlet suite is a collection of MIDlets with some extra information. There are two files involved. One is an application descriptor, which is a simple text file. The other is a JAR file that contains the class files and resource files that make up your MIDlet suite. Like any JAR file, a MIDlet suite’s JAR file has a manifest file. If you use a tool like the J2ME Wireless Toolkit, you don’t need to worry much about MIDlet suite packaging because most of the details are handled automatically. If you want to understand things at a lower level, or if you’re just curious, keep reading for a complete description of MIDlet suite packaging. Packaging a MIDlet suite consists of three steps:

1. The class files and resource files that make up the MIDlets are packaged into a JAR file. Usually, you’ll use the jar command-line tool to accomplish this.

2. Additional information that’s needed at runtime is placed in the JAR’s manifest file. All JARs include a manifest; a MIDlet suite JAR contains some extra information needed by    application management software.

3. An application descriptor file should also be generated. This is a file with a .jad extension that describes the MIDlet suite JAR. It can be used by the application management software to decide whether a MIDlet suite JAR should be downloaded to the device.

MIDlet Manifest Information

    The information stored in a MIDlet’s manifest file consists of name and value pairs, like a properties file. For example, an unadorned JAR manifest might look like this:

Manifest-Version: 1.0

Created-By: 1.4.2_04 (Sun Microsystems Inc.)

A MIDlet JAR manifest for HelloMIDlet looks like this:

Manifest-Version: 1.0

MIDlet-Name: HelloMIDlet

MIDlet-Version: 2.0

MIDlet-Vendor: Sun Microsystems

Created-By: 1.4.2_04 (Sun Microsystems Inc.)

MicroEdition-Configuration: CLDC-1.0

MicroEdition-Profile: MIDP-2.0

    The extra attributes describe software versions, class names, and other information about the MIDlet suite. The following attributes must be included: • MIDlet-Name: Despite the moniker, this attribute actually refers to the name of the entire MIDlet suite, not just one MIDlet.

•  MIDlet-Version: This describes the version of the MIDlet suite. It’s a number you pick yourself in the form major.minor.micro.

• MIDlet-Vendor: This is your name or the name of your company.

• MIDlet-n: For each MIDlet in the MIDlet suite, the displayable name, icon file name, and class name are listed. The MIDlets must be numbered starting from 1 and counting up.For example, several MIDlets in a single MIDlet suite could be listed like this:

    MIDlet-1: Sokoban, /icons/Sokoban.png, example.sokoban.Sokoban

    MIDlet-2: Tickets, /icons/Auction.png, example.lcdui.TicketAuction

    MIDlet-3: Colors, /icons/ColorChooser.png, example.chooser.Color

    MIDlet-4: Stock, /icons/Stock.png, example.stock.StockMIDlet

• MicroEdition-Configuration: This attribute describes the J2ME configurations upon which this MIDlet suite can run. Multiple configuration names should be separated by spaces.

• MicroEdition-Profile: This describes the set of profiles upon which this MIDlet suite can run. For MIDP 2.0 applications, this is MIDP-20. For applications that can also run on the older MIDP 1.0 profile, use “MIDP-2.0 MIDP-1.0”. In addition to the required manifest attributes, the following attributes may be defined:

• MIDlet-Description: The description of the MIDlet suite goes in this attribute.

• MIDlet-Icon: Icons for individual MIDlets are described in the MIDlet-n attributes. Thisattribute specifies an icon to represent the entire MIDlet suite.

• MIDlet-Info-URL: If additional information about the MIDlet suite is available online, use this attribute to list the URL.

• MIDlet-Data-Size: If you know how many bytes of persistent data are required by the MIDlet suite, you can specify the number with this attribute.

¡Tip Don’t get tripped up by the attribute names. Many of them appear to refer to a single MIDlet, like MIDlet-Name and MIDlet-Description. In fact, these attributes describe an entire MIDlet suite. The only attribute that applies to a specific MIDlet is the MIDlet-n attribute, which is used to list each MIDlet in the suite. Several additional attributes may be included. Network APIs can be protected from unauthorized access using a permission scheme, which will be fully discussed later in this chapter. MIDlets can list necessary permissions and optional permissions in the MIDlet JAR manifest asfollows:

• MIDlet-Permissions: Use this attribute to list permissions that are critical to the operation of the MIDlet suite. Multiple permissions are separated by commas.

• MIDlet-Permissions-Opt: This attribute lists permissions that may be used but are not critical for this MIDlet suite. Finally, there is also a way for MIDlet suites to signal their dependence on optional APIs:

• MIDlet-Extensions: List the required Optional APIs used by this MIDlet suite in this attribute. The exact names are determined by the individual optional API specifications.

Application Descriptor

    The attributes in a MIDlet suite JAR are used by the application management software to run MIDlets within a suite. The application descriptor, by contrast, contains information that helps a device and/or the user decide whether or not to load a MIDlet suite. Because an application descriptor is a file separate from the MIDlet suite JAR, it is easy for a device to load and examine the file before downloading the MIDlet suite. As it happens, a lot of the information in the application descriptor has to be the same as the information that’s in the MIDlet suite JAR. For example, the application descriptor must contain the MIDlet-Name, MIDlet-Version, and MIDlet-Vendor attributes. In addition, it must include the following:

• MIDlet-Jar-URL: This is the URL where the MIDlet suite JAR can be found.

• MIDlet-Jar-Size: This is the size, in bytes, of the MIDlet suite JAR.

The application descriptor can optionally contain the MIDlet-Description, MIDlet-Icon,

MIDlet-Info-URL, and MIDlet-Data-Size attributes.

Devices and emulators vary widely in their handling of MIDlet suite descriptors. Some will fail installation if any fields in the descriptor are incorrect, while others are more lenient. A tool like the J2ME Wireless Toolkit is extremely useful in creating well-formed descriptors. The application descriptor is useful in over the air (OTA) deployment. A device (and theuser) can download and inspect the descriptor, a relatively short file, before deciding whether the entire MIDlet suite JAR should be downloaded and installed. For OTA provisioning, the server’s returned MIME type for the application descriptor should be text/vnd.sun.j2me.app-descriptor. This and more (a whole protocol) is described in the “Over the Air User Initiated Provisioning Specification” section of the MIDP 2.0 specification.

<!--[if !supportLineBreakNewLine]-->

<!--[endif]-->

MIDlet Properties

    There’s one other possibility for attributes in the manifest or application descriptor. You can add attributes that have meaning to your MIDlets. MIDlets can retrieve the values of these attributes using the getAppProperty() method in the javax.microedition.midlet.MIDlet class. An attribute can be listed in the application descriptor, JAR manifest, or both; if it is listed in both, the value from the application descriptor will be used. In general, it makes sense to store application properties in the application descriptor file. Because it’s distinct from the MIDlet suite JAR, the application descriptor can easily be changed to modify the behavior of your MIDlets. You might, for example, store a URL or other configuration information in the application descriptor.

For example, suppose you put an application-specific attribute in the application descriptor, like this:

Jargoneer.url: http://www.dict.org/bin/Dict

Inside the MIDlet, you can retrieve the value of the attribute like this:

String url = getAppProperty("Jargoneer.url");

Changing the URL is as easy as changing the application descriptor, a simple text file. None of your code needs to be recompiled. This could be useful if you were expecting to distribute many copies of a MIDlet and wanted to share the server load among a group of servers. You could distribute the same MIDlet suite JAR with a group of different application descriptors, each one using a MIDlet attribute to point to a different server.

MIDlet Suite Security

    Wireless application security is important to almost everyone involved in the wireless industry:

• Carriers want to be sure that viruses do not bring down their customers’ devices or their networks.

• Device manufacturers don’t want customer-installed software crashing their devices.

• Users want to be able to run downloaded code without threatening the stability of their device or the safety of their personal information. Additionally, they may want control over the network usage of their applications, as network usage often costs money.

• Application developers do not want their applications to be compromised by other applications.

Permissions

    Permissions provide MIDlets with an explicit security architecture. In a nutshell, MIDlets must have permission to perform sensitive operations. The only parts of the API that are protected by permissions are the network connections. Optional APIs are free to define additional permissions to protect sensitive data or functionality.Permission names use the same prefix and class or interface name as the API that they protect. Later, we’ll explain the names of the network permissions in detail. For the moment, suppose that you write a MIDlet that needs to make a socket connection. This MIDlet would need the permission of javax.microedition.io.Connector.socket. The MIDlet itself needs no knowledge of permissions. It simply attempts the connection, which either succeeds or throws a java.lang.SecurityException. There is a method in the MIDlet class that programmers can use to check if a permission will be granted or denied: public final int checkPermission(String permission)  This method returns 1 if the permission is granted and 0 if the permission is denied. A special return value, -1, indicates that the implementation cannot determine whether the permission will be granted or denied, which might be the case if the user will be asked about the given permission.

Protection Domains

    MIDlet suites belong to protection domains that determine which permissions are granted, which are denied, and which ones must be deferred to the user’s judgment. A protection domain is kind of like a secret club and comprises two parts:

    1. The set of permissions that are allowed and those for which the user must be consulted

    2. The rules for how a MIDlet suite can get into this protection domain

    A very simple protection domain, “SimplePD,” might contain the permission javax.microedition.io.Connector.http. The rules for membership in SimplePD could be something as simple as verifying the origin IP address of the MIDlet suite. For example, if the MIDlet suite is downloaded from www.bigcarrier.com, then the application management software on the device would know to place the MIDlet suite in the SimplePD protection domain. At runtime, any MIDlet that tries to make an HTTP connection will be granted the permission. Attempts to make other connection types will be denied. The simple IP-origin criterion for SimplePD is pretty weak. MIDlet suites in SimplePD are susceptible to many attacks, including data modification, data replacement, man-in-the-middle attacks, and DNS spoofing. More robust rules are based on cryptographic solutions for data integrity and authentication. In the MIDP 2.0 specification, the section “Trusted MIDlet Suites Using X.509 PKI” describes one such scheme, including additional manifest attributes. MIDlet suites whose contents and origin cannot be verified are placed in a kind of default protection domain, the untrusted domain. The only restriction placed on the untrusted domain is that, given explicit confirmation from the user, it must allow MIDlets access to HTTP and HTTPS connections. The concept of protection domains is deliberately vague, leaving MIDP vendors with considerable latitude in their implementation. Our guess is that many implementations will choose to have a single untrusted domain and a single trusted domain, with entry to the trusted domain limited to cryptographically signed (and verified) MIDlet suites.

Permission Types

The protection domain contains the permissions that will be granted to MIDlets (allowed permissions) as well as the permissions for which the user must be consulted (user permissions). There are several varieties of user permissions. Blanket means that the user is only required to grant or deny the permission once for a MIDlet suite. Session means that the user must grant or deny permission once per invocation of a MIDlet suite. Finally, oneshot indicates that the user must be consulted each time the necessary permission is needed.

Permissions in MIDlet Suite Descriptors

    There are additional attributes for MIDlet suite descriptors. If your MIDlet suite absolutely, positively needs certain permissions, use the MIDlet-Permissions attribute. For example, if your MIDlet suite needs to make HTTP connections to function correctly, you would have a line in your descriptor file like this: MIDlet-Permissions: javax.microedition.io.Connector.http

    Multiple permission types are placed on the same line, separated by commas. If your MIDlet suite does not need certain permissions to function, but it may use them for enhanced functionality, these permissions can be placed in the MIDlet-Permissions-Opt attribute. At installation time, the application management software will compare the permissions requested in the descriptor with the permissions in the destination protection domain. If there are irreconcilable differences, the MIDlet suite will not be installed.