Chapter   15

Java Application Manager (JAM)

A central requirement for KVM in most target devices is to be able to execute applications that have been downloaded dynamically from the network. Once downloaded, the user commonly wants to use the applications several times before deleting them. The process of downloading, installing, inspecting, launching and uninstalling of Java applications is referred to generally as application management. In typical desktop computing environments, these tasks can be performed by utilizing the facilities of the host operating system. However, the situation is very different in many small, resource-constrained devices which often lack even basic facilities such as a built-in file system.

To facilitate the porting of KVM to small, resource-constrained platforms, KVM implementation contains an optional component called Java Application Manager (JAM) that can be used as a starting point for machine-specific implementations.

At the compilation level, JAM can be turned on or off by using the flag

    #define USE_JAM 1 

When building the KVM using gnumake, the following command automatically builds the system with the JAM enabled:

    gnumake USE_JAM=true 

This section provides a brief overview of the JAM reference implementation provided with KVM. The description below assumes that the target device has some kind of a “microbrowser” that can be used for initiating the downloading of applications. This microbrowser is commonly provided as part of the native computing environment, but it can also be part of the JAM in some implementations.

15.1 Using the JAM to install applications

Java Application Manager is a native C application that is responsible for downloading, installing, inspecting, launching, and uninstalling Java applications.

From the user’s viewpoint, the JAM is typically used as follows:

The user sees an application advertised on a content provider’s web page.
The user selects the tag to install it.
The Java application is downloaded and installed.
The user runs it.

While browsing a content provider web page using a native microbrowser, the user sees a description of the Java application in the text of the page, and a highlighted tag (or button) that asks them if they want to install the application. The tag contains a reference to an application Descriptor File. The Descriptor File, typically with a .jam file extension, is a text file consisting of name/value pairs. The purpose of this file is to allow the JAM to decide, before it tries to download it, whether the Java application the user selected can be installed successfully on the device. This saves the user the cost of moving the Java application to the device if it cannot be installed. The Descriptor File is small (several hundred bytes), while a typical Java application is from 10 to 20 kilobytes, so it is much cheaper to download the Descriptor File rather than the entire Java application.
The user selects the tag to start the installation process. The browser retrieves the Descriptor File from the web site.
The browser transfers program control to the JAM, passing it the content of the Descriptor File and the URL for the page it was browsing.
The JAM checks to see if the application is already installed on the device, and checks its version number (see later discussion on the details of application updating.) It then reads the JAR-File-Size tag of the Java application to ensure that there is sufficient space on the device to save it.
If there is sufficient space to install the application, the JAM uses the JAR-File-URL tag in the descriptor file to get the URL of the JAR file (it may use the base URL to the Descriptor File, if the JAR-File-URL tag is a relative URL) and start the download process using HTTP. The JAM then stores the JAR file on the device.

If the download process is interrupted, the JAM discards the partially downloaded application, as if the application was never downloaded before.
The JAM adds the application to the list of installed Java applications, and registers it with any other native tools as required. The JAM saves the following information along with the JAR file:
name of JAR file,
absolute URL from which the JAR file was downloaded,
main class of the java application,
name of the application,
version number of the application.

The absolute URL and the version number are used to uniquely identify an application during application update (see next subsection.)

In the reference implementation of the JAM, the user is shown the list of installed Java applications on the device, with the recently installed application selected for execution.

However, if the Use-Once tag is set to yes, JAM does not add the application to the list, and it launches the application immediately.

Any errors encountered during the process must be handled by the JAM. A help page URL for the content provider is included in the Descriptor File. The JAM can then direct the user to this URL using the native browser.

15.1.1 Application launching

Here’s a typical use case for launching a Java application:

The user is shown a list of Java applications (the user interface design is left up to the manufacturer.)
The user selects the Java application that is to be launched (the user interface design and selection mechanism is left up to the manufacturer).
The JAM launches the KVM with a parameter containing the main class of the application. The KVM initializes the main class and starts executing it. As additional classes are required for the execution of the application, the KVM uses a manufacturer-defined API to unpack and load the class files from the stored JAR file.
The Java application is displayed on the screen to the user.
When the application exits, and if the Use-Once tag in the Descriptor File is set to YES, the JAM removes the JAR file.

