midletstate.java

有关j2me的很好的例子可以研究一下

/*
 * 01/08/08 @(#)MIDletState.java	1.10
 *
 * Copyright 1998-2001 by Sun Microsystems, Inc.,
 * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
 * All rights reserved.
 *
 * This software is the confidential and proprietary information
 * of Sun Microsystems, Inc. ("Confidential Information").  You
 * shall not disclose such Confidential Information and shall use
 * it only in accordance with the terms of the license agreement
 * you entered into with Sun.
 */

package com.sun.midp.midlet;

import javax.microedition.midlet.MIDlet;
import javax.microedition.midlet.MIDletStateChangeException;

import com.sun.midp.lcdui.DisplayAccess;
import com.sun.midp.lcdui.MIDLetMap;

/**
 * MIDletState holds the current state of the MIDlet and forwards
 * updates to it.  It holds the reference to the MIDlet itself
 * and the DisplayAccess object used to communicate with the MIDlet's
 * Display.
 * <p>
 * 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.
 * <p>
 * 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.
 * <p>
 * The getAppProperty method from the MIDlet is sent here and
 * relayed to the Scheduler.
 */

public abstract class MIDletState {

    /*
     * Implementation state; the states are in priority order.
     * That is, a higher number indicates a preference to be
     * selected for scheduling sooner.  This allows the scheduler
     * to make one pass over the known MIDlets and pick the 
     * "best" MIDlet to schedule.
     */

    /**
     * State of the MIDlet is Paused; it should be quiescent
     */
    static final int PAUSED = 0;

    /**
     * State of the MIDlet is Active
     */
    static final int ACTIVE = 1;

    /**
     * State of the MIDlet is Active and has the display
     */
    static final int ACTIVE_FOREGROUND = 2;

    /**
     * State of the MIDlet is Paused but Resume has been requested
     */
    static final int PAUSED_RESUME = 3;

    /**
     * State of the MIDlet with destroy pending
     */
    static final int DESTROY_PENDING = 4;

    /**
     * State of the MIDlet is Destroyed
     */
    static final int DESTROYED = 5;

    /**
     * The applications current state.
     */
    private int state;

    /**
     * The lock for changes to the state.
     */
    private Object mutex;

    /**
     * The controller of MIDlets.
     */
    private Scheduler scheduler;

    /**
     * The MIDlet for which this is the state.
     */
    protected MIDlet midlet;	
    /** 
     * Access to the Display.
     */
    protected DisplayAccess displayAccess;

    /**
     * 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.
     * @param m the MIDlet this is the state for; Must not be <code>null</null>.
     */
    protected MIDletState(MIDlet m) {
	midlet = m;
	state = PAUSED_RESUME;	// So it will be made active soon
	scheduler = Scheduler.getScheduler();
	mutex = scheduler.getMutex();

	// Force the creation of the Display and DisplayAccess
        javax.microedition.lcdui.Display.getDisplay(midlet);
	displayAccess = MIDLetMap.get(midlet);

	scheduler.register(this);
    }

    /**
     * Get the MIDlet for which this holds the state.
     *
     * @return the MIDlet; will not be null.
     */
    public MIDlet getMIDlet() {
	return midlet;
    }

    /**
     * Get the DisplayAccess for this MIDlet.
     * The DisplayAccess instance is used to signal changes in
     * foreground and background to the Display and to get the
     * the state reflecting whether this Display has a Screen and
     * should be in forground.
     *
     * @return the DisplayAccess of this MIDlet.
     */
    public DisplayAccess getDisplayAccess() {
	return displayAccess;
    }

    /**
     * Signals the <code>MIDlet</code> to start and enter the <i>ACTIVE</i>
     * state.
     * In the <i>ACTIVE</I> state the <code>MIDlet</code> may hold resources.
     * The method will only be called when
     * the <code>MIDlet</code> is in the <i>PAUSED</i> state.
     * <p>
     * Two kinds of failures can prevent the service from starting,
     * transient and non-transient.  For transient failures the
     * <code>MIDletStateChangeException</code> exception should be thrown.
     * For non-transient failures the <code>notifyDestroyed</code>
     * method should be called.
     *
     * @exception MIDletStateChangeException  is thrown
     * if the <code>MIDlet</code> cannot start now but might be able to
     * start at a later time.
     */
    protected abstract void startApp() throws MIDletStateChangeException;

    /**
     *
     * Signals the <code>MIDlet</code> to stop and enter the <i>PAUSED</i>
     * state.
     * In the <i>PAUSED</i> state the <code>MIDlet</code> must release shared
     * resources
     * and become quiescent. This method will only be called
     * called when the <code>MIDlet</code> is in the <i>ACTIVE</i> state. <p>
     *
     */
    protected abstract void pauseApp();


