Package javax.microedition.midlet

The MIDlet package defines Mobile Information Device Profile applications and the interactions between the application and the environment in which the application runs.

See:
Description

Class Summary

MIDlet

A MIDLet is a MID Profile application.

Exception Summary

MIDletStateChangeException

Signals that a requested MIDlet state change failed.

Package javax.microedition.midlet Description

The MIDlet package defines Mobile Information Device Profile 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.

The MIDlet lifecycle defines the protocol between a MIDlet and its environment through the following:

• A simple well-defined state machine

• A concise definition of the MIDlet's states

• APIs to signal changes between the states

MIDlet Lifecycle Definitions

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

MIDlet States

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 perceived startup latency of an application should be very short.

• It should be possible to put an application into a state where it is not active.

• It should be possible to destroy an application at any time.

The valid states for MIDlets are:

State Name	Description
Paused	The MIDlet is initialized and is quiescent. It should not be holding or using any shared resources. This state is entered: After the MIDlet has been created using new. The public no-argument constructor for the MIDlet 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. From the Active state after the MIDlet.pauseApp() method returns successfully. From the Active state when the MIDlet.notifyPaused() method returns successfully to the MIDlet. From the Active state if startApp throws an MIDletStateChangeException.
Active	The MIDlet is functioning normally. This state is entered: Just prior to calling the MIDlet.startApp() method.
Destroyed	The MIDlet has released all of its resources and terminated. This state is entered: When the MIDlet.destroyApp() method returns except in the case when the unconditional argument is false and a MIDletStateChangeException is thrown. 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 MIDlet must have performed the equivalent of the MIDlet.destroyApp() method before calling MIDlet.notifyDestroyed(). Note: This state is only entered once.

The states and transitions for a MIDlet are:

MIDlet Lifecycle Model

A typical sequence of MIDlet execution is:

Application Management Software	MIDlet
The application management software creates a new instance of a MIDlet.	The default (no argument) constructor for the MIDlet is called; it is in the Paused state.
The application management software has decided that it is an appropriate time for the MIDlet to run, so it calls the MIDlet.startApp method for it to enter the Active state.	The MIDlet acquires any resources it needs and begins to perform its service.
The application management software no longer needs the application be active, so it signals it to stop performing its service by calling the MIDlet.pauseApp method.	The MIDlet stops performing its service and might choose to release some resources it currently holds.
The application management software has determined that the MIDlet is no longer needed, or perhaps needs to make room for a higher priority application in memory, so it signals the MIDlet that it is a candidate to be destroyed by calling the MIDlet.destroyApp method.	If it has been designed to do so, the MIDlet saves state or user preferences and performs clean up.

MIDlet Interface

• pauseApp - the MIDlet should release any temporary resources and become passive

• startApp - the MIDlet should acquire any resources it needs and resume

• destroyApp - the MIDlet should save any state and release all resources

• notifyDestroyed - the MIDlet notifies the application management software that it has cleaned up and is done

• notifyPaused - the MIDlet notifies the application management software that it has paused

• resumeRequest - the MIDlet asks application management software to be started again

• getAppProperty - gets a named property from the MIDlet

Application Implementation Notes

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.

Example MIDlet Application

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, pauseApp, 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();
    }

    /**
     * Pause signals the thread to stop by clearing the thread field.
     * If stopped before done with the iterations it will
     * be restarted from scratch later.
     */
    public void pauseApp() {
        thread = null;
    }

    /**
     * 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 1000 times.
     * Terminate early if the current thread is no longer
     * the thread from the
     */
    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() {
    }
}