1 /*
2 * Copyright (c) 1995, 2018, 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.io.IOException;
30 import java.io.InputStream;
31 import java.net.URL;
32 import java.util.Enumeration;
33 import java.util.Iterator;
34
35 /**
36 * This interface corresponds to an applet's environment: the
37 * document containing the applet and the other applets in the same
38 * document.
39 * <p>
40 * The methods in this interface can be used by an applet to obtain
41 * information about its environment.
42 *
43 * @author Arthur van Hoff
44 * @since 1.0
45 *
46 * @deprecated The Applet API is deprecated, no replacement.
47 */
48 @Deprecated(since = "9")
49 public interface AppletContext {
50 /**
51 * Creates an audio clip.
52 *
53 * @param url an absolute URL giving the location of the audio clip.
54 * @return the audio clip at the specified URL.
55 */
56 AudioClip getAudioClip(URL url);
57
58 /**
59 * Returns an {@code Image} object that can then be painted on
60 * the screen. The {@code url} argument that is
61 * passed as an argument must specify an absolute URL.
62 * <p>
63 * This method always returns immediately, whether or not the image
64 * exists. When the applet attempts to draw the image on the screen,
65 * the data will be loaded. The graphics primitives that draw the
66 * image will incrementally paint on the screen.
67 *
68 * @param url an absolute URL giving the location of the image.
69 * @return the image at the specified URL.
70 * @see java.awt.Image
71 */
72 Image getImage(URL url);
73
74 /**
75 * Finds and returns the applet in the document represented by this
76 * applet context with the given name. The name can be set in the
77 * HTML tag by setting the {@code name} attribute.
78 *
79 * @param name an applet name.
80 * @return the applet with the given name, or {@code null} if
81 * not found.
82 */
83 Applet getApplet(String name);
84
85 /**
86 * Finds all the applets in the document represented by this applet
87 * context.
88 *
89 * @return an enumeration of all applets in the document represented by
90 * this applet context.
91 */
92 Enumeration<Applet> getApplets();
93
94 /**
95 * Requests that the browser or applet viewer show the Web page
96 * indicated by the {@code url} argument. The browser or
97 * applet viewer determines which window or frame to display the
98 * Web page. This method may be ignored by applet contexts that
99 * 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} argument. The
108 * {@code target} argument indicates in which HTML frame the
109 * document is to be displayed.
110 * The target argument is interpreted as follows:
111 *
112 * <table class="striped">
113 * <caption>Target arguments and their descriptions</caption>
114 * <thead>
115 * <tr>
116 * <th scope="col">Target Argument
117 * <th scope="col">Description
118 * </thead>
119 * <tbody>
120 * <tr>
121 * <th scope="row">{@code "_self"}
122 * <td>Show in the window and frame that contain the applet.
123 * <tr>
124 * <th scope="row">{@code "_parent"}
125 * <td>Show in the applet's parent frame. If the applet's frame has no
126 * parent frame, acts the same as "_self".
127 * <tr>
128 * <th scope="row">{@code "_top"}
129 * <td>Show in the top-level frame of the applet's window. If the
130 * applet's frame is the top-level frame, acts the same as "_self".
131 * <tr>
132 * <th scope="row">{@code "_blank"}
133 * <td>Show in a new, unnamed top-level window.
134 * <tr>
135 * <th scope="row"><i>name</i>
136 * <td>Show in the frame or window named <i>name</i>. If a target named
137 * <i>name</i> does not already exist, a new top-level window with the
138 * specified name is created, and the document is shown there.
139 * </tbody>
140 * </table>
141 * <p>
142 * An applet viewer or browser is free to ignore {@code showDocument}.
143 *
144 * @param url an absolute URL giving the location of the document.
145 * @param target a {@code String} indicating where to display
146 * the page.
147 */
148 public void showDocument(URL url, String target);
149
150 /**
151 * Requests that the argument string be displayed in the
152 * "status window". Many browsers and applet viewers
153 * provide such a window, where the application can inform users of
154 * its current state.
155 *
156 * @param status a string to display in the status window.
157 */
158 void showStatus(String status);
159
160 /**
161 * Associates the specified stream with the specified key in this
162 * applet context. If the applet context previously contained a mapping
163 * for this key, the old value is replaced.
164 * <p>
165 * For security reasons, mapping of streams and keys exists for each
166 * codebase. In other words, applet from one codebase cannot access
167 * the streams created by an applet from a different codebase
168 *
169 * @param key key with which the specified value is to be associated.
170 * @param stream stream to be associated with the specified key. If this
171 * parameter is {@code null}, the specified key is removed
172 * in this applet context.
173 * @throws IOException if the stream size exceeds a certain
174 * size limit. Size limit is decided by the implementor of this
175 * interface.
176 * @since 1.4
177 */
178 public void setStream(String key, InputStream stream)throws IOException;
179
180 /**
181 * Returns the stream to which specified key is associated within this
182 * applet context. Returns {@code null} if the applet context contains
183 * no stream for this key.
184 * <p>
185 * For security reasons, mapping of streams and keys exists for each
186 * codebase. In other words, applet from one codebase cannot access
187 * the streams created by an applet from a different codebase
188 *
189 * @return the stream to which this applet context maps the key
190 * @param key key whose associated stream is to be returned.
191 * @since 1.4
192 */
193 public InputStream getStream(String key);
194
195 /**
196 * Finds all the keys of the streams in this applet context.
197 * <p>
198 * For security reasons, mapping of streams and keys exists for each
199 * codebase. In other words, applet from one codebase cannot access
200 * the streams created by an applet from a different codebase
201 *
202 * @return an Iterator of all the names of the streams in this applet
203 * context.
204 * @since 1.4
205 */
206 public Iterator<String> getStreamKeys();
207 }