MEEP 1.9950 (b67)
JCP EG draft 10-February-2014 08:45

Package javax.microedition.midlet

The Application and the environment in which the application runs.

See: Description

Package javax.microedition.midlet Description

The Application and the environment in which the application runs.


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.


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.

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:

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:

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 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:

Application Lifecycle Definitions

The following definitions are used in the application lifecycle:

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:

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



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.


The application is functioning normally. This state is entered:

  • Just prior to the AMS calling the MIDlet.startApp() method.


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 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


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

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);
      // 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++) {

          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) {

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

      // 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.


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.


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:

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.

MEEP 1.9950 (b67)
10-February-2014 08:45

Copyright (c) 2014, Oracle and/or its affiliates. All Rights Reserved. Use of this specification is subject to license terms.