001: /*
002: * Copyright 1995-2006 Sun Microsystems, Inc. All Rights Reserved.
003: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004: *
005: * This code is free software; you can redistribute it and/or modify it
006: * under the terms of the GNU General Public License version 2 only, as
007: * published by the Free Software Foundation. Sun designates this
008: * particular file as subject to the "Classpath" exception as provided
009: * by Sun in the LICENSE file that accompanied this code.
010: *
011: * This code is distributed in the hope that it will be useful, but WITHOUT
012: * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013: * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014: * version 2 for more details (a copy is included in the LICENSE file that
015: * accompanied this code).
016: *
017: * You should have received a copy of the GNU General Public License version
018: * 2 along with this work; if not, write to the Free Software Foundation,
019: * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020: *
021: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022: * CA 95054 USA or visit www.sun.com if you need additional information or
023: * have any questions.
024: */
025:
026: package java.applet;
027:
028: import java.awt.Image;
029: import java.awt.Graphics;
030: import java.awt.image.ColorModel;
031: import java.net.URL;
032: import java.util.Enumeration;
033: import java.io.InputStream;
034: import java.io.IOException;
035: import java.util.Iterator;
036:
037: /**
038: * This interface corresponds to an applet's environment: the
039: * document containing the applet and the other applets in the same
040: * document.
041: * <p>
042: * The methods in this interface can be used by an applet to obtain
043: * information about its environment.
044: *
045: * @author Arthur van Hoff
046: * @version 1.41, 05/05/07
047: * @since JDK1.0
048: */
049: public interface AppletContext {
050: /**
051: * Creates an audio clip.
052: *
053: * @param url an absolute URL giving the location of the audio clip.
054: * @return the audio clip at the specified URL.
055: */
056: AudioClip getAudioClip(URL url);
057:
058: /**
059: * Returns an <code>Image</code> object that can then be painted on
060: * the screen. The <code>url</code> argument<code> </code>that is
061: * passed as an argument must specify an absolute URL.
062: * <p>
063: * This method always returns immediately, whether or not the image
064: * exists. When the applet attempts to draw the image on the screen,
065: * the data will be loaded. The graphics primitives that draw the
066: * image will incrementally paint on the screen.
067: *
068: * @param url an absolute URL giving the location of the image.
069: * @return the image at the specified URL.
070: * @see java.awt.Image
071: */
072: Image getImage(URL url);
073:
074: /**
075: * Finds and returns the applet in the document represented by this
076: * applet context with the given name. The name can be set in the
077: * HTML tag by setting the <code>name</code> attribute.
078: *
079: * @param name an applet name.
080: * @return the applet with the given name, or <code>null</code> if
081: * not found.
082: */
083: Applet getApplet(String name);
084:
085: /**
086: * Finds all the applets in the document represented by this applet
087: * context.
088: *
089: * @return an enumeration of all applets in the document represented by
090: * this applet context.
091: */
092: Enumeration<Applet> getApplets();
093:
094: /**
095: * Requests that the browser or applet viewer show the Web page
096: * indicated by the <code>url</code> argument. The browser or
097: * applet viewer determines which window or frame to display the
098: * Web page. This method may be ignored by applet contexts that
099: * are not browsers.
100: *
101: * @param url an absolute URL giving the location of the document.
102: */
103: void showDocument(URL url);
104:
105: /**
106: * Requests that the browser or applet viewer show the Web page
107: * indicated by the <code>url</code> argument. The
108: * <code>target</code> argument indicates in which HTML frame the
109: * document is to be displayed.
110: * The target argument is interpreted as follows:
111: * <p>
112: * <center><table border="3" summary="Target arguments and their descriptions">
113: * <tr><th>Target Argument</th><th>Description</th></tr>
114: * <tr><td><code>"_self"</code> <td>Show in the window and frame that
115: * contain the applet.</tr>
116: * <tr><td><code>"_parent"</code><td>Show in the applet's parent frame. If
117: * the applet's frame has no parent frame,
118: * acts the same as "_self".</tr>
119: * <tr><td><code>"_top"</code> <td>Show in the top-level frame of the applet's
120: * window. If the applet's frame is the
121: * top-level frame, acts the same as "_self".</tr>
122: * <tr><td><code>"_blank"</code> <td>Show in a new, unnamed
123: * top-level window.</tr>
124: * <tr><td><i>name</i><td>Show in the frame or window named <i>name</i>. If
125: * a target named <i>name</i> does not already exist, a
126: * new top-level window with the specified name is created,
127: * and the document is shown there.</tr>
128: * </table> </center>
129: * <p>
130: * An applet viewer or browser is free to ignore <code>showDocument</code>.
131: *
132: * @param url an absolute URL giving the location of the document.
133: * @param target a <code>String</code> indicating where to display
134: * the page.
135: */
136: public void showDocument(URL url, String target);
137:
138: /**
139: * Requests that the argument string be displayed in the
140: * "status window". Many browsers and applet viewers
141: * provide such a window, where the application can inform users of
142: * its current state.
143: *
144: * @param status a string to display in the status window.
145: */
146: void showStatus(String status);
147:
148: /**
149: * Associates the specified stream with the specified key in this
150: * applet context. If the applet context previously contained a mapping
151: * for this key, the old value is replaced.
152: * <p>
153: * For security reasons, mapping of streams and keys exists for each
154: * codebase. In other words, applet from one codebase cannot access
155: * the streams created by an applet from a different codebase
156: * <p>
157: * @param key key with which the specified value is to be associated.
158: * @param stream stream to be associated with the specified key. If this
159: * parameter is <code>null</code>, the specified key is removed
160: * in this applet context.
161: * @throws <code>IOException</code> if the stream size exceeds a certain
162: * size limit. Size limit is decided by the implementor of this
163: * interface.
164: * @since 1.4
165: */
166: public void setStream(String key, InputStream stream)
167: throws IOException;
168:
169: /**
170: * Returns the stream to which specified key is associated within this
171: * applet context. Returns <tt>null</tt> if the applet context contains
172: * no stream for this key.
173: * <p>
174: * For security reasons, mapping of streams and keys exists for each
175: * codebase. In other words, applet from one codebase cannot access
176: * the streams created by an applet from a different codebase
177: * <p>
178: * @return the stream to which this applet context maps the key
179: * @param key key whose associated stream is to be returned.
180: * @since 1.4
181: */
182: public InputStream getStream(String key);
183:
184: /**
185: * Finds all the keys of the streams in this applet context.
186: * <p>
187: * For security reasons, mapping of streams and keys exists for each
188: * codebase. In other words, applet from one codebase cannot access
189: * the streams created by an applet from a different codebase
190: * <p>
191: * @return an Iterator of all the names of the streams in this applet
192: * context.
193: * @since 1.4
194: */
195: public Iterator<String> getStreamKeys();
196: }
| 