    /**
     * Signals the <code>MIDlet</code> to terminate and enter the
     * <i>DESTROYED</i> state.
     * In the destroyed state the <code>MIDlet</code> must release
     * all resources and save any persistent state. This method may
     * be called from the <i>PAUSED</i> or
     * <i>ACTIVE</i> states. <p>
     * <code>MIDlet</code>s should
     * perform any operations required before being terminated, such as
     * releasing resources or saving preferences or
     * state. <p>
     *
     * <b>NOTE:</b> The <code>MIDlet</code> can request that it not enter
     * the <i>DESTROYED</i>
     * state by throwing an <code>MIDletStateChangeException</code>. This
     * is only a valid response if the <code>unconditional</code>
     * flag is set to <code>false</code>. If it is <code>true</code>
     * the <code>MIDlet</code> is assumed to be in the <i>DESTROYED</i>
     * state regardless of how this method terminates. If it is not an
     * unconditional request, the <code>MIDlet</code> can signify that it wishes
     * to stay in its current state by throwing the 
     * <code>MIDletStateChangeException</code>.
     * This request may be honored and the <code>destroy()</code>
     * method called again at a later time.
     *
     * @param unconditional If true when this method is called,
     * the <code>MIDlet</code> must cleanup and release all resources.
     * If false the <code>MIDlet</code> may throw 
     * <CODE>MIDletStateChangeException</CODE>
     * to indicate it does not want to be destroyed at this time.
     *
     * @exception MIDletStateChangeException is thrown if the
     * <code>MIDlet</code> wishes to continue to execute 
     * (Not enter the <i>DESTROYED</i> state).
     * This exception is ignored if <code>unconditional</code>
     * is equal to <code>true</code>.
     */
    protected abstract void destroyApp(boolean unconditional)
	throws MIDletStateChangeException;


    /**
     *
     * Used by a <code>MIDlet</code> to notify the application management
     * software that it has entered into the
     * <i>DESTROYED</i> state.  The application management software will not
     * call the MIDlet's <code>destroyApp</code> method, and all resources
     * held by the <code>MIDlet</code> will be considered eligible for
     * reclamation.
     * The <code>MIDlet</code> must have performed the same operations
     * (clean up, releasing of resources etc.) it would have if the
     * <code>MIDlet.destroyApp()</code> had been called.
     *
     */
    public final void notifyDestroyed() {
	synchronized (mutex) {
	    state = DESTROYED;
	    mutex.notify();
	}
    }

    /**
     * Used by a <code>MIDlet</code> to notify the application management
     * software that it has entered into the <i>PAUSED</i> state.
     * Invoking this method will
     * have no effect if the <code>MIDlet</code> is destroyed,
     * or if it has not yet been started. <p>
     * It may be invoked by the <code>MIDlet</code> when it is in the
     * <i>ACTIVE</i> state. <p>
     *
     * If a <code>MIDlet</code> calls <code>notifyPaused()</code>, in the
     * future its <code>startApp()</code> method may be called make
     * it active again, or its <code>destroyApp()</code> method may be
     * called to request it to destroy itself.
     */
    public final void notifyPaused() {
	synchronized (mutex) {
	    if (state == ACTIVE || state == ACTIVE_FOREGROUND) {
		state = PAUSED;
		mutex.notify();
	    }
	}
    }

    /**
     * Provides a <code>MIDlet</code> with a mechanism to retrieve
     * <code>MIDletSuite</code> for this MIDlet.
     *
     * @return MIDletSuite for this MIDlet
     */
    public final MIDletSuite getMIDletSuite() {
	return scheduler.getMIDletSuite();
    }

    /**
     * Used by a <code>MIDlet</code> to notify the application management
     * software that it is
     * interested in entering the <i>ACTIVE</i> state. Calls to
     * this method can be used by the application management software to
     * determine which applications to move to the <i>ACTIVE</i> state.
     * <p>
     * When the application management software decides to activate this  
     * application it will call the <code>startApp</code> method.
     * <p> The application is generally in the <i>PAUSED</i> state when this is
     * called.  Even in the paused state the application may handle
     * asynchronous events such as timers or callbacks.
     */

    public final void resumeRequest() {
	synchronized (mutex) {
	    if (state == PAUSED) {
		state = PAUSED_RESUME;
		mutex.notify();
	    }
	}
    }

    /**
     * Change the state and notify.
     * Changes to the status are protected by the mutex.
     * Any change to the state notifies the mutex.
     *
     * @param newState new state of the MIDlet
     */
    void setState(int newState) {
	synchronized (mutex) {
	    state = newState;
	    mutex.notify();
	}
    }

    /**
     * Get the state.
     *
     * @return cuurent state of the MIDlet.
     */
    int getState() {
	synchronized (mutex) {
	    return state;
	}
    }
}