javax.microedition.midlet (Java(TM) ME Embedded Profile, Version 1.9950 (b67))

Class Summary
Class	Description
AutoStartPermission	`AutoStartPermission` allows applications in an application suite assume the Auto Start application behavior.
MIDlet	An application must extend this class `MIDlet` (the name comes from MIDP, this application model has been developed for) to allow the application management software to control the application and to be able to retrieve properties from the application descriptor and notify and request state changes.
MIDletIdentity	This class represents the identity of an application.

Exception Summary
Exception Description

MIDletStateChangeException Deprecated
MIDletStateChangeException is no longer used.

Exception Summary
Exception	Description
MIDletStateChangeException	Deprecated `MIDletStateChangeException` is no longer used.

Package javax.microedition.midlet Description

The Application and the environment in which the application runs.

Description

The midlet package defines applications, the interactions between the applications and the environment in which the applications run.

Unless otherwise noted, passing a null argument to a constructor or method in any class or interface in this package MUST cause a java.lang.NullPointerException to be thrown.

Applications

The application model is defined to allow the limited resources of the device to be shared by multiple applications. It defines what an application is, how it is packaged, what runtime environment is available to the application, and how it should behave so that the device can manage its resources.

An application is the entity that is launched by the Application Management Software (AMS). Each application consists of a class that extends the javax.microedition.midlet.MIDlet class and other classes as may be needed by the application. When an application is invoked, a Java Virtual Machine is needed on which the classes can be executed. A new instance of the application is created by the application management software and used to inform the application that it has been started or destroyed.

An application suite is a collection of applications packaged in a JAR as described in Application Suite Packaging. The manifest in the JAR contains attributes that are used during installation and execution of applications.

In case the implementation allows multiple applications to run in concurrence, which is optional to MEEP 8, each application is executed in a separate execution environment that MUST not share any VM resources with any other application. Refer to Application Concurrency for more requirements.

An application MUST use only functionality specified by the requested specification, the requested configuration, optional packages, and Licensee Open Classes as it is developed, tested, deployed, and run.

Sharing of data and other information between applications is controlled by the individual APIs and their implementations. For example, the Record Management System API specifies the methods that are used when the record stores associated with an application suite are shared among applications.

Application Suite Security

Previous profile version specifications constrained each application suite to operate in a sandbox wherein all of the APIs available to the applications would prevent access to sensitive functions of the device. That sandbox concept is used in this specification and all untrusted application suites are subject to its limitations. Every implementation of this specification MUST support running untrusted application suites.

Later profile versions have introduced the concept of trusted applications (being optional to MEEP 8) that may be permitted to use APIs that are considered sensitive and are restricted. If and when a device determines that an application suite can be trusted the device allows access as indicated by the policy. "Security for Applications" describes the concepts and capabilities of untrusted and trusted applications.

One aspect of the application security model is that each application suite runs in isolation, and cannot gain access to the variables, data, memory, etc. of an application in a different application suite. This is important because the integrity and privacy of the application data must be maintained and protected from rogue applications either attempting to ascertain secret information or being destructive. With the LIBlet development model, where the LIBlet code may be developed and deployed independently (any by independent entities) from the application code, yet where the two are bound together to run in one execution environment, the security risks are significant. A LIBlet can gain access to application private data, can modify this data freely, and can even inherit the security privileges granted to the application.

By itself, a LIBlet, unlike an application, is not associated with a Client.
Permissions while executing LIBlet code are the permissions associated with the application's execution environment.

Execution Environment

This specification defines the execution environment provided to applications. Invocation of applications has to be supported. The way how the start of an application is triggered, is implementation dependent. If the start of an application has been triggered, the device MUST invoke the application with the execution environment as described here.

Each application executed receives its own execution environment. The loading of classes, class state, static variable data, and static initializers is managed per execution environment. The application management software initiates the applications and makes the following available to the application:

Classes and native code that implement the underlying configuration including a Java Virtual Machine
Classes and native code that implement the MEEP 8 runtime
Classes from the application JAR for execution
Classes from each LIBlet required by the application
Services bound to the application from the LIBlet(s) that provides the service.
Files from the application JAR as resources; class files SHOULD be available
Files from each LIBlet required by the application as resources; class files SHOULD be available
Contents of the application descriptor, when it is present
Any other APIs available on the device such as implementations of additional Optional Packages, Licensee Open Classes, etc.