15.1.2 Application updating

When the content provider updates an application (for example, to fix bugs or add new features), the content provider should do the following:

Assign a new version number to the application.
Change the Descriptor File of the application to use the new version number.
Post the updated JAR file on the content provider's web site, using the same JAR-File-URL tag as the previous version of the application.

When the user requests the installation of an application, the JAM checks if the application's JAR-File-URL is the same as one of the installed applications. If so, and the Application-Version of the requested version is newer than the installed version, the JAM prompts for user approval before downloading and installing the newer version of the application.

The reference implementation uses a string to specify the version number in the following format:

Major.Minor[.Micro] (X.X[.X]), where the .Micro portion is optional (it defaults to “0”). In addition, each portion of the version number is allowed to a maximum of 2 decimal digits (that is, the range is from 0 to 99.)

For example, “1.0.0” can be used to specify the first version of an application. For each portion of the version number, leading zeros are not significant. For example, “08” is equivalent to “8”. Also, “1.0” is equivalent to “1.0.0”. However, “1.1” is equivalent to “1.1.0”, and not “1.0.1”.

In the reference implementation, missing Application-Version tag is assumed to be “0.0.0”, which means that any non-zero version number is considered as a newer version of the application.

The JAM must ensure that if the application update fails for any reason, the older version is left intact on the device. When the update is successful, the older version of the application is removed.

15.2 JAM components

15.2.1 Security requirements

The JAM, its data, and associated libraries, should be stored securely on the device. The device manufacturer must ensure that these components cannot be modified by Java applications or other downloadable content.

15.2.2 JAR file

JAR files are a standard feature of Java technology designed to hold class files and application resource data in a compressed format. JAM-compliant JAR files hold exactly one Java application and its associated resources. Compressed JAR files reduce the size of the application by approximately 40% to 50%. This both reduces the storage requirements on the device and reduces the download time for the application. Items in the JAR file are unpacked as required by the JAM.

15.2.3 Application Descriptor File

The Application Descriptor File is a readable text file. It consists of name-value pairs that describe the important aspects of its associated Java application. It is referenced from a tag on a content provider's web page. It is created and maintained by the Java application developer and stored along with its application JAR file on the same web site. Developers may create this file with any text editor.

The Descriptor File has the following entries (tag names are case sensitive):

Application-Name 

Displayable text, limited to width of screen on the device

Application-Version	 

Major.Minor[.Micro] (X.X[.X], where X is a 1 or 2 digit decimal number, and the .Micro part is optional)

KVM-Version 

Comma separated list of KVM version strings as defined in the CLDC microedition.configuration system property (see CLDC Specification).
“CLDC-1.0” is an example of the KVM version string. The items in the list are matched against the KVM version string on the device, and an exact match is required to execute this application. Any item matching the KVM version string on the device satisfies this condition. For example, “CLDC-1.0, CLDC-1.0.3” runs on either version of KVM on the device.

Main-Class 

Text name of the application's Main class in standard Java format.

JAR-File-Size 

Integer in bytes

JAR-File-URL 

Standard URL text format to specify the source URL. If this is a relative URL, then the URL to the Descriptor File is the base URL.

Use-Once 

yes/no

Help-Page-URL	 

Standard URL text format, used by the browser to access help pages

Additional requirements and restrictions:

The MIME type for the Descriptor File is application/x-jam and the extension is .jam.
All URLs must point to the same server from which the web page was loaded.
The JAM must store the Descriptor File contents, in a manufacturer-specific format for possible later use.

The application developer may add any application specific name-value pairs to the Descriptor File. This allows the application to be configured at deployment by changing the values in the Descriptor File. So, different Descriptor Files could use the same application JAR file, with different application parameters.

The format of the tag is a string, but it is recommended that it follow a similar style as the tags defined in the above table. The format of the value is an application specific string.

A simple proposed API to retrieve the value via the JAM could be:

    public String GetApplicationParameter(String name) 

15.2.4 Network communication

Whenever a Java application tries to make an HTTP connection, the networking implementation should check with the JAM to find the name of the server where the application was downloaded. This ensures that the connection is made to the same server the application came from. A string comparison is made between the host name in both the URLs.

