See: Description
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 | Description |
---|---|
MIDletStateChangeException | Deprecated
MIDletStateChangeException is no longer used. |
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.
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.
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.
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:
MIDlet-Dependency-<n>
attribute and the additional dependency names for MEEP 8 optional
standard APIs as defined
here),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.
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.
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.
.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
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:
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:
|
Active |
The application is functioning normally. This state is entered:
|
Destroyed |
The application has released all of its resources and terminated. This state is entered:
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 |
---|
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
|
The application
management software has decided that it is an appropriate time for the
application to run, so it sets it to |
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 |
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
MIDlet.destroyApp
method, which includes making up
resources etc.
InterruptedException
s.
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.
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() { } } |
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.
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.
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.
Copyright (c) 2014, Oracle and/or its affiliates. All rights reserved. Use of this specification is subject to license terms.