The underlying configuration and Java Virtual Machine provide multi-threading, locking and synchronization, the execution of byte codes, dispatching of methods, etc. A single VM is the scope of all policy, naming, and resource management. If a device supports multiple VMs, each may have its own scope, naming, and resource management policies. Applications MUST NOT contain classes that are in packages defined by the underlying configuration, MEEP 8, or optional packages.

The implementation MUST ensure that the application programmer cannot override, modify, or add any classes to these system packages.

A single JAR file contains all the classes of the application. The application may load and invoke methods from:

any class in the application JAR,
any class in each LIBlet the application specified a dependency on,
any class in each LIBlet that provides a service and is bound to the application as a result of an application dependency on the service,
any class in MEEP 8, as far as the respective package - if optional - is part of the implementation (applications are recommended to require optional MEEP 8 APIs they are going to use, using the MIDlet-Dependency-<n> attribute and the additional dependency names for MEEP 8 optional standard APIs as defined here),
any class in the underlying configuration, and
any class in optional packages(applications are recommended to require optional packages they are going to use, using the MIDlet-Dependency-<n> attribute and the dependency names for standard APIs as defined here).

All of the classes, class state, static variable data and static initializers within these scopes are unique in the execution environment provided by the AMS for the application. All states accessible via those classes are available to any Java class running on behalf of the application.

When an application that depends on one or more LIBlets is launched, all the code of the application and LIBlets is executed in an execution environment, indistinguishable from a standalone application packaging all the application and LIBlet code in a single application JAR. That is, the application and LIBlets it depends on are executed on the same Java heap, and follow the same security policy/manager associated with the application's Client and its associated Security Protection Domain.

The act of loading an application with all the associated LIBlets it declares dependencies on directly or indirectly into a single execution environment is called binding. Once bound, the LIBlet code is executed within the application execution environment as if it were packaged into the application JAR. Thus, although a LIBlet bound to different applications may access shared persistent resources through RMS or other persistent storage, the execution of its code inside different bindings will be completely isolated from each other.

The class files of the application or dependent LIBlets MUST be available for execution and SHOULD be available as resources. The implementation MAY store and interpret the contents of the JAR in any manner suitable.

The files from the JAR that are not Java class files are made available via java.lang.Class.getResourceAsStream, for example, the contents of the manifest file are made available in this manner.

The contents of the application descriptor file, when it is present, are made available via the javax.microedition.midlet.MIDlet.getAppProperty(String key) method. This method cannot be used to retrieve contents of the LIBlet descriptor file. The javax.microedition.midlet.MIDlet.getAppProperty(String name, String vendor, String attributeName, String attributeDelimiter) method is used to retrieve and at the same time parse application property values from the application descriptor and the manifest of the application or bound LIBlets. This method retrieves a property value for a specific LIBlet or application, so the same property name is allowed to be used by multiple LIBlets without ambiguity in the binding.

Auto Start Applications

Applications that are auto-started by the device on power-up and restarted (on exit of the application) are called "Auto Start Applications". The AMS MUST attempt to start the application on power-up; however, the system MAY fail start such applications due to resource constraints at power-up. In addition, the AMS MUST attempt to restart Auto Start Applications on exit/termination of the application; however, the system may fail to restart the application due to resource limitations or other system failures (like failing to open a network connection, inaccessibility of a resource etc.). In both these failure cases, the AMS MUST make at least one attempt to restart the application.

An application developer marks an application as Auto Start using the MIDlet-<n>-Type attribute. If the attribute value includes autostart, the application assumes the Auto Start Application behavior. The application must have the javax.microedition.midlet.AutoStartPermission for an application to assume this behavior. Otherwise the installation of an Auto Start Application MUST fail. Pls. be aware that the application can still lose its Auto Start Permission after having become installed, e.g. by blacklisting.

Version Numbering

Version numbers have the format Major.Minor[.Micro] (X.X[.X]), where the .Micro portion MAY be omitted. (If the .Micro portion is omitted, then it defaults to zero). In addition, each portion of the version number is allowed a maximum of two decimal digits (i.e., 0-99). Version numbers are described in [JPVS].

For example, 1.0.0 can be used to specify the first version of an application suite. 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.

Application Classes

