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:

MIDlet Lifecycle Definitions

The following definitions are used in the MIDlet lifecycle:

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

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






Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.