001: /*
002: * @(#)XletContext.java 1.23 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: import java.awt.Container;
031:
032: /**
033: * An interface that provides methods allowing an Xlet to discover
034: * information about its environment. An XletContext is passed
035: * to an Xlet when the Xlet is initialized. It provides an Xlet with a
036: * mechanism to retrieve properties, as well as a way to signal
037: * internal state changes.
038: *
039: * @see javax.microedition.xlet.Xlet
040: */
041:
042: public interface XletContext {
043: /**
044: * The property key used to obtain initialization arguments for the
045: * Xlet. The call
046: * <code>XletContext.getXletProperty(XletContext.ARGS)</code> will
047: * return the arguments as an array of Strings. If there are
048: * no arguments, then an array of length 0 will be returned.
049: *
050: * @see #getXletProperty
051: */
052: public static final String ARGS = "javax.microedition.xlet.args";
053:
054: /**
055: *
056: * Used by an application to notify its manager that it
057: * has entered into the
058: * <i>Destroyed</i> state. The application manager will not
059: * call the Xlet's <code>destroy</code> method, and all resources
060: * held by the Xlet will be considered eligible for reclamation.
061: * Before calling this method,
062: * the Xlet must have performed the same operations
063: * (clean up, releasing of resources etc.) it would have if the
064: * <code>Xlet.destroyXlet()</code> had been called.
065: *
066: */
067: public void notifyDestroyed();
068:
069: /**
070: * Notifies the manager that the Xlet does not want to be active and has
071: * entered the <i>Paused</i> state. Invoking this method will
072: * have no effect if the Xlet is destroyed, or if it has not
073: * yet been started. <p>
074: *
075: * If an Xlet calls <code>notifyPaused()</code>, in the
076: * future it may receive an <i>Xlet.startXlet()</i> call to request
077: * it to become active, or an <i>Xlet.destroyXlet()</i> call to request
078: * it to destroy itself.
079: *
080: */
081:
082: public void notifyPaused();
083:
084: /**
085: * Provides an Xlet with a mechanism to retrieve named
086: * properties from the XletContext.
087: *
088: * @param key The name of the property.
089: *
090: * @return A reference to an object representing the property.
091: * <code>null</code> is returned if no value is available for key.
092: */
093: public Object getXletProperty(String key);
094:
095: /**
096: * Provides the Xlet with a mechanism to indicate that it is
097: * interested in entering the <i>Active</i> state. Calls to this
098: * method can be used by an application manager to determine which
099: * Xlets to move to <i>Active</i> state.
100: * If the request is fulfilled, the application manager will
101: * subsequently call <code>Xlet.startXlet()</code>
102: * via a different thread than the one used to call
103: * <code>resumeRequest()</code>.
104: *
105: * @see Xlet#startXlet
106: */
107: public void resumeRequest();
108:
109: /**
110: * Get the parent container for an Xlet to put its AWT components in.
111: * Xlets without a graphical representation should never call this method.
112: * If successful, this method returns an instance of java.awt.Container that
113: * is initially invisible, with an arbitrary size and position.
114:
115: * If this method is called multiple times on the same XletContext instance,
116: * the same container will be returned each time.
117:
118: * The methods for setting the size and position of the xlet's parent
119: * container shall attempt to change the shape of the container, but they may
120: * fail silently or make platform specific approximations. To discover if
121: * a request to change the size or position has succeeded, the Xlet should
122: * query the container for the result.
123: *
124: * @return An invisible container with an arbitrary size and position.
125: *
126: * @exception UnavailableContainerException - If policy or screen real estate
127: * does not permit a Container to be granted to the Xlet at this time.
128: */
129:
130: public Container getContainer()
131: throws UnavailableContainerException;
132:
133: /**
134: * Returns the base class loader of the Xlet. This class loader
135: * will be dedicated exclusively to the xlet. The xlet's classes are
136: * all loaded by this classloader or by a classloader that has this
137: * classloader as its ancestor.
138: */
139: public java.lang.ClassLoader getClassLoader();
140: }
|