Figure 15-2 : Idle Screen MIDlet Example
|
MIDP3.0 | |||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||
See:
Description
| Class Summary | |
|---|---|
| ActionsDeniedPermission | ActionsDeniedPermission is required by MIDlets that want to restrict the actions allowed by an user on a MIDlet or a MIDlet Suite. |
| AutoStartPermission | AutoStartPermission allows MIDlets in a MIDlet suite to assume the Auto Start MIDlet behavior. |
| MIDlet | A MIDlet is a Mobile Information Device Profile application. |
| MIDletIdentity | This class represents the identity of a MIDlet. |
| Exception Summary | |
|---|---|
| MIDletStateChangeException | Deprecated. MIDletStateChangeException is no longer used. |
The MIDlet package defines Mobile Information Device Profile (MIDP)
applications and the interactions between the application and the
environment in which the application runs. An application of the Mobile
Information Device Profile is a MIDlet.
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 MIDP defines an application model to allow the limited resources of the device to be shared by multiple MIDP applications, or MIDlets. It defines what a MIDlet is, how it is packaged, what execution environment is available to the MIDlet, and how it should behave so that the device can manage its resources. The application model defines how multiple MIDlets forming a suite can be packaged together.
A MIDlet is the entity that is launched by the
Application Management Software (AMS). Each MIDlet consists of a class
that extends the javax.microedition.midlet.MIDlet
class and other classes as may be needed by the MIDlet.
When a MIDlet is invoked, a Java
Virtual Machine is needed on which the classes can be executed. A new
instance of the MIDlet is created by the application management
software and used to inform the MIDlet that it has been started or
destroyed.
A MIDlet suite is a collection of MIDlets packaged in a JAR as described in MIDlet Suite Packaging. The manifest in the JAR contains attributes that are used during installation and execution of MIDlets.
Each MIDlet is executed in a separate execution environment that MUST not share any VM resources with any other MIDlet. All of the MIDlets in a MIDlet suite are subject to a single set of policies and controls. Refer to MIDP 3.0 MIDlet Concurrency for more requirements.
A MIDP application MUST use only functionality specified by the MIDP 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 MIDlets 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 a MIDlet suite are shared among MIDlets.
The MIDP 1.0 specification constrained each MIDlet suite to operate in a sandbox wherein all of the APIs available to the MIDlets would prevent access to sensitive functions of the device. That sandbox concept is used in this specification and all untrusted MIDlet suites are subject to its limitations. Every implementation of this specification MUST support running untrusted MIDlet suites.
MIDP 2.0 introduced the concept of trusted applications that may be permitted to use APIs that are considered sensitive and are restricted. If and when a device determines that a MIDlet suite can be trusted the device allows access as indicated by the policy. Security for MIDP Applications section describes the concepts and capabilities of untrusted and trusted applications.
One aspect of the MIDlet security model is that each MIDlet suite runs in isolation, and cannot gain access to the variables, data, memory, etc. of a MIDlet in a different MIDlet. This is important because the integrity and privacy of the MIDlet data must be maintained and protected from rogue MIDlets 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 MIDlet 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 MIDlet private data, can modify this data freely, and can even inherit the security privileges granted to the MIDlet.
The MIDP defines the execution environment provided to MIDlets. Each MIDlet 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 MIDlet:
The CDC or CLDC and Java Virtual Machine provides 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. MIDlet suites MUST NOT contain classes that are in packages defined by the CDC, CLDC, MIDP, or optional packages.
The behavior of MIDlets in MIDP 3.0 is defined for two different Java ME
configurations: CLDC 1.1.1 and CDC.
Access to the functionality defined by configurations is controlled by the JAD
attribute MicroEdition-Configuration. A MIDlet may choose
the appropriate execution environment using the following attribute
value definitions:
If the value of the MicroEdition-Configuration
attribute in the JAD file of the MIDlet suite is "CLDC-1.1.1",
then execution environment MUST conform to the
CLDC Specification, version 1.1.1 or higher and
the MIDlet SHALL have access to all of its functionality
(within the restrictions imposed by the security policy).
All systems compliant with the MIDP3 Specification MUST provide support
for the "CLDC-1.1.1" value of the MicroEdition-Configuration
attribute, and the behavior associated with this attribute value.
If the value of the MicroEdition-Configuration
attribute in the JAD file of the MIDlet suite is "CDC-1.1",
then execution environment MUST conform to the
CDC Specification, version requested or higher and
the MIDlet SHALL have access to all of its functionality
(within the restrictions imposed by the security policy).
In the CDC environment, the sandbox security requirements defined in the CLDC Specification are superseded by the more fine-grained security model offered by the CDC Specification. Access to CDC-specific functionality is controlled by the security policy.
Support for the "CDC-1.1" values of the
MicroEdition-Configuration attribute and the associated behavior
is OPTIONAL.
If the system cannot honor a MIDlet's request for a particular execution environment, then the installation of the MIDlet MUST fail. Status Code 908 (Incompatible Configuration or Profile) MUST be used when reporting the installation failure.
The MIDP implementation provides the classes that implement the MIDP APIs. 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 MIDlet. The MIDlet may load and invoke methods from :
When a MIDlet that depends on one or more LIBlets is launched, all the code of the MIDlet and LIBlets is executed in an execution environment, indistinguishable from a standalone MIDlet packaging all the MIDlet and LIBlet code in a single MIDlet JAR. That is, the MIDlet and LIBlets it depends on are executed on the same Java heap, in the same Protection Domain, and with the same security policy/manager.
The act of loading a MIDlet 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 MIDlet execution environment as if it were packaged into the MIDlet JAR. Thus, although a LIBlet bound to different MIDlets 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 MIDlet 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 MIDlet descriptor file, when it is
present, are made available via the
javax.microedition.midlet.MIDlet.getAppProperty(String key)
method.
This method can not 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 MIDlet or bound
LIBlets. This method retrieves a property value for a specific LIBlet or
MIDlet, so the same property name is allowed to be used by multiple LIBlets
without ambiguity in the binding.
An application MAY define the minimum and/or maximum screen
sizes that it is designed to work with using the
MIDlet-Minimum-Canvas-Size and/or
MIDlet-Maximum-Canvas-Size attributes.
If either of the MIDlet-Minimum-Canvas-Size
or MIDlet-Maximum-Canvas-Size attributes are specified,
and the primary display of the device is incapable of meeting the specified
size requirements, then the MIDlet suite installation MUST fail
(see Installation for more details).
On devices that support multiple orientations, the MIDlet suite MAY be installed if the application's size requirements can be met using one or more of its available orientations. Implementations SHOULD select a display and orientation that meets the application's display requirements.
A screen saver MIDlet is an application that can be launched automatically when the device has been in the idle state for a predetermined amount of time. The idle state is typically a state in which the device is not actively being used; for example, if there is no call ongoing and the user has not pressed any keys. The precise definition of the idle state depends on the device implementation. The screen saver keeps running until it is deactivated by an external event, such as a user action or by a platform dependent timeout.
Screen saver MIDlets are identified with the Application Attribute
MIDlet-<n>-Type. The type
for identifying a screen saver MIDlet is screensaver.
In order to indicate a screen saver MIDlet in the MIDlet suite, either
the JAD file or the JAR manifest MUST have a
MIDlet-<n>-Type: screensaver
entry.
For example :
MIDlet-1: Cool3DSaver, /icon.png, ScreenSaverMIDlet
MIDlet-1-Type: screensaver
|
MIDlet suites that contain a screen saver MIDlet are provisioned in the same way as all other MIDlet suites. The following additional requirements apply :
In order to receive events corresponding to activation and deactivation
of the screen saver, a MIDlet must register a
EventDataListener with
EventManager.addEventListener. A screen saver MIDlet should register such a listener
immediately after it has been started, as soon as it is ready to act as a screen saver.
The event that corresponds to changes in screen saver state is
SCREENSAVER_MODE.
When a screen saver is activated or deactivated, the
SCREENSAVER_MODE
event MUST be sent to all registered screen saver applications.
A MIDlet can then determine if it is the currently selected screen saver by querying
MIDlet.isSelectedScreenSaver.
A MIDlet can also query the state of the
SCREENSAVER_MODE event
with the
EventManager.getCurrent(event)
method. If the currently selected screen saver MIDlet is not running when the screen saver
is activated, the AMS MUST start the currently selected screen saver MIDlet.
When a screen saver MIDlet is not running as the active screen saver, it
runs like any other MIDlet. This provides the opportunity to allow
configuration and preview of the screen saver. A screen saver MIDlet
may also add content to the idle screen with
IdleItem.
In this case it MUST also announce itself as an active idle MIDlet through the
MIDlet-<n>-Type
attribute with value idlescreen. More information on the idle screen can be
found javax.microedition.lcdui package.
Once in the active mode, a screen saver MIDlet MAY be deactivated by a key
event. A device MAY have one or more keys that do not cause
the screen saver MIDlet to be terminated in the active mode. These keys
can be, for example, used to turn on a dimmed screen backlight. When the
screen saver MIDlet is deactivated, the SCREENSAVER_MODE event
with value SCREENSAVER_MODE_DEACTIVATED is sent to all registered applications.
If the screen saver MIDlet uses functionality that is protected with the security policy, the security prompts shown to the user when screen saver is activated are problematic. The security prompts SHOULD NOT deactivate the screen saver. However this functionality may be impossible or at best difficult to implement. Therefore sequence of events that the screen saver MIDlet MAY expect are as follows :
SCREENSAVER_MODE event with value SCREENSAVER_MODE_ACTIVATED.
Display capabilities are changed to indicate no further
user input events will be delivered to the screen saver MIDlet.
Display capabilities are
changed to deliver user input and a SCREENSAVER_MODE event
with value SCREENSAVER_MODE_DEACTIVATED is sent to the screen saver MIDlet.
SCREENSAVER_MODE event with
value SCREENSAVER_MODE_ACTIVATED is sent to the screen saver MIDlet. The
MIDlet's Display capabilities are changed as appropriate.
An implementation MAY also use system screens to temporarily obscure a screen saver display.
The screen saver MIDlet MAY also be deactivated by implementation specific actions or timeouts; these may include :
MIDlet.notifyDestroyed()
methodFrom the security point of view, a screen saver MIDlet is handled as any other MIDlet. As such, if the screen saver MIDlet satisfies security requirements for specific APIs, those APIs MUST be accessible to the MIDlet.
Most mobile platforms feature some concept of an idle screen - a default
display which is presented to the user when no other activity is taking place
on the device. Typically the idle screen is not empty but features UI
components which provide status information about the device (signal strength,
battery levels), information about services on the device (number of unread
emails, calendar event information, headlines from a news feed) and shortcuts
or controls for popular applications (music players controls).
MIDlets can offer the same capability by setting
the IdleItem for a Display.
Figure 15-2 below shows how idle screen
MIDlets can be placed into a device's idle screen.
|
Figure 15-2 : Idle Screen MIDlet Example |
|---|
|
|
A MIDlet that wants to add content to the idle screen is identified with
an application attribute
MIDlet-<n>-Type with the value idlescreen.
For example:
MIDlet-1: NewsTicker, /icon.png, NewsTickerMIDlet
MIDlet-1-Type: idlescreen
|
More than one MIDlet on the device can add content to the idle screen.
MIDlets that are auto-started by the device on power-up and restarted (on exit of the MIDlet) are called "Auto Start MIDlets". The AMS MUST attempt to start the MIDlet on power-up; however, the system MAY fail start such MIDlets due to resource constraints at power-up. In addition, the AMS MUST attempt to restart Auto Start MIDlets on exit/termination of the MIDlet; however, the system may fail to restart the MIDlet due to resource limitations or other system failures. In both these failure cases, the AMS MUST make at least one attempt to restart the MIDlet.
A MIDlet developer marks a MIDlet as Auto Start using the
MIDlet-<n>-Type attribute.
If the attribute value includes autostart,
the MIDlet assumes the Auto Start MIDlet behavior. The MIDlet suite
must have the javax.microedition.midlet.AutoStartPermission for a
MIDlet to assume this behavior.
A MIDlet developer may want to restrict the actions allowed on a
MIDlet by the user. User actions on a MIDlet are controlled using
the MIDlet-<n>-UserDenied
attribute.
Actions include the ability for a user to launch a MIDlet and the ability
to stop a running MIDlet from an AMS screen.
User actions on a MIDlet Suite are controlled using the
MIDlet-UserDenied
attribute. User actions on a Suite include the ability to update or delete
a MIDlet suite.
MIDlet Suites that declare attributes to control user action require
the ActionsDeniedPermission
Permission. If any of the user actions attributes are present and this Permission is
not granted, the installation of the MIDlet Suite MUST fail.
If the MIDlet-<n>
attribute is not present in the JAD/Manifest, no user actions are denied on this MIDlet. If the
-UserDeniedMIDlet-UserDenied
attribute is not present in the JAD/Manifest, none of allowed user actions
are denied on the MIDlet Suite.
A MIDlet Suite that cannot be deleted by the user is a Persistent MIDlet
Suite. A MIDlet developer marks a suite as Persistent using the
MIDlet-UserDenied attribute. If the attribute value
includes delete, the suite is a Persistent MIDlet Suite as the user is denied the ability
to delete the MIDlet Suite. When a Persistent MIDlet suite is being installed,
the user MUST be prompted to confirm that the MIDlet Suite installation can proceed, and that
the user will not be able to delete the MIDlet suite after installation.
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 a MIDlet 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.
A missing MIDlet-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 MIDlet suite.
All Java classes needed by the MIDlet 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.sun.microedition.Test
would be placed in the JAR with the name com/sun/microedition/Test.class.
Each MIDlet MUST extend the MIDlet
class. The MIDlet class allows for the
orderly starting, stopping, and cleanup of the MIDlet. The MIDlet can
request the arguments from the application descriptor to communicate
with the application management software.
If a MIDlet 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,
MIDP does not use the public static void main(String[]) method
as the entry point of the application. Instead, the methods of the initial
MIDlet class are called as defined by the MIDlet lifecycle model.
When a MIDlet suite is installed on a device, its classes, resource files, arguments, and persistent storage are kept on the device and ready for use. The MIDlet(s) are available to the user via the device's application management software.
When the MIDlet is run, an instance of the MIDlet's primary
class is created using its public no-argument constructor, and the
methods of the MIDlet are called to sequence
the MIDlet through its various states. The MIDlet can either request
changes in state or notify the application management software of state
changes via the MIDlet methods. When the
MIDlet 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 MIDlet MUST NOT
call System.exit , which will throw a SecurityException
when called by a MIDlet.
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 MIDlet lifecycle defines the protocol between a
MIDlet and its environment through the following:
The following definitions are used in the MIDlet
lifecycle:
application management software - a part of the
device's software operating environment that manages
MIDlets. It maintains the MIDlet state and directs
the MIDlet through state changes.
MIDlet - a MIDP application on the device.
The MIDlet can signal the application management
software about whether is it wants to run or has completed. A
MIDlet has no knowledge of other MIDlets
through the MIDlet API.
MIDlet States - the states a MIDlet
can have are defined by the transitions allowable through the
MIDlet interface. More specific application states
are known only to the application.
The MIDlet state machine is designed to ensure that the
behavior of an application is consistent and as close as possible to
what device manufactures and users expect; specifically :
The Paused state described below is included for backward
compatibility with previous versions. For MIDP 3.0 MIDlet suites, the
AMS does not call MIDlet.pauseApp after it enters the
Active state.
The valid states for MIDlets are defined in Table 15-1 below.
Table 15-1 : MIDlet States |
|
|---|---|
State Name |
Description |
|
Paused |
The
|
|
Active |
The
|
|
Destroyed |
The
Note: This state is only entered once. |
Figure 15-1 below illustrates the state transitions and requirements related to the MIDlet lifecycle.
|
Figure 15-1 : MIDlet Lifecycle State Diagram |
|---|
|
A typical sequence of MIDlet execution is presented in
Table 15-2 :
Table 15-2 : MIDlet Lifecycle Sequence |
|
|---|---|
Application Management Software |
MIDlet |
|
The application management software creates a new instance
of a |
The default (no argument) constructor for the |
|
The application management software has decided that it
is an appropriate time for the |
The |
|
The application management software has determined that the
|
If it has been designed to do so, the |
The application SHOULD take measures to avoid race
conditions in the execution of the MIDlet methods. Each
method may need to synchronize itself with the other methods avoid
concurrency problems during state changes.
The example uses the MIDlet lifecycle to do a simple measurement of the speed of the Java Virtual Machine.
import javax.microedition.midlet.*;
/**
* An example MIDlet 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() { }
}
An application may specify a splash screen in its manifest (see Packaging section for more details).
The splash screen is shown only when the application is started by the user. The splash screen is shown on the primary Display.
The implementation should show the splash screen as soon as possible after the MIDlet is launched, but it must guarantee that it is visible to the user by the time the MIDlet's startApp method is called.
Once shown, the splash screen will remain visible until one of the following events occurs:
|
MIDP3.0 | |||||||||
| PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES | |||||||||