1 /*
2 * Copyright (c) 1995, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package java.applet;
27
28 import java.awt.Image;
29 import java.awt.Graphics;
30 import java.awt.image.ColorModel;
31 import java.net.URL;
32 import java.util.Enumeration;
33 import java.io.InputStream;
34 import java.io.IOException;
35 import java.util.Iterator;
36
37 /**
38 * This interface corresponds to an applet's environment: the
39 * document containing the applet and the other applets in the same
40 * document.
41 * <p>
42 * The methods in this interface can be used by an applet to obtain
43 * information about its environment.
44 *
45 * @author Arthur van Hoff
46 * @since 1.0
47 *
48 * @deprecated The Applet API is deprecated. See the
49 * <a href="package-summary.html"> java.applet package documentation</a>
50 * for further information.
51 */
52
53 @Deprecated(since = "9")
54 public interface AppletContext {
55 /**
56 * Creates an audio clip.
57 *
58 * @param url an absolute URL giving the location of the audio clip.
59 * @return the audio clip at the specified URL.
60 */
61 AudioClip getAudioClip(URL url);
62
63 /**
64 * Returns an {@code Image} object that can then be painted on
65 * the screen. The {@code url} argument that is
66 * passed as an argument must specify an absolute URL.
67 * <p>
68 * This method always returns immediately, whether or not the image
69 * exists. When the applet attempts to draw the image on the screen,
70 * the data will be loaded. The graphics primitives that draw the
71 * image will incrementally paint on the screen.
72 *
73 * @param url an absolute URL giving the location of the image.
74 * @return the image at the specified URL.
75 * @see java.awt.Image
76 */
77 Image getImage(URL url);
78
79 /**
80 * Finds and returns the applet in the document represented by this
81 * applet context with the given name. The name can be set in the
82 * HTML tag by setting the {@code name} attribute.
83 *
84 * @param name an applet name.
85 * @return the applet with the given name, or {@code null} if
86 * not found.
87 */
88 Applet getApplet(String name);
89
90 /**
91 * Finds all the applets in the document represented by this applet
92 * context.
93 *
94 * @return an enumeration of all applets in the document represented by
95 * this applet context.
96 */
97 Enumeration<Applet> getApplets();
98
99 /**
100 * Requests that the browser or applet viewer show the Web page
101 * indicated by the {@code url} argument. The browser or
102 * applet viewer determines which window or frame to display the
103 * Web page. This method may be ignored by applet contexts that
104 * are not browsers.
105 *
106 * @param url an absolute URL giving the location of the document.
107 */
108 void showDocument(URL url);
109
110 /**
111 * Requests that the browser or applet viewer show the Web page
112 * indicated by the {@code url} argument. The
113 * {@code target} argument indicates in which HTML frame the
114 * document is to be displayed.
115 * The target argument is interpreted as follows:
116 *
117 * <center><table border="3" summary="Target arguments and their descriptions">
118 * <tr><th>Target Argument</th><th>Description</th></tr>
119 * <tr><td>{@code "_self"} <td>Show in the window and frame that
120 * contain the applet.</tr>
121 * <tr><td>{@code "_parent"}<td>Show in the applet's parent frame. If
122 * the applet's frame has no parent frame,
123 * acts the same as "_self".</tr>
124 * <tr><td>{@code "_top"} <td>Show in the top-level frame of the applet's
125 * window. If the applet's frame is the
126 * top-level frame, acts the same as "_self".</tr>
127 * <tr><td>{@code "_blank"} <td>Show in a new, unnamed
128 * top-level window.</tr>
129 * <tr><td><i>name</i><td>Show in the frame or window named <i>name</i>. If
130 * a target named <i>name</i> does not already exist, a
131 * new top-level window with the specified name is created,
132 * and the document is shown there.</tr>
133 * </table> </center>
134 * <p>
135 * An applet viewer or browser is free to ignore {@code showDocument}.
136 *
137 * @param url an absolute URL giving the location of the document.
138 * @param target a {@code String} indicating where to display
139 * the page.
140 */
141 public void showDocument(URL url, String target);
142
143 /**
144 * Requests that the argument string be displayed in the
145 * "status window". Many browsers and applet viewers
146 * provide such a window, where the application can inform users of
147 * its current state.
148 *
149 * @param status a string to display in the status window.
150 */
151 void showStatus(String status);
152
153 /**
154 * Associates the specified stream with the specified key in this
155 * applet context. If the applet context previously contained a mapping
156 * for this key, the old value is replaced.
157 * <p>
158 * For security reasons, mapping of streams and keys exists for each
159 * codebase. In other words, applet from one codebase cannot access
160 * the streams created by an applet from a different codebase
161 *
162 * @param key key with which the specified value is to be associated.
163 * @param stream stream to be associated with the specified key. If this
164 * parameter is {@code null}, the specified key is removed
165 * in this applet context.
166 * @throws IOException if the stream size exceeds a certain
167 * size limit. Size limit is decided by the implementor of this
168 * interface.
169 * @since 1.4
170 */
171 public void setStream(String key, InputStream stream)throws IOException;
172
173 /**
174 * Returns the stream to which specified key is associated within this
175 * applet context. Returns {@code null} if the applet context contains
176 * no stream for this key.
177 * <p>
178 * For security reasons, mapping of streams and keys exists for each
179 * codebase. In other words, applet from one codebase cannot access
180 * the streams created by an applet from a different codebase
181 *
182 * @return the stream to which this applet context maps the key
183 * @param key key whose associated stream is to be returned.
184 * @since 1.4
185 */
186 public InputStream getStream(String key);
187
188 /**
189 * Finds all the keys of the streams in this applet context.
190 * <p>
191 * For security reasons, mapping of streams and keys exists for each
192 * codebase. In other words, applet from one codebase cannot access
193 * the streams created by an applet from a different codebase
194 *
195 * @return an Iterator of all the names of the streams in this applet
196 * context.
197 * @since 1.4
198 */
199 public Iterator<String> getStreamKeys();
200 }