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      * &lt;applet code="Clock" width=50 height=50&gt;
 184      * &lt;param name=Color value="blue"&gt;
 185      * &lt;/applet&gt;
 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 }