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