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