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