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 package java.applet;
26
27 import java.awt.*;
28 import java.awt.image.ColorModel;
29 import java.io.IOException;
30 import java.io.ObjectInputStream;
31 import java.net.URL;
32 import java.net.MalformedURLException;
33 import java.util.Hashtable;
34 import java.util.Locale;
35 import javax.accessibility.*;
36
37 /**
38 * An applet is a small program that is intended not to be run on
39 * its own, but rather to be embedded inside another application.
40 * <p>
41 * The {@code Applet} class must be the superclass of any
42 * applet that is to be embedded in a Web page or viewed by the Java
43 * Applet Viewer. The {@code Applet} class provides a standard
44 * interface between applets and their environment.
45 *
46 * @author Arthur van Hoff
47 * @author Chris Warth
48 * @since 1.0
49 *
50 * @deprecated As of JDK 9, the Applet API is deprecated, no replacement.
51 */
52
53 @Deprecated(since = "9")
54 public class Applet extends Panel {
55
56 /**
57 * Constructs a new Applet.
58 * <p>
59 * Note: Many methods in {@code java.applet.Applet}
60 * may be invoked by the applet only after the applet is
61 * fully constructed; applet should avoid calling methods
62 * in {@code java.applet.Applet} in the constructor.
63 *
64 * @exception HeadlessException if GraphicsEnvironment.isHeadless()
65 * returns true.
66 * @see java.awt.GraphicsEnvironment#isHeadless
67 * @since 1.4
68 */
69 public Applet() throws HeadlessException {
70 if (GraphicsEnvironment.isHeadless()) {
71 throw new HeadlessException();
72 }
73 }
74
75 /**
76 * Applets can be serialized but the following conventions MUST be followed:
77 *
78 * Before Serialization:
79 * An applet must be in STOPPED state.
80 *
81 * After Deserialization:
82 * The applet will be restored in STOPPED state (and most clients will
83 * likely move it into RUNNING state).
84 * The stub field will be restored by the reader.
85 */
86 private transient AppletStub stub;
87
88 /* version ID for serialized form. */
89 private static final long serialVersionUID = -5836846270535785031L;
90
91 /**
92 * Read an applet from an object input stream.
93 * @param s an object input stream.
94 * @exception HeadlessException if
95 * {@code GraphicsEnvironment.isHeadless()} returns
96 * {@code true}
97 * @serial
98 * @see java.awt.GraphicsEnvironment#isHeadless
99 * @since 1.4
100 */
101 private void readObject(ObjectInputStream s)
102 throws ClassNotFoundException, IOException, HeadlessException {
103 if (GraphicsEnvironment.isHeadless()) {
104 throw new HeadlessException();
105 }
106 s.defaultReadObject();
107 }
108
109 /**
110 * Sets this applet's stub. This is done automatically by the system.
111 * <p>If there is a security manager, its {@code checkPermission}
112 * method is called with the
113 * {@code AWTPermission("setAppletStub")}
114 * permission if a stub has already been set.
115 * @param stub the new stub.
116 * @exception SecurityException if the caller cannot set the stub
117 */
118 public final void setStub(AppletStub stub) {
119 if (this.stub != null) {
120 SecurityManager s = System.getSecurityManager();
121 if (s != null) {
122 s.checkPermission(new AWTPermission("setAppletStub"));
123 }
124 }
125 this.stub = stub;
126 }
127
128 /**
129 * Determines if this applet is active. An applet is marked active
130 * just before its {@code start} method is called. It becomes
131 * inactive just before its {@code stop} method is called.
132 *
133 * @return {@code true} if the applet is active;
134 * {@code false} otherwise.
135 * @see java.applet.Applet#start()
136 * @see java.applet.Applet#stop()
137 */
138 public boolean isActive() {
139 if (stub != null) {
140 return stub.isActive();
141 } else { // If stub field not filled in, applet never active
142 return false;
143 }
144 }
145
146 /**
147 * Gets the URL of the document in which this applet is embedded.
148 * For example, suppose an applet is contained
149 * within the document:
150 * <blockquote><pre>
151 * http://www.oracle.com/technetwork/java/index.html
152 * </pre></blockquote>
153 * The document base is:
154 * <blockquote><pre>
155 * http://www.oracle.com/technetwork/java/index.html
156 * </pre></blockquote>
157 *
158 * @return the {@link java.net.URL} of the document that contains this
159 * applet.
160 * @see java.applet.Applet#getCodeBase()
161 */
162 public URL getDocumentBase() {
163 return stub.getDocumentBase();
164 }
165
166 /**
167 * Gets the base URL. This is the URL of the directory which contains this applet.
168 *
169 * @return the base {@link java.net.URL} of
170 * the directory which contains this applet.
171 * @see java.applet.Applet#getDocumentBase()
172 */
173 public URL getCodeBase() {
174 return stub.getCodeBase();
175 }
176
177 /**
178 * Returns the value of the named parameter in the HTML tag. For
179 * example, if this applet is specified as
180 * <blockquote><pre>
181 * <applet code="Clock" width=50 height=50>
182 * <param name=Color value="blue">
183 * </applet>
184 * </pre></blockquote>
185 * <p>
186 * then a call to {@code getParameter("Color")} returns the
187 * value {@code "blue"}.
188 * <p>
189 * The {@code name} argument is case insensitive.
190 *
191 * @param name a parameter name.
192 * @return the value of the named parameter,
193 * or {@code null} if not set.
194 */
195 public String getParameter(String name) {
196 return stub.getParameter(name);
197 }
198
199 /**
200 * Determines this applet's context, which allows the applet to
201 * query and affect the environment in which it runs.
202 * <p>
203 * This environment of an applet represents the document that
204 * contains the applet.
205 *
206 * @return the applet's context.
207 */
208 public AppletContext getAppletContext() {
209 return stub.getAppletContext();
210 }
211
212 /**
213 * Requests that this applet be resized.
214 *
215 * @param width the new requested width for the applet.
216 * @param height the new requested height for the applet.
217 */
218 @SuppressWarnings("deprecation")
219 public void resize(int width, int height) {
220 Dimension d = size();
221 if ((d.width != width) || (d.height != height)) {
222 super.resize(width, height);
223 if (stub != null) {
224 stub.appletResize(width, height);
225 }
226 }
227 }
228
229 /**
230 * Requests that this applet be resized.
231 *
232 * @param d an object giving the new width and height.
233 */
234 @SuppressWarnings("deprecation")
235 public void resize(Dimension d) {
236 resize(d.width, d.height);
237 }
238
239 /**
240 * Indicates if this container is a validate root.
241 * <p>
242 * {@code Applet} objects are the validate roots, and, therefore, they
243 * override this method to return {@code true}.
244 *
245 * @return {@code true}
246 * @since 1.7
247 * @see java.awt.Container#isValidateRoot
248 */
249 @Override
250 public boolean isValidateRoot() {
251 return true;
252 }
253
254 /**
255 * Requests that the argument string be displayed in the
256 * "status window". Many browsers and applet viewers
257 * provide such a window, where the application can inform users of
258 * its current state.
259 *
260 * @param msg a string to display in the status window.
261 */
262 public void showStatus(String msg) {
263 getAppletContext().showStatus(msg);
264 }
265
266 /**
267 * Returns an {@code Image} object that can then be painted on
268 * the screen. The {@code url} that is passed as an argument
269 * must specify an absolute URL.
270 * <p>
271 * This method always returns immediately, whether or not the image
272 * exists. When this applet attempts to draw the image on the screen,
273 * the data will be loaded. The graphics primitives that draw the
274 * image will incrementally paint on the screen.
275 *
276 * @param url an absolute URL giving the location of the image.
277 * @return the image at the specified URL.
278 * @see java.awt.Image
279 */
280 public Image getImage(URL url) {
281 return getAppletContext().getImage(url);
282 }
283
284 /**
285 * Returns an {@code Image} object that can then be painted on
286 * the screen. The {@code url} argument must specify an absolute
287 * URL. The {@code name} argument is a specifier that is
288 * relative to the {@code url} argument.
289 * <p>
290 * This method always returns immediately, whether or not the image
291 * exists. When this applet attempts to draw the image on the screen,
292 * the data will be loaded. The graphics primitives that draw the
293 * image will incrementally paint on the screen.
294 *
295 * @param url an absolute URL giving the base location of the image.
296 * @param name the location of the image, relative to the
297 * {@code url} argument.
298 * @return the image at the specified URL.
299 * @see java.awt.Image
300 */
301 public Image getImage(URL url, String name) {
302 try {
303 return getImage(new URL(url, name));
304 } catch (MalformedURLException e) {
305 return null;
306 }
307 }
308
309 /**
310 * Get an audio clip from the given URL.
311 *
312 * @param url points to the audio clip
313 * @return the audio clip at the specified URL.
314 *
315 * @since 1.2
316 */
317 public static final AudioClip newAudioClip(URL url) {
318 return new sun.applet.AppletAudioClip(url);
319 }
320
321 /**
322 * Returns the {@code AudioClip} object specified by the
323 * {@code URL} argument.
324 * <p>
325 * This method always returns immediately, whether or not the audio
326 * clip exists. When this applet attempts to play the audio clip, the
327 * data will be loaded.
328 *
329 * @param url an absolute URL giving the location of the audio clip.
330 * @return the audio clip at the specified URL.
331 * @see java.applet.AudioClip
332 */
333 public AudioClip getAudioClip(URL url) {
334 return getAppletContext().getAudioClip(url);
335 }
336
337 /**
338 * Returns the {@code AudioClip} object specified by the
339 * {@code URL} and {@code name} arguments.
340 * <p>
341 * This method always returns immediately, whether or not the audio
342 * clip exists. When this applet attempts to play the audio clip, the
343 * data will be loaded.
344 *
345 * @param url an absolute URL giving the base location of the
346 * audio clip.
347 * @param name the location of the audio clip, relative to the
348 * {@code url} argument.
349 * @return the audio clip at the specified URL.
350 * @see java.applet.AudioClip
351 */
352 public AudioClip getAudioClip(URL url, String name) {
353 try {
354 return getAudioClip(new URL(url, name));
355 } catch (MalformedURLException e) {
356 return null;
357 }
358 }
359
360 /**
361 * Returns information about this applet. An applet should override
362 * this method to return a {@code String} containing information
363 * about the author, version, and copyright of the applet.
364 * <p>
365 * The implementation of this method provided by the
366 * {@code Applet} class returns {@code null}.
367 *
368 * @return a string containing information about the author, version, and
369 * copyright of the applet.
370 */
371 public String getAppletInfo() {
372 return null;
373 }
374
375 /**
376 * Gets the locale of the applet. It allows the applet
377 * to maintain its own locale separated from the locale
378 * of the browser or appletviewer.
379 *
380 * @return the locale of the applet; if no locale has
381 * been set, the default locale is returned.
382 * @since 1.1
383 */
384 public Locale getLocale() {
385 Locale locale = super.getLocale();
386 if (locale == null) {
387 return Locale.getDefault();
388 }
389 return locale;
390 }
391
392 /**
393 * Returns information about the parameters that are understood by
394 * this applet. An applet should override this method to return an
395 * array of {@code Strings} describing these parameters.
396 * <p>
397 * Each element of the array should be a set of three
398 * {@code Strings} containing the name, the type, and a
399 * description. For example:
400 * <blockquote><pre>
401 * String pinfo[][] = {
402 * {"fps", "1-10", "frames per second"},
403 * {"repeat", "boolean", "repeat image loop"},
404 * {"imgs", "url", "images directory"}
405 * };
406 * </pre></blockquote>
407 * <p>
408 * The implementation of this method provided by the
409 * {@code Applet} class returns {@code null}.
410 *
411 * @return an array describing the parameters this applet looks for.
412 */
413 public String[][] getParameterInfo() {
414 return null;
415 }
416
417 /**
418 * Plays the audio clip at the specified absolute URL. Nothing
419 * happens if the audio clip cannot be found.
420 *
421 * @param url an absolute URL giving the location of the audio clip.
422 */
423 public void play(URL url) {
424 AudioClip clip = getAudioClip(url);
425 if (clip != null) {
426 clip.play();
427 }
428 }
429
430 /**
431 * Plays the audio clip given the URL and a specifier that is
432 * relative to it. Nothing happens if the audio clip cannot be found.
433 *
434 * @param url an absolute URL giving the base location of the
435 * audio clip.
436 * @param name the location of the audio clip, relative to the
437 * {@code url} argument.
438 */
439 public void play(URL url, String name) {
440 AudioClip clip = getAudioClip(url, name);
441 if (clip != null) {
442 clip.play();
443 }
444 }
445
446 /**
447 * Called by the browser or applet viewer to inform
448 * this applet that it has been loaded into the system. It is always
449 * called before the first time that the {@code start} method is
450 * called.
451 * <p>
452 * A subclass of {@code Applet} should override this method if
453 * it has initialization to perform. For example, an applet with
454 * threads would use the {@code init} method to create the
455 * threads and the {@code destroy} method to kill them.
456 * <p>
457 * The implementation of this method provided by the
458 * {@code Applet} class does nothing.
459 *
460 * @see java.applet.Applet#destroy()
461 * @see java.applet.Applet#start()
462 * @see java.applet.Applet#stop()
463 */
464 public void init() {
465 }
466
467 /**
468 * Called by the browser or applet viewer to inform
469 * this applet that it should start its execution. It is called after
470 * the {@code init} method and each time the applet is revisited
471 * in a Web page.
472 * <p>
473 * A subclass of {@code Applet} should override this method if
474 * it has any operation that it wants to perform each time the Web
475 * page containing it is visited. For example, an applet with
476 * animation might want to use the {@code start} method to
477 * resume animation, and the {@code stop} method to suspend the
478 * animation.
479 * <p>
480 * Note: some methods, such as {@code getLocationOnScreen}, can only
481 * provide meaningful results if the applet is showing. Because
482 * {@code isShowing} returns {@code false} when the applet's
483 * {@code start} is first called, methods requiring
484 * {@code isShowing} to return {@code true} should be called from
485 * a {@code ComponentListener}.
486 * <p>
487 * The implementation of this method provided by the
488 * {@code Applet} class does nothing.
489 *
490 * @see java.applet.Applet#destroy()
491 * @see java.applet.Applet#init()
492 * @see java.applet.Applet#stop()
493 * @see java.awt.Component#isShowing()
494 * @see java.awt.event.ComponentListener#componentShown(java.awt.event.ComponentEvent)
495 */
496 public void start() {
497 }
498
499 /**
500 * Called by the browser or applet viewer to inform
501 * this applet that it should stop its execution. It is called when
502 * the Web page that contains this applet has been replaced by
503 * another page, and also just before the applet is to be destroyed.
504 * <p>
505 * A subclass of {@code Applet} should override this method if
506 * it has any operation that it wants to perform each time the Web
507 * page containing it is no longer visible. For example, an applet
508 * with animation might want to use the {@code start} method to
509 * resume animation, and the {@code stop} method to suspend the
510 * animation.
511 * <p>
512 * The implementation of this method provided by the
513 * {@code Applet} class does nothing.
514 *
515 * @see java.applet.Applet#destroy()
516 * @see java.applet.Applet#init()
517 */
518 public void stop() {
519 }
520
521 /**
522 * Called by the browser or applet viewer to inform
523 * this applet that it is being reclaimed and that it should destroy
524 * any resources that it has allocated. The {@code stop} method
525 * will always be called before {@code destroy}.
526 * <p>
527 * A subclass of {@code Applet} should override this method if
528 * it has any operation that it wants to perform before it is
529 * destroyed. For example, an applet with threads would use the
530 * {@code init} method to create the threads and the
531 * {@code destroy} method to kill them.
532 * <p>
533 * The implementation of this method provided by the
534 * {@code Applet} class does nothing.
535 *
536 * @see java.applet.Applet#init()
537 * @see java.applet.Applet#start()
538 * @see java.applet.Applet#stop()
539 */
540 public void destroy() {
541 }
542
543 //
544 // Accessibility support
545 //
546
547 AccessibleContext accessibleContext = null;
548
549 /**
550 * Gets the AccessibleContext associated with this Applet.
551 * For applets, the AccessibleContext takes the form of an
552 * AccessibleApplet.
553 * A new AccessibleApplet instance is created if necessary.
554 *
555 * @return an AccessibleApplet that serves as the
556 * AccessibleContext of this Applet
557 * @since 1.3
558 */
559 public AccessibleContext getAccessibleContext() {
560 if (accessibleContext == null) {
561 accessibleContext = new AccessibleApplet();
562 }
563 return accessibleContext;
564 }
565
566 /**
567 * This class implements accessibility support for the
568 * {@code Applet} class. It provides an implementation of the
569 * Java Accessibility API appropriate to applet user-interface elements.
570 * @since 1.3
571 */
572 protected class AccessibleApplet extends AccessibleAWTPanel {
573
574 private static final long serialVersionUID = 8127374778187708896L;
575
576 /**
577 * Get the role of this object.
578 *
579 * @return an instance of AccessibleRole describing the role of the
580 * object
581 */
582 public AccessibleRole getAccessibleRole() {
583 return AccessibleRole.FRAME;
584 }
585
586 /**
587 * Get the state of this object.
588 *
589 * @return an instance of AccessibleStateSet containing the current
590 * state set of the object
591 * @see AccessibleState
592 */
593 public AccessibleStateSet getAccessibleStateSet() {
594 AccessibleStateSet states = super.getAccessibleStateSet();
595 states.add(AccessibleState.ACTIVE);
596 return states;
597 }
598
599 }
600 }