MIDletState.javaAPI DocJ2ME MIDP 2.018578Thu Nov 07 12:02:22 GMT 2002com.sun.midp.midlet


public abstract class MIDletState extends Object
MIDletState holds the current state of the MIDlet and forwards updates to it. It holds the reference to the MIDlet itself and the Display object used to communicate with the MIDlet's Display.

When each MIDlet is constructed it creates a MIDletProxy object (subclassed from MIDletState). The MIDletProxy is in the javax.microedition.midlet package so that it can invoke the control methods of MIDlets (startApp, destroyApp, pauseApp). Invocations from the Scheduler to the MIDlet are forwarded using corresponding methods.

All state changes are synchronized using the mutex retrieved from the Scheduler. NotifyPaused, ResumeRequest, and NotifyDestroyed methods invoked on the MIDlet cause the appropriate state change. The Scheduler is aware of changes by waiting on the mutex.

The getAppProperty method from the MIDlet is sent here and relayed to the Scheduler.

Fields Summary
static final int
State of the MIDlet is Paused; it should be quiescent
static final int
State of the MIDlet is Active
static final int
State of the MIDlet is Paused but Resume has been requested
static final int
State of the MIDlet when resumed by the display manager
static final int
State of the MIDlet when paused by the display manager
static final int
State of the MIDlet with destroy pending
static final int
State of the MIDlet is Destroyed
private static
This class has a different security domain than the application.
private static Object
Lock for creating a MIDlet.
private static boolean
Lock for creating a MIDlet, default to false.
private int
The applications current state.
private Object
The lock for changes to the state.
private Scheduler
The controller of MIDlets.
protected javax.microedition.midlet.MIDlet
The MIDlet for which this is the state.
protected javax.microedition.lcdui.Display
The Display for this MIDlet.
protected com.sun.midp.lcdui.DisplayManager
The controller of Displays.
Constructors Summary
protected MIDletState(javax.microedition.midlet.MIDlet m)
Protected constructor for subclasses. If any MIDlet is constructed it should be registered with Scheduler. That allows them to be managed even if an application creates one itself.

