Source for java.applet.Applet

   1: /* Applet.java -- Java base applet class
   2:    Copyright (C) 1999, 2002, 2004, 2005  Free Software Foundation, Inc.
   3: 
   4: This file is part of GNU Classpath.
   5: 
   6: GNU Classpath is free software; you can redistribute it and/or modify
   7: it under the terms of the GNU General Public License as published by
   8: the Free Software Foundation; either version 2, or (at your option)
   9: any later version.
  10: 
  11: GNU Classpath is distributed in the hope that it will be useful, but
  12: WITHOUT ANY WARRANTY; without even the implied warranty of
  13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14: General Public License for more details.
  15: 
  16: You should have received a copy of the GNU General Public License
  17: along with GNU Classpath; see the file COPYING.  If not, write to the
  18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19: 02110-1301 USA.
  20: 
  21: Linking this library statically or dynamically with other modules is
  22: making a combined work based on this library.  Thus, the terms and
  23: conditions of the GNU General Public License cover the whole
  24: combination.
  25: 
  26: As a special exception, the copyright holders of this library give you
  27: permission to link this library with independent modules to produce an
  28: executable, regardless of the license terms of these independent
  29: modules, and to copy and distribute the resulting executable under
  30: terms of your choice, provided that you also meet, for each linked
  31: independent module, the terms and conditions of the license of that
  32: module.  An independent module is a module which is not derived from
  33: or based on this library.  If you modify this library, you may extend
  34: this exception to your version of the library, but you are not
  35: obligated to do so.  If you do not wish to do so, delete this
  36: exception statement from your version. */
  37: 
  38: 
  39: package java.applet;
  40: 
  41: import java.awt.Component;
  42: import java.awt.Dimension;
  43: import java.awt.GraphicsEnvironment;
  44: import java.awt.HeadlessException;
  45: import java.awt.Image;
  46: import java.awt.Panel;
  47: import java.io.IOException;
  48: import java.io.ObjectInputStream;
  49: import java.net.MalformedURLException;
  50: import java.net.URL;
  51: import java.util.Locale;
  52: 
  53: import javax.accessibility.AccessibleContext;
  54: import javax.accessibility.AccessibleRole;
  55: import javax.accessibility.AccessibleState;
  56: import javax.accessibility.AccessibleStateSet;
  57: 
  58: /**
  59:  * This is the base applet class.  An applet is a Java program that
  60:  * runs inside a web browser or other applet viewer in a restricted
  61:  * environment.
  62:  *
  63:  * <p>To be useful, a subclass should override at least start(). Also useful
  64:  * are init, stop, and destroy for control purposes, and getAppletInfo and
  65:  * getParameterInfo for descriptive purposes.
  66:  *
  67:  * @author Aaron M. Renn (arenn@urbanophile.com)
  68:  * @author Eric Blake (ebb9@email.byu.edu)
  69:  * @since 1.0
  70:  * @status updated to 1.4
  71:  */
  72: public class Applet extends Panel
  73: {
  74:   /**
  75:    * Compatible with JDK 1.0+.
  76:    */
  77:   private static final long serialVersionUID = -5836846270535785031L;
  78: 
  79:   /** The applet stub for this applet. */
  80:   private transient AppletStub stub;
  81: 
  82:   /** Some applets call setSize in their constructors.  In that case,
  83:       these fields are used to store width and height values until a
  84:       stub is set. */
  85:   private transient int width;
  86:   private transient int height;
  87: 
  88:   /**
  89:    * The accessibility context for this applet.
  90:    *
  91:    * @serial the accessibleContext for this
  92:    * @since 1.2
  93:    */
  94:   private AccessibleContext accessibleContext;
  95: 
  96:   /**
  97:    * Default constructor for subclasses.
  98:    *
  99:    * @throws HeadlessException if in a headless environment
 100:    */
 101:   public Applet()
 102:   {
 103:     if (GraphicsEnvironment.isHeadless())
 104:       throw new HeadlessException();
 105:   }
 106: 
 107:   /**
 108:    * The browser calls this method to set the applet's stub, which is the
 109:    * low level interface to the browser. Manually setting this to null is
 110:    * asking for problems down the road.
 111:    *
 112:    * @param stub the applet stub for this applet
 113:    */
 114:   public final void setStub(AppletStub stub)
 115:   {
 116:     this.stub = stub;
 117: 
 118:     if (width != 0 && height != 0)
 119:       stub.appletResize (width, height);
 120:   }
 121: 
 122:   /**
 123:    * Tests whether or not this applet is currently active. An applet is active
 124:    * just before the browser invokes start(), and becomes inactive just
 125:    * before the browser invokes stop().
 126:    *
 127:    * @return <code>true</code> if this applet is active
 128:    */
 129:   public boolean isActive()
 130:   {
 131:     return stub.isActive();
 132:   }
 133: 
 134:   /**
 135:    * Returns the basename URL of the document this applet is embedded in. This
 136:    * is everything up to the final '/'.
 137:    *
 138:    * @return the URL of the document this applet is embedded in
 139:    * @see #getCodeBase()
 140:    */
 141:   public URL getDocumentBase()
 142:   {
 143:     return stub.getDocumentBase();
 144:   }
 145: 
 146:   /**
 147:    * Returns the URL of the code base for this applet.
 148:    *
 149:    * @return the URL of the code base for this applet
 150:    */
 151:   public URL getCodeBase()
 152:   {
 153:     return stub.getCodeBase();
 154:   }
 155: 
 156:   /**
 157:    * Returns the value of the specified parameter that was specified in
 158:    * the <code>&lt;APPLET&gt;</code> tag for this applet.
 159:    *
 160:    * @param name the parameter name
 161:    * @return the parameter value, or null if the parameter does not exist
 162:    * @throws NullPointerException if name is null
 163:    */
 164:   public String getParameter(String name)
 165:   {
 166:     return stub.getParameter(name);
 167:   }
 168: 
 169:   /**
 170:    * Returns the applet context for this applet.
 171:    *
 172:    * @return the applet context for this applet
 173:    */
 174:   public AppletContext getAppletContext()
 175:   {
 176:     return stub.getAppletContext();
 177:   }
 178: 
 179:   /**
 180:    * Requests that the applet window for this applet be resized.
 181:    *
 182:    * @param width the new width in pixels
 183:    * @param height the new height in pixels
 184:    */
 185:   public void resize(int width, int height)
 186:   {
 187:     if (stub == null)
 188:       {
 189:         this.width = width;
 190:         this.height = height;
 191:       }
 192:     else
 193:       stub.appletResize(width, height);
 194:   }
 195: 
 196:   /**
 197:    * Requests that the applet window for this applet be resized.
 198:    *
 199:    * @param dim the requested dimensions
 200:    * @throws NullPointerException if dim is null
 201:    */
 202:   public void resize(Dimension dim)
 203:   {
 204:     resize(dim.width, dim.height);
 205:   }
 206: 
 207:   /**
 208:    * Displays the specified message in the status window if that window
 209:    * exists.
 210:    *
 211:    * @param message the status message, may be null
 212:    */
 213:   public void showStatus(String message)
 214:   {
 215:     getAppletContext().showStatus(message);
 216:   }
 217: 
 218:   /**
 219:    * Returns an image from the specified URL.  Note that the image is not
 220:    * actually retrieved until the applet attempts to display it, so this
 221:    * method returns immediately.
 222:    *
 223:    * @param url the URL of the image
 224:    * @return the retrieved image
 225:    * @throws NullPointerException if url is null
 226:    */
 227:   public Image getImage(URL url)
 228:   {
 229:     return getAppletContext().getImage(url);
 230:   }
 231: 
 232:   /**
 233:    * Returns an image from the specified absolute URL, and relative path
 234:    * from that URL.  Note that the image is not actually retrieved until the
 235:    * applet attempts to display it, so this method returns immediately.
 236:    * This calls <code>getImage(new URL(url, name))</code>, but if building
 237:    * the new URL fails, this returns null.
 238:    *
 239:    * @param url the base URL of the image
 240:    * @param name the name of the image relative to the URL
 241:    * @return the retrieved image, or null on failure
 242:    * @see #getImage(URL)
 243:    */
 244:   public Image getImage(URL url, String name)
 245:   {
 246:     try
 247:       {
 248:     return getImage(new URL(url, name));
 249:       }
 250:     catch (MalformedURLException e)
 251:       {
 252:     return null;
 253:       }
 254:   }
 255: 
 256:   /**
 257:    * Returns an audio clip from the specified URL. This clip is not tied to
 258:    * any particular applet.
 259:    *
 260:    * XXX Classpath does not yet implement this.
 261:    *
 262:    * @param url the URL of the audio clip
 263:    * @return the retrieved audio clip
 264:    * @throws NullPointerException if url is null
 265:    * @see #getAudioClip(URL)
 266:    * @since 1.2
 267:    */
 268:   public static final AudioClip newAudioClip(URL url)
 269:   {
 270:     // This requires an implementation of AudioClip in gnu.java.applet.
 271:     throw new Error("Not implemented");
 272:   }
 273: 
 274:   /**
 275:    * Returns an audio clip from the specified URL. Note that the clip is not
 276:    * actually retrieved until the applet attempts to play it, so this method
 277:    * returns immediately.
 278:    *
 279:    * @param url the URL of the audio clip
 280:    * @return the retrieved audio clip
 281:    * @throws NullPointerException if url is null
 282:    */
 283:   public AudioClip getAudioClip(URL url)
 284:   {
 285:     return getAppletContext().getAudioClip(url);
 286:   }
 287: 
 288:   /**
 289:    * Returns an audio clip from the specified absolute URL, and relative path
 290:    * from that URL.  Note that the clip is not actually retrieved until the
 291:    * applet attempts to play it, so this method returns immediately. This
 292:    * calls <code>getAudioClip(new URL(url, name))</code>, but if building
 293:    * the new URL fails, this returns null.
 294:    *
 295:    * @param url the base URL of the audio clip
 296:    * @param name the name of the clip relative to the URL
 297:    * @return the retrieved audio clip, or null on failure
 298:    * @see #getAudioClip(URL)
 299:    */
 300:   public AudioClip getAudioClip(URL url, String name)
 301:   {
 302:     try
 303:       {
 304:     return getAudioClip(new URL(url, name));
 305:       }
 306:     catch (MalformedURLException e)
 307:       {
 308:     return null;
 309:       }
 310:   }
 311: 
 312:   /**
 313:    * Returns a descriptive string with applet defined information.  The
 314:    * implementation in this class returns <code>null</code>, so subclasses
 315:    * must override to return information.
 316:    *
 317:    * @return a string describing the author, version, and applet copyright
 318:    */
 319:   public String getAppletInfo()
 320:   {
 321:     return null;
 322:   }
 323: 
 324:   /**
 325:    * Returns the locale for this applet, if it has been set.  If no applet
 326:    * specific locale has been set, the default locale is returned.
 327:    *
 328:    * @return the locale for this applet
 329:    * @see Component#setLocale(Locale)
 330:    * @since 1.1
 331:    */
 332:   public Locale getLocale()
 333:   {
 334:     return super.getLocale();
 335:   }
 336: 
 337:   /**
 338:    * Returns a list of parameters this applet supports.  Each element of
 339:    * the outer array is an array of three strings with the name of the
 340:    * parameter, the data type or valid values, and a description.  This
 341:    * method is optional and the default implementation returns null.
 342:    *
 343:    * @return the list of parameters supported by this applet
 344:    */
 345:   public String[][] getParameterInfo()
 346:   {
 347:     return null;
 348:   }
 349: 
 350:   /**
 351:    * Loads and plays the audio clip pointed to by the specified URL. This does
 352:    * nothing if the URL does not point to a valid audio clip.
 353:    *
 354:    * @param url the URL of the audio clip
 355:    * @throws NullPointerException if url is null
 356:    * @see #getAudioClip(URL)
 357:    */
 358:   public void play(URL url)
 359:   {
 360:     AudioClip ac = getAudioClip(url);
 361:     try
 362:       {
 363:     ac.play();
 364:       }
 365:     catch (Exception ignored)
 366:       {
 367:       }
 368:   }
 369: 
 370:   /**
 371:    * Loads and plays the audio clip pointed to by the specified absolute URL,
 372:    * and relative path from that URL. This does nothing if the URL cannot be
 373:    * constructed, or if it does not point to a valid audio clip.
 374:    *
 375:    * @param url the base URL of the audio clip
 376:    * @param name the name of the audio clip relative to the URL
 377:    * @see #getAudioClip(URL, String)
 378:    * @see #play(URL)
 379:    */
 380:   public void play(URL url, String name)
 381:   {
 382:     try
 383:       {
 384:     getAudioClip(url, name).play();
 385:       }
 386:     catch (Exception ignored)
 387:       {
 388:       }
 389:   }
 390: 
 391:   /**
 392:    * This method is called when the applet is first loaded, before start().
 393:    * The default implementation does nothing; override to do any one-time
 394:    * initialization.
 395:    *
 396:    * @see #start()
 397:    * @see #stop()
 398:    * @see #destroy()
 399:    */
 400:   public void init()
 401:   {
 402:   }
 403: 
 404:   /**
 405:    * This method is called when the applet should start running.  This is
 406:    * normally each time a web page containing it is loaded.  The default
 407:    * implemention does nothing; override for your applet to be useful.
 408:    *
 409:    * @see #init()
 410:    * @see #stop()
 411:    * @see #destroy()
 412:    */
 413:   public void start()
 414:   {
 415:   }
 416: 
 417:   /**
 418:    * This method is called when the applet should stop running.  This is
 419:    * normally when the next web page is loaded.  The default implementation
 420:    * does nothing; override for your applet to stop using resources when
 421:    * it is no longer visible, but may be restarted soon.
 422:    *
 423:    * @see #init()
 424:    * @see #start()
 425:    * @see #destroy()
 426:    */
 427:   public void stop()
 428:   {
 429:   }
 430: 
 431:   /**
 432:    * This method is called when the applet is being unloaded.  The default
 433:    * implementation does nothing; override for your applet to clean up
 434:    * resources on exit.
 435:    *
 436:    * @see #init()
 437:    * @see #start()
 438:    * @see #stop()
 439:    */
 440:   public void destroy()
 441:   {
 442:   }
 443: 
 444:   /**
 445:    * Gets the AccessibleContext associated with this applet, creating one if
 446:    * necessary. This always returns an instance of {@link AccessibleApplet}.
 447:    *
 448:    * @return the accessibility context of this applet
 449:    * @since 1.3
 450:    */
 451:   public AccessibleContext getAccessibleContext()
 452:   {
 453:     if (accessibleContext == null)
 454:       accessibleContext = new AccessibleApplet();
 455:     return accessibleContext;
 456:   }
 457: 
 458:   /**
 459:    * Read an applet from an object stream. This checks for a headless
 460:    * environment, then does the normal read.
 461:    *
 462:    * @param s the stream to read from
 463:    * @throws ClassNotFoundException if a class is not found
 464:    * @throws IOException if deserialization fails
 465:    * @throws HeadlessException if this is a headless environment
 466:    * @see GraphicsEnvironment#isHeadless()
 467:    * @since 1.4
 468:    */
 469:   private void readObject(ObjectInputStream s)
 470:     throws ClassNotFoundException, IOException
 471:   {
 472:     if (GraphicsEnvironment.isHeadless())
 473:       throw new HeadlessException();
 474:     s.defaultReadObject();
 475:   }
 476: 
 477:   /**
 478:    * This class provides accessibility support for Applets, and is the
 479:    * runtime type returned by {@link #getAccessibleContext()}.
 480:    *
 481:    * @author Eric Blake (ebb9@email.byu.edu)
 482:    * @since 1.3
 483:    */
 484:   protected class AccessibleApplet extends AccessibleAWTPanel
 485:   {
 486:     /**
 487:      * Compatible with JDK 1.4+.
 488:      */
 489:     private static final long serialVersionUID = 8127374778187708896L;
 490: 
 491:     /**
 492:      * The default constructor.
 493:      */
 494:     protected AccessibleApplet()
 495:     {
 496:     }
 497: 
 498:     /**
 499:      * Get the role of this accessible object, a frame.
 500:      *
 501:      * @return the role of the object
 502:      * @see AccessibleRole#FRAME
 503:      */
 504:     public AccessibleRole getAccessibleRole()
 505:     {
 506:       return AccessibleRole.FRAME;
 507:     }
 508: 
 509:     /**
 510:      * Get the state set of this accessible object. In addition to the default
 511:      * states of a Component, the applet can also be active.
 512:      *
 513:      * @return the role of the object
 514:      * @see AccessibleState
 515:      */
 516:     public AccessibleStateSet getAccessibleStateSet()
 517:     {
 518:       AccessibleStateSet s = super.getAccessibleStateSet();
 519:       if (isActive())
 520:     s.add(AccessibleState.ACTIVE);
 521:       return s;
 522:     }
 523:   } // class AccessibleApplet
 524: } // class Applet