Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

## 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 `MIDlet`s 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 `MIDlet`s 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`.
Active | The `MIDlet` is functioning normally. This state is entered: From the Paused after the `MIDlet.startApp()` method returns successfully.
Destroyed | The `MIDlet` has released all of its resources and terminated. This state is entered: When the `MIDlet.destroyApp()` method returns successfully. The `destroyApp()` method shall release all resources held and perform any necessary clean up 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 quiesced.
            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() {
        }
    }

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| MID Profile
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES

Submit a comment or suggestion Version 0.95 of MID Profile Specification
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries. Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road,Palo Alto, California, 94303, U.S.A. All Rights Reserved.