m the MIDlet this is the state for; Must not be null.
SecurityException if is constructor is not being called in the context of createMIDlet and the suite does not have the AMS permission.

        DisplayAccess accessor;

	midlet = m;
	state = PAUSED_RESUME;	// So it will be made active soon
	scheduler = Scheduler.getScheduler();
	mutex = scheduler.getMutex();

        synchronized (createMIDletLock) {
            if (!allowedToCreateMIDlet) {
                MIDletSuite suite = scheduler.getMIDletSuite();

                if (suite != null) {

	// Force the creation of the Display
        displayManager = DisplayManagerFactory.getDisplayManager();
        accessor = displayManager.createDisplay(classSecurityToken, midlet);
        display = accessor.getDisplay();

        if (scheduler.getMIDletSuite().isTrusted()) {
            accessor.setTrustedIcon(classSecurityToken, true);
Methods Summary
public intcheckPermission(java.lang.String permission)
Get the status of the specified permission. If no API on the device defines the specific permission requested then it must be reported as denied. If the status of the permission is not known because it might require a user interaction then it should be reported as unknown.

permission to check if denied, allowed, or unknown.
0 if the permission is denied; 1 if the permission is allowed; -1 if the status is unknown

        return getMIDletSuite().checkPermission(permission);
static javax.microedition.midlet.MIDletcreateMIDlet(java.lang.String classname)
Create a MIDlet without throwing a security exception.

classname name of MIDlet class
newly created MIDlet
ClassNotFoundException is thrown, if the MIDlet main class is not found
InstantiationException is thrown, if the MIDlet can not be created
IllegalAccessException is thrown, if the MIDlet is not permitted to perform a specific operation

        Class midletClass;
        Object midlet;

        synchronized (createMIDletLock) {
            try {
                allowedToCreateMIDlet = true;

                midletClass = Class.forName(classname);
                midlet = midletClass.newInstance();
                if (midlet instanceof MIDlet) {
                    return (MIDlet)midlet;

                throw new InstantiationException("Class not a MIDlet");
            } finally {
                allowedToCreateMIDlet = false;
protected abstract voiddestroyApp(boolean unconditional)
Signals the MIDlet to terminate and enter the DESTROYED state. In the destroyed state the MIDlet must release all resources and save any persistent state. This method may be called from the PAUSED or ACTIVE states.

MIDlets should perform any operations required before being terminated, such as releasing resources or saving preferences or state.

NOTE: The MIDlet can request that it not enter the DESTROYED state by throwing an MIDletStateChangeException. This is only a valid response if the unconditional flag is set to false. If it is true the MIDlet is assumed to be in the DESTROYED state regardless of how this method terminates. If it is not an unconditional request, the MIDlet can signify that it wishes to stay in its current state by throwing the MIDletStateChangeException. This request may be honored and the destroy() method called again at a later time.

unconditional If true when this method is called, the MIDlet must cleanup and release all resources. If false the MIDlet may throw MIDletStateChangeException to indicate it does not want to be destroyed at this time.
MIDletStateChangeException is thrown if the MIDlet wishes to continue to execute (Not enter the DESTROYED state). This exception is ignored if unconditional is equal to true.

public javax.microedition.lcdui.DisplaygetDisplay()
Get the Display for this MIDlet.

the Display of this MIDlet.

	return display;
public javax.microedition.midlet.MIDletgetMIDlet()
Get the MIDlet for which this holds the state.

the MIDlet; will not be null.

	return midlet;
public final MIDletSuitegetMIDletSuite()
Provides a MIDlet with a mechanism to retrieve MIDletSuite for this MIDlet.

MIDletSuite for this MIDlet

	return scheduler.getMIDletSuite();
Get the state.

current state of the MIDlet.

	synchronized (mutex) {
	    return state;
public static voidinitSecurityToken( token)
Initializes the security token for this class, so it can perform actions that a normal MIDlet Suite cannot.

token security token for this class

        if (classSecurityToken != null) {

        classSecurityToken = token;
public final voidnotifyDestroyed()
Used by a MIDlet to notify the application management software that it has entered into the DESTROYED state. The application management software will not call the MIDlet's destroyApp method, and all resources held by the MIDlet will be considered eligible for reclamation. The MIDlet must have performed the same operations (clean up, releasing of resources etc.) it would have if the MIDlet.destroyApp() had been called.

	synchronized (mutex) {
	    state = DESTROYED;
public final voidnotifyPaused()
Used by a MIDlet to notify the application management software that it has entered into the PAUSED state. Invoking this method will have no effect if the MIDlet is destroyed, or if it has not yet been started.

It may be invoked by the MIDlet when it is in the ACTIVE state.

If a MIDlet calls notifyPaused(), in the future its startApp() method may be called make it active again, or its destroyApp() method may be called to request it to destroy itself.

        int oldState;

	synchronized (mutex) {
            oldState = state;

            // do not notify the scheduler, since there is nothing to do

        // do work outside of the mutex
        if (oldState == ACTIVE) {
protected abstract voidpauseApp()
Signals the MIDlet to stop and enter the PAUSED state. In the PAUSED state the MIDlet must release shared resources and become quiescent. This method will only be called called when the MIDlet is in the ACTIVE state.

public final native booleanplatformRequest(java.lang.String URL)
Requests that the device handle (e.g. display or install) the indicated URL.

If the platform has the appropriate capabilities and resources available, it SHOULD bring the appropriate application to the foreground and let the user interact with the content, while keeping the MIDlet suite running in the background. If the platform does not have appropriate capabilities or resources available, it MAY wait to handle the URL request until after the MIDlet suite exits. In this case, when the requesting MIDlet suite exits, the platform MUST then bring the appropriate application to the foreground to let the user interact with the content.

This is a non-blocking method. In addition, this method does NOT queue multiple requests. On platforms where the MIDlet suite must exit before the request is handled, the platform MUST handle only the last request made. On platforms where the MIDlet suite and the request can be handled concurrently, each request that the MIDlet suite makes MUST be passed to the platform software for handling in a timely fashion.

If the URL specified refers to a MIDlet suite (either an Application Descriptor or a JAR file), the request is interpreted as a request to install the named package. In this case, the platform's normal MIDlet suite installation process SHOULD be used, and the user MUST be allowed to control the process (including cancelling the download and/or installation). If the MIDlet suite being installed is an update of the currently running MIDlet suite, the platform MUST first stop the currently running MIDlet suite before performing the update. On some platforms, the currently running MIDlet suite MAY need to be stopped before any installations can occur.

If the URL specified is of the form tel:<number>, as specified in RFC2806, then the platform MUST interpret this as a request to initiate a voice call. The request MUST be passed to the "phone" application to handle if one is present in the platform.

Devices MAY choose to support additional URL schemes beyond the requirements listed above.

Many of the ways this method will be used could have a financial impact to the user (e.g. transferring data through a wireless network, or initiating a voice call). Therefore the platform MUST ask the user to explicitly acknowlege each request before the action is taken. Implementation freedoms are possible so that a pleasant user experience is retained. For example, some platforms may put up a dialog for each request asking the user for permission, while other platforms may launch the appropriate application and populate the URL or phone number fields, but not take the action until the user explicitly clicks the load or dial buttons.

true if the MIDlet suite MUST first exit before the content can be fetched.
URL The URL for the platform to load.
ConnectionNotFoundException if the platform cannot handle the URL requested.
MIDP 2.0

public final voidresumeRequest()
Used by a MIDlet to notify the application management software that it is interested in entering the ACTIVE state. Calls to this method can be used by the application management software to determine which applications to move to the ACTIVE state.

When the application management software decides to activate this application it will call the startApp method.

The application is generally in the PAUSED state when this is called. Even in the paused state the application may handle asynchronous events such as timers or callbacks.

voidsetState(int newState)
Change the state and notify. Check to make sure the new state makes sense. Changes to the status are protected by the mutex. Any change to the state notifies the mutex.

newState new state of the MIDlet

	synchronized (mutex) {
voidsetStateWithoutNotify(int newState)
Change the state without notifing the scheduler. Check to make sure the new state makes sense.

To be called only by the scheduler or MIDletState while holding the scheduler mutex.

newState new state of the MIDlet

        switch (state) {
        case DESTROYED:
            // can't set any thing else
        case DESTROY_PENDING:
            if (newState != DESTROYED) {
                // can only set DESTROYED

        case PAUSED:
            if (newState == PAUSE_PENDING) {
                // already paused by app


        case ACTIVE:
            if (newState == PAUSED_RESUME || newState == ACTIVE_PENDING) {
                // already active

        state = newState;
protected abstract voidstartApp()
Signals the MIDlet to start and enter the ACTIVE state. In the ACTIVE state the MIDlet may hold resources. The method will only be called when the MIDlet is in the PAUSED state.

Two kinds of failures can prevent the service from starting, transient and non-transient. For transient failures the MIDletStateChangeException exception should be thrown. For non-transient failures the notifyDestroyed method should be called.

MIDletStateChangeException is thrown if the MIDlet cannot start now but might be able to start at a later time.