15.3 Application lifecycle management

The lifecycle of a Java application is defined to be the following:

The KVM task is launched and instructed to execute the main class of the Java application (as described by the Main-Class entry of the Descriptor File.)
The Java application executes inside the context of the KVM task and responds to user events.
The KVM task exits, either voluntarily, or involuntarily, and terminates the Java application.

The term task is used loosely to describe the KVM as a logically distinct execution unit. In actual devices, the KVM task can be implemented as a task, a process or a thread of the underlying operating system.

The API functions for controlling the lifecycle of the KVM are not specified, as the mechanism is vastly different from platform to platform. Instead, it is required that all JAM implementations support the following features:

The JAM implementation must be able to launch the KVM task and start executing the main class of the Java application.
The JAM implementation must be able to forcibly terminate the KVM task, and optionally be able to suspend and resume the KVM task.
The suspension, resumption, and termination of the KVM must be performed by the procedures described below.

15.3.1 Termination of the KVM Task

The KVM task can be terminated in two ways: voluntarily or involuntarily.

The application can voluntarily terminate itself by calling the Java method System.exit. Under certain conditions, the JAM may decide to force the KVM to terminate. The exact method of triggering forced termination is platform dependent. For example, the JAM may spawn a watchdog thread that wakes up after a certain period. If the watchdog thread detects that the KVM has not terminated voluntarily, it forces the KVM to terminate.

During forced termination, the JAM actively frees all resources allocated by the KVM and terminates the KVM task. The exact procedure is platform dependent. On some platforms, calling exit or kill may be enough. On other platforms, more elaborate clean-up may be required.

15.4 Error handling

The JAM is responsible for handling all errors encountered in installing and launching Java applications. The method of handling errors differs from implementation to implementation, but the JAM should be able to interact with the user to resolve the error if possible. To assist in this, the Descriptor File has a tag called Help-Page-URL that is set by the content provider. The JAM may decide that under certain conditions, the browser should be invoked and the user sent to the help page. The help page could have information that would allow the user to contact the content provider for additional assistance.

15.4.1 Error conditions

The following are a set of possible error conditions and sample messages that can be displayed to describe the error to the user. Manufacturers should design the messages so that they are appropriate to their device user interface.

The user tries to install an application whose size is larger than the total storage space available on the device:

“NAMEOFAPP” is too large to run on this device and cannot be installed.

The user tries to install an application, whose size is larger than the free storage space (but smaller than the total storage space) on the device:

There is not enough room to install. Try removing an application and trying again.

The user tries to install an application that is already installed on the device.

“NAMEOFAPP” is already installed. (Soft buttons should be labeled OK and Launch. Launch would run the existing application on the device.)

The user tries to install an application that is not designed for the particular device they own.

“NAMEOFAPP” won't work on this device. Choose another application. (Soft button label = Back, Done.)

The user tries to install an application and the tags describing the Java application have a syntax error or an invalid format that results in installation failure.

The installation failed. Contact your ISP for help.

The user tries to install an application, the URL to the application is incorrect or inaccessible, and the application cannot be installed.

The URL for “NAMEOFAPP” is invalid. Contact your ISP for help.

The user tries to install an application, the application is not the same size as described in the Descriptor File. The application should be discarded.

“NAMEOFAPP” does not match its description and may be invalid. Contact your ISP for help.

The user is installing an application. During application download, the connection drops, and the application is not loaded onto the device successfully.

The connection dropped and the installation did not complete. Please try installing again. [Soft button label = Install, Back]

The user is installing an application, and the URL specified matches exactly with the one located already on the device.

The JAM should check the version # of both versions and present a decision to the user.

The user tries to run an application and for some reason the application cannot launch (for example, the JAM failed to create a new OS task to run the KVM).

Cannot launch “NAMEOFAPP”. Contact your ISP for help.

The user has been running an application. The application tries to save to the scratchpad and fails.

Cannot save data. Contact your ISP for help.

The user is running an application and it crashes or hangs during execution. NOTE: This is a generic error.

“NAMEOFAPP” has unexpectedly quit.

KVM Porting Guide , CLDC 1.1

Copyright © 2003 Sun Microsystems, Inc. All rights reserved.