midlet.java

来自「This is a resource based on j2me embedde」· Java 代码 · 共 384 行 · 第 1/2 页

/*
 *   
 *
 * Copyright  1990-2007 Sun Microsystems, Inc. All Rights Reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
 * 
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License version
 * 2 only, as published by the Free Software Foundation.
 * 
 * This program is distributed in the hope that it will be useful, but
 * WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 * General Public License version 2 for more details (a copy is
 * included at /legal/license.txt).
 * 
 * You should have received a copy of the GNU General Public License
 * version 2 along with this work; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA
 * 
 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
 * Clara, CA 95054 or visit www.sun.com if you need additional
 * information or have any questions.
 */

package javax.microedition.midlet;

import com.sun.midp.midlet.MIDletPeer;
import com.sun.midp.midlet.MIDletStateHandler;

import com.sun.midp.security.SecurityToken;
import com.sun.midp.security.SecurityInitializer;
import com.sun.midp.security.ImplicitlyTrustedClass;

import javax.microedition.lcdui.Display;

/**
 * A <code>MIDlet</code> is a MID Profile application.
 * The application must extend this class to allow the
 * application management software to control the MIDlet and to be
 * able to retrieve properties from the application descriptor
 * and notify and request state changes.
 * The methods of this class allow the application management software
 * to create,  start, pause, and destroy a MIDlet.
 * A <code>MIDlet</code> is a set of classes designed to be run and
 * controlled by the application management software via this interface.
 * The states allow the application management software to manage
 * the activities of multiple <CODE>MIDlets</CODE> within
 * a runtime environment.
 * It can select which <code>MIDlet</code>s are active at a given time
 * by starting and pausing them individually.
 * The application management software maintains the state of the
 * <code>MIDlet</code> and
 * invokes methods on the <code>MIDlet</code> to notify the MIDlet of
 * change states.
 * The <code>MIDlet</code>
 * implements these methods to update its internal activities and
 * resource usage as directed by the application management software.
 * The <code>MIDlet</code> can initiate some state changes itself and
 * notifies the application management software of those state changes
 * by invoking the appropriate methods.<p>
 *
 * <strong>Note:</strong> The methods on this interface signal state
 * changes. The state change is not considered complete until the state
 * change method has returned. It is intended that these methods return
 * quickly.<p>
 */

public abstract class MIDlet {

    /**
     * Inner class to request security token from SecurityInitializer.
     * SecurityInitializer should be able to check this inner class name.
     */
    static private class SecurityTrusted
        implements ImplicitlyTrustedClass {}

    /** Security token to allow access to implementation APIs */
    private static SecurityToken classSecurityToken =
        SecurityInitializer.requestToken(new SecurityTrusted());

    /** Internal peer of this MIDlet */
    private MIDletPeer peer;

    /**
     * Static initializer to set MIDletTunnel implementation
     * in MIDletPeer class.
     */
    static {
        MIDletPeer.setMIDletTunnel(classSecurityToken,
                                    new MIDletTunnelImpl());
    }

    /**
     * Gets the MIDletPeer instance for this MIDlet.
     *
     * @return MIDletPeer instance for this midlet.
     */
    MIDletPeer getMIDletPeer() {
        return peer;
    }
     
    /**
     * Protected constructor for subclasses.
     * The application management software is responsible
     * for creating MIDlets and creation of MIDlets is restricted.
     * MIDlets should not attempt to create other MIDlets.
     *
     * @exception java.lang.SecurityException unless the application
     * management software is creating the MIDlet.
     */
    protected MIDlet() {
        peer = MIDletStateHandler.newMIDletPeer(classSecurityToken, this);

        // Ensure that a display for this midlet is created
        Display d = Display.getDisplay(this);
    }

    /**
     * Signals the <code>MIDlet</code> that it has entered the
     * <em>Active</em> state.
     * In the <em>Active</EM> state the <code>MIDlet</code> may
     * hold resources.
     * The method will only be called when
     * the <code>MIDlet</code> is in the <em>Paused</em> 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.
     * <p>
     * If a Runtime exception occurs during <code>startApp</code> the
     * MIDlet will be
     * destroyed immediately.  Its <code>destroyApp</code> will be
     * called allowing
     * the MIDlet to cleanup.
     *
     * @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 enter
     * the <em>Paused</em> state.
     * In the <em>Paused</em> 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 <em>Active</em> state. <p>
     * <p>
     * If a Runtime exception occurs during <code>pauseApp</code> the
     * MIDlet will be destroyed immediately.  Its
     * <code>destroyApp</code> will be called allowing
     * the MIDlet to cleanup.
     */
    protected abstract void pauseApp();

    /**
     * Signals the <code>MIDlet</code> to terminate and enter the
     * <em>Destroyed</em> 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 <em>Paused</em> or
     * <em>Active</em> states. <p>
     * <code>MIDlet</code>s should
     * perform any operations required before being terminated, such as
     * releasing resources or saving preferences or
     * state. <p>
     *
     * <strong>Note:</strong> The <code>MIDlet</code> can request that
     * it not enter the <em>Destroyed</em>
     * 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 <em>Destroyed</em> 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.
     *
     * <p>If a Runtime exception occurs during <code>destroyApp</code> then
     * they are ignored and the MIDlet is put into the <em>Destroyed</em>
     * state.
     *
     * @param unconditional If true when this method is called, the