001: /*
002: * @(#)Xlet.java 1.28 06/10/10
003: *
004: * Copyright 1990-2006 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: *
026: */
027:
028: package javax.microedition.xlet;
029:
030: /**
031: * This interface allows an application manager to create,
032: * initialize, start, pause, and destroy an Xlet.
033: * An Xlet is an application or service designed to be run and
034: * controlled by an application manager via this lifecycle interface.
035: * The lifecycle states allow the application manager to manage
036: * the activities of multiple Xlets within a runtime environment
037: * selecting which Xlets are active at a given time.
038: * The application manager maintains the state of the Xlet and
039: * invokes method on the Xlet via the lifecycle methods. The Xlet
040: * implements these methods to update its internal activities and
041: * resource usage as directed by the application manager.
042: * The Xlet can initiate some state changes itself and informs
043: * the application manager of those state changes
044: * by invoking methods on <code>XletContext</code>.<p>
045: *
046: * In order to support interoperability between Xlets and application
047: * managers, all Xlet classes must provide a public no-argument
048: * constructor.<p>
049: *
050: * <b>Note:</b> The methods on this interface are meant to signal state
051: * changes. The state change is not considered complete until the state
052: * change method has returned. It is intended that these methods return
053: * quickly.<p>
054: *
055: * @see XletContext
056: */
057: public interface Xlet {
058: /**
059: * Signals the Xlet to initialize itself and enter the
060: * <i>Paused</i> state.
061: * The Xlet shall initialize itself in preparation for providing service.
062: * It should not hold shared resources but should be prepared to provide
063: * service in a reasonable amount of time. <p>
064: * An <code>XletContext</code> is used by the Xlet to access
065: * properties associated with its runtime environment.
066: * After this method returns successfully, the Xlet
067: * is in the <i>Paused</i> state and should be quiescent. <p>
068: * <b>Note:</b> This method shall only be called once.<p>
069: *
070: * @param ctx The <code>XletContext</code> of this Xlet.
071: * @exception XletStateChangeException If the Xlet cannot be
072: * initialized.
073: * @see javax.microedition.xlet.XletContext
074: */
075:
076: public void initXlet(XletContext ctx)
077: throws XletStateChangeException;
078:
079: /**
080: * Signals the Xlet to start providing service and
081: * enter the <i>Active</i> state.
082: * In the <i>Active</I> state the Xlet may hold shared resources.
083: * The method will only be called when
084: * the Xlet is in the <i>paused</i> state.
085: * <p>
086: *
087: * @exception XletStateChangeException is thrown if the Xlet
088: * cannot start providing service.
089: */
090:
091: /*
092: * Two kinds of failures can prevent the service from starting,
093: * transient and non-transient. For transient failures the
094: * <code>XletStateChangeException</code> exception should be thrown.
095: * For non-transient failures the <code>XletContext.notifyDestroyed</code>
096: * method should be called.
097: *
098: * @see XletContext#notifyDestroyed
099: */
100: public void startXlet() throws XletStateChangeException;
101:
102: /**
103: *
104: * Signals the Xlet to stop providing service and
105: * enter the <i>Paused</i> state.
106: * In the <i>Paused</i> state the Xlet must stop providing
107: * service, and might release all shared resources
108: * and become quiescent. This method will only be called
109: * called when the Xlet is in the <i>Active</i> state. <p>
110: *
111: */
112: public void pauseXlet();
113:
114: /**
115: * Signals the Xlet to terminate and enter the <i>Destroyed</i> state.
116: * In the destroyed state the Xlet must release
117: * all resources and save any persistent state. This method may
118: * be called from the <i>Loaded</i>, <i>Paused</i> or
119: * <i>Active</i> states. <p>
120: * Xlets should
121: * perform any operations required before being terminated, such as
122: * releasing resources or saving preferences or
123: * state. <p>
124: *
125: * <b>NOTE:</b> The Xlet can request that it not enter the <i>Destroyed</i>
126: * state by throwing an <code>XletStateChangeException</code>. This
127: * is only a valid response if the <code>unconditional</code>
128: * flag is set to <code>false</code>. If it is <code>true</code>
129: * the Xlet is assumed to be in the <i>Destroyed</i> state
130: * regardless of how this method terminates. If it is not an
131: * unconditional request, the Xlet can signify that it wishes
132: * to stay in its current state by throwing the Exception.
133: * This request may be honored and the <code>destroyXlet()</code>
134: * method called again at a later time.
135: *
136: *
137: * @param unconditional If <code>unconditional</code> is true when this
138: * method is called, requests by the Xlet to not enter the
139: * destroyed state will be ignored.
140: *
141: * @exception XletStateChangeException is thrown if the Xlet
142: * wishes to continue to execute (Not enter the <i>Destroyed</i>
143: * state).
144: * This exception is ignored if <code>unconditional</code>
145: * is equal to <code>true</code>.
146: *
147: *
148: */
149: public void destroyXlet(boolean unconditional)
150: throws XletStateChangeException;
151: }
|