All Java classes needed by the application are be placed in the JAR using the standard structure, based on mapping the fully qualified class names to directory and file names. Each period is converted to a forward slash ( / ) and the .class extension is appended. For example, a class com.oracle.microedition.Test would be placed in the JAR with the name com/oracle/microedition/Test.class.

Application Lifecycle

Each application MUST extend the MIDlet class. The application class allows for the orderly starting, stopping, and cleanup of the application. The application can request the arguments from the application descriptor to communicate with the application management software. If an application class identified by MIDlet-<n> has a public static void main(String[]) method, it MUST be ignored by the application management software. Unlike other Java application environments, applications of MEEP 8 do not use the

public static
 void main(String[])

method as their entry point. Instead, the methods of the initial application class are called as defined by the application lifecycle model.

When an application suite is installed on a device, its classes, resource files, arguments, and persistent storage are kept on the device and ready for use. The application(s) are available via the device's application management software.

When the application is run, an instance of the application's primary class is created using its public no-argument constructor, and the methods of the application are called to sequence the application through its various states. The application can either request changes in state or notify the application management software of state changes via the application methods. When the application is finished or terminated by the application management software, it is destroyed, and the resources it used can be reclaimed, including any objects it created and its classes. The application MUST NOT call System.exit , which would throw a SecurityException when called by an application.

The normal states of Java classes are not affected by these classes as they are loaded. Referring to any class will cause it to be loaded, and the normal static initialization will occur.

The application lifecycle defines the protocol between an application and its environment through the following:

A simple well-defined state machine
A concise definition of the application's states
APIs to signal changes between the states

Application Lifecycle Definitions

The following definitions are used in the application lifecycle:

application management software - a part of the device's software operating environment that manages applications. It maintains the application's state and directs the application through state changes.
Application - an instance of javax.microedition.midlet.MIDlet on the device. The application can signal the application management software about whether it wants to run or has completed. An application has no knowledge of other applications through the application API.
Application States - the states an application can have are defined by the transitions allowable through the application interface. More specific application states are known only to the application.

Application States

The application state machine is designed to ensure that the behavior of an application is consistent and as close as possible to what device manufacturers and users expect; specifically:

The perceived startup latency of an application SHOULD be very short.
It SHOULD be possible to destroy an application at any time.

For this specification MIDlet.pauseApp is deprecated and will not be called by the AMS after it enters the Active state.

The valid states for applications are defined in the table below.

Table 15-1 : Application States
State Name	Description
Paused	The application is initialized and is quiescent. It SHOULD not be holding or using any shared resources. This state is entered: After the application has been created using `new`. The public no-argument constructor for the application is called and returns without throwing an exception. The application typically does little or no initialization in this step. If an exception occurs, the application immediately enters the `Destroyed` state and is discarded.
Active	The application is functioning normally. This state is entered: Just prior to the AMS calling the `MIDlet.startApp()` method.
Destroyed	The application has released all of its resources and terminated. This state is entered: When the AMS called the `MIDlet.destroyApp()` method and returns. The `destroyApp()` method shall release all resources held and perform any necessary cleanup so it may be garbage collected. When the `MIDlet.notifyDestroyed()` method returns successfully to the application. The application must have performed the equivalent of the `MIDlet.destroyApp()` method before calling `MIDlet.notifyDestroyed()`. Note: This state is only entered once.

Figure 15-1 below illustrates the state transitions and requirements related to the Application lifecycle. The deprecated parts of the spec are not considered in this picture.

Figure 15-1 : Application Lifecycle State Diagram

Application Lifecycle Model

A typical sequence of application execution is presented in the following table:

Table 15-2 : Application Lifecycle Sequence
Application Management Software	application
The application management software creates a new instance of an application.	The default (no argument) constructor for the application is called; it is in the `Paused` state.
The application management software has decided that it is an appropriate time for the application to run, so it sets it to `Active` state and then calls the `MIDlet.startApp` method.	The application acquires any resources it needs and begins to perform its service.
The application management software has determined that the application is no longer needed, or perhaps needs to make room for a higher priority application in memory, so it signals the application that it is a candidate to be destroyed by calling the `MIDlet.destroyApp` method.	If it has been designed to do so, the application saves state and performs clean up.

For the AMS, there are two ways to delete an application

