midletstate.java

用于移动设备上的java虚拟机源代码

/*
 * @(#)MIDletState.java	1.19 02/09/11 @(#)
 *
 * Copyright (c) 1998-2002 Sun Microsystems, Inc.  All rights reserved.
 * PROPRIETARY/CONFIDENTIAL
 * Use is subject to license terms.
 */

package com.sun.midp.midlet;

import javax.microedition.lcdui.Display;

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

import com.sun.midp.lcdui.DisplayAccess;
import com.sun.midp.lcdui.DisplayManager;
import com.sun.midp.lcdui.DisplayManagerFactory;

import com.sun.midp.security.Permissions;
import com.sun.midp.security.SecurityToken;

/**
 * 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.
 * <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 Paused but Resume has been requested
     */
    static final int PAUSED_RESUME = 2;

    /**
     * State of the MIDlet when resumed by the display manager
     */
    static final int ACTIVE_PENDING = 3;

    /**
     * State of the MIDlet when paused by the display manager
     */
    static final int PAUSE_PENDING = 4;

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

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

    /** This class has a different security domain than the application. */
    private static SecurityToken classSecurityToken;

    /** Lock for creating a MIDlet. */
    private static Object createMIDletLock = new Object();

    /** Lock for creating a MIDlet, default to false. */
    private static boolean allowedToCreateMIDlet;

    /**
     * Initializes the security token for this class, so it can
     * perform actions that a normal MIDlet Suite cannot.
     *
     * @param token security token for this class
     */
    public static void initSecurityToken(SecurityToken token) {
        if (classSecurityToken != null) {
            return;
        }

        classSecurityToken = token;
    }

    /**
     * Create a MIDlet without throwing a security exception.
     *
     * @param classname name of MIDlet class
     *
     * @return newly created MIDlet
     *
     * @exception ClassNotFoundException is thrown, if the MIDlet main class is
     * not found
     * @exception InstantiationException is thrown, if the MIDlet can not be 
     * created
     * @exception IllegalAccessException is thrown, if the MIDlet is not 
     * permitted to perform a specific operation
     */
    static MIDlet createMIDlet(String classname) throws
           ClassNotFoundException, InstantiationException,
           IllegalAccessException {
        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;
            }
        }
    }

    /**
     * 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;	

    /** 
     * The Display for this MIDlet.
     */
    protected Display display;

    /** 
     * The controller of Displays.
     */
    protected DisplayManager displayManager;

    /**
     * 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</code>.
     *
     * @exception SecurityException if is constructor is not being called in
     * the context of <code>createMIDlet</code> and the suite does not
     * have the AMS permission.
     */
    protected MIDletState(MIDlet m) {
        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) {
                    suite.checkIfPermissionAllowed(Permissions.AMS);
                }
            }
        }

	// 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);
        }
    }

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

    /**
     * Get the Display for this MIDlet.
     *
     * @return the Display of this MIDlet.
     */
    public Display getDisplay() {
	return display;
    }

    /**
     * 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();


    /**