The normal, or "soft" one can be used in most cases, so if an application ends normally as it is done, it will be destroyed by the AMS for priority reasons or for technical reasons (e.g. if it necessary to end the application because an update should take place). This normal way is done as described above just by calling the MIDlet.destroyApp method, which includes making up resources etc.
The rigorous or "hard" one has to be used in cases when the application has to be stopped for security reasons, e.g. if the application itself or its Client has been blacklisted. In this cases everything has to be done as described for the "soft" variant, but additionally it has to be guaranteed that all threads of the application have been killed indeed, even if they try to avoid this by catching InterruptedExceptions. The safest way to do this is to kill the process of the instance of the virtual machine that runs this application.

There are several places in the spec indicating explicitly whether "soft" or "hard" variant of application destruction is appropriate, respectively.

Application Implementation Notes

The application SHOULD take measures to avoid race conditions in the execution of the application methods. Each method may need to synchronize itself with the other methods avoid concurrency problems during state changes.

Example Application

The example uses the application lifecycle to do a simple measurement of the speed of the Java Virtual Machine.

 import javax.microedition.midlet.*;

 // An example application runs a simple timing test
 // When it is started by the application management software it will create
 // a separate thread to do the test.
 // When it finishes it will notify the application management software it is
 // done.
 // Refer to the startApp and destroyApp methods so see how it handles each
 //requested transition.
 
 public class MethodTimes extends MIDlet implements Runnable {
      // The state for the timing thread.
      Thread thread;

      // Start creates the thread to do the timing.
      // It should return immediately to keep the dispatcher from hanging.
      public void startApp() {
          thread = new Thread(this);
          thread.start();
      }
 
      // Destroy must cleanup everything. The thread is signaled
      // to stop and no result is produced.
      public void destroyApp(boolean unconditional) {
          thread = null;
      }

      // Run the timing test, measure how long it takes to
      // call a empty method 1000000 times.
      // Terminate early if the current thread should no longer be running.
      public void run() {
          Thread curr = Thread.currentThread();

          // Remember which thread is current
          long start = System.currentTimeMillis();
          for (int i = 0; i < 1000000 && thread == curr; i++) {
              empty();
          }

          long end = System.currentTimeMillis();
 
          // Check if timing was aborted, if so just exit
          // The rest of the application has already become quiescent.
          if (thread != curr) {
              return;
          }

          long millis = end - start;
 
          // Reporting the elapsed time is outside the scope of this example.
          // All done cleanup and quit
          destroyApp(true);
          notifyDestroyed();
      }

      // An Empty method.
      void empty() { }
 }

System Functions

This specification requires a set of modified behaviors for certain system functions of underlying configurations related to the exit of applications.

System.exit

The behavior of java.lang.System#exit MUST throw a java.lang.SecurityException when invoked by an application. The only way an application can indicate that it is complete is by calling MIDlet.notifyDestroyed.

Runtime.exit

The behavior of java.lang.Runtime#exit MUST throw a java.lang.SecurityException when invoked by an application. The only way an application can indicate that it is complete is by calling MIDlet.notifyDestroyed.

Application Resource Files

Application resource files are accessed using getResourceAsStream(String name) in java.lang.Class. getResourceAsStream is used to allow resource files to be retrieved from application and LIBlet JAR files.

Resource names refer to the contents of a application or LIBlet JAR. Absolute pathnames, beginning with "/" are fully qualified file names within the JAR. The resource file is loaded from the same context as the Class instance it is called upon. Only a single JAR is searched for the resource. For example, if called on a class loaded from the application, the resource will be retrieved from the application suite JAR.

Relative pathnames, not beginning with "/" are relative to the class upon which getResourceAsStream is called. Relative names are converted to absolute by prepending a "/" followed by the fully qualified package with "." characters converted to "/" and a separator of "/". The resulting string is reduced to canonical form by applying as many times as possible the following:

All occurrences of "/./" are replaced with "/".
All occurrences of "/segment/../" are replaced with "/" where segment does not contain "/".

The canonical resource name is the absolute pathname of the resource within the JAR.

In no case can the path extend outside the JAR, and resources outside the JAR MUST NOT be accessible. For example, using "../../" does NOT point outside the JAR. If there are any remaining "." or ".." characters they are treated literally in locating the resource. No resource can exist with that name so null is returned from Class.getResourceAsStream. Also, devices SHOULD NOT allow class files to be read from the JAR as resources, but all other files MUST be accessible.

Since:: MEEP-8.0.0