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:  import javax.sound.sampled.AudioSystem;
 58:  import javax.sound.sampled.Clip;
 59:  import javax.sound.sampled.LineUnavailableException;
 60:  import javax.sound.sampled.UnsupportedAudioFileException;
 61: 
 62:  /**
 63:  * This is the base applet class. An applet is a Java program that
 64:  * runs inside a web browser or other applet viewer in a restricted
 65:  * environment.
 66:  *
 67:  * <p>To be useful, a subclass should override at least start(). Also useful
 68:  * are init, stop, and destroy for control purposes, and getAppletInfo and
 69:  * getParameterInfo for descriptive purposes.
 70:  *
 71:  * @author Aaron M. Renn (arenn@urbanophile.com)
 72:  * @author Eric Blake (ebb9@email.byu.edu)
 73:  * @since 1.0
 74:  * @status updated to 1.4
 75:  */
 76:  public class Applet extends Panel
 77: {
 78:  /**
 79:  * Compatible with JDK 1.0+.
 80:  */
 81:  private static final long serialVersionUID = -5836846270535785031L;
 82: 
 83:  /** The applet stub for this applet. */
 84:  private transient AppletStub stub;
 85: 
 86:  /** Some applets call setSize in their constructors. In that case,
 87:  these fields are used to store width and height values until a
 88:  stub is set. */
 89:  private transient int width;
 90:  private transient int height;
 91: 
 92:  /**
 93:  * The accessibility context for this applet.
 94:  *
 95:  * @serial the accessibleContext for this
 96:  * @since 1.2
 97:  */
 98:  private AccessibleContext accessibleContext;
 99: 
 100:  /**
 101:  * Default constructor for subclasses.
 102:  *
 103:  * @throws HeadlessException if in a headless environment
 104:  */
 105:  public Applet()
 106:  {
 107:  if (GraphicsEnvironment.isHeadless())
 108:  throw new HeadlessException();
 109:  }
 110: 
 111:  /**
 112:  * The browser calls this method to set the applet's stub, which is the
 113:  * low level interface to the browser. Manually setting this to null is
 114:  * asking for problems down the road.
 115:  *
 116:  * @param stub the applet stub for this applet
 117:  */
 118:  public final void setStub(AppletStub stub)
 119:  {
 120:  this.stub = stub;
 121: 
 122:  if (width != 0 && height != 0)
 123:  stub.appletResize (width, height);
 124:  }
 125: 
 126:  /**
 127:  * Tests whether or not this applet is currently active. An applet is active
 128:  * just before the browser invokes start(), and becomes inactive just
 129:  * before the browser invokes stop().
 130:  *
 131:  * @return <code>true</code> if this applet is active
 132:  */
 133:  public boolean isActive()
 134:  {
 135:  return stub.isActive();
 136:  }
 137: 
 138:  /**
 139:  * Returns the basename URL of the document this applet is embedded in. This
 140:  * is everything up to the final '/'.
 141:  *
 142:  * @return the URL of the document this applet is embedded in
 143:  * @see #getCodeBase()
 144:  */
 145:  public URL getDocumentBase()
 146:  {
 147:  return stub.getDocumentBase();
 148:  }
 149: 
 150:  /**
 151:  * Returns the URL of the code base for this applet.
 152:  *
 153:  * @return the URL of the code base for this applet
 154:  */
 155:  public URL getCodeBase()
 156:  {
 157:  return stub.getCodeBase();
 158:  }
 159: 
 160:  /**
 161:  * Returns the value of the specified parameter that was specified in
 162:  * the <code>&lt;APPLET&gt;</code> tag for this applet.
 163:  *
 164:  * @param name the parameter name
 165:  * @return the parameter value, or null if the parameter does not exist
 166:  * @throws NullPointerException if name is null
 167:  */
 168:  public String getParameter(String name)
 169:  {
 170:  return stub.getParameter(name);
 171:  }
 172: 
 173:  /**
 174:  * Returns the applet context for this applet.
 175:  *
 176:  * @return the applet context for this applet
 177:  */
 178:  public AppletContext getAppletContext()
 179:  {
 180:  return stub.getAppletContext();
 181:  }
 182: 
 183:  /**
 184:  * Requests that the applet window for this applet be resized.
 185:  *
 186:  * @param width the new width in pixels
 187:  * @param height the new height in pixels
 188:  */
 189:  public void resize(int width, int height)
 190:  {
 191:  if (stub == null)
 192:  {
 193:  this.width = width;
 194:  this.height = height;
 195:  }
 196:  else
 197:  stub.appletResize(width, height);
 198:  }
 199: 
 200:  /**
 201:  * Requests that the applet window for this applet be resized.
 202:  *
 203:  * @param dim the requested dimensions
 204:  * @throws NullPointerException if dim is null
 205:  */
 206:  public void resize(Dimension dim)
 207:  {
 208:  resize(dim.width, dim.height);
 209:  }
 210: 
 211:  /**
 212:  * Displays the specified message in the status window if that window
 213:  * exists.
 214:  *
 215:  * @param message the status message, may be null
 216:  */
 217:  public void showStatus(String message)
 218:  {
 219:  getAppletContext().showStatus(message);
 220:  }
 221: 
 222:  /**
 223:  * Returns an image from the specified URL. Note that the image is not
 224:  * actually retrieved until the applet attempts to display it, so this
 225:  * method returns immediately.
 226:  *
 227:  * @param url the URL of the image
 228:  * @return the retrieved image
 229:  * @throws NullPointerException if url is null
 230:  */
 231:  public Image getImage(URL url)
 232:  {
 233:  return getAppletContext().getImage(url);
 234:  }
 235: 
 236:  /**
 237:  * Returns an image from the specified absolute URL, and relative path
 238:  * from that URL. Note that the image is not actually retrieved until the
 239:  * applet attempts to display it, so this method returns immediately.
 240:  * This calls <code>getImage(new URL(url, name))</code>, but if building
 241:  * the new URL fails, this returns null.
 242:  *
 243:  * @param url the base URL of the image
 244:  * @param name the name of the image relative to the URL
 245:  * @return the retrieved image, or null on failure
 246:  * @see #getImage(URL)
 247:  */
 248:  public Image getImage(URL url, String name)
 249:  {
 250:  try
 251:  {
 252:  return getImage(new URL(url, name));
 253:  }
 254:  catch (MalformedURLException e)
 255:  {
 256:  return null;
 257:  }
 258:  }
 259: 
 260:  /**
 261:  * Returns an audio clip from the specified URL. This clip is not tied to
 262:  * any particular applet.
 263:  *
 264:  * @param url the URL of the audio clip
 265:  * @return the retrieved audio clip
 266:  * @throws NullPointerException if url is null
 267:  * @see #getAudioClip(URL)
 268:  * @since 1.2
 269:  */
 270:  public static final AudioClip newAudioClip(URL url)
 271:  {
 272:  return new URLAudioClip(url);
 273:  }
 274: 
 275:  /**
 276:  * Returns an audio clip from the specified URL. Note that the clip is not
 277:  * actually retrieved until the applet attempts to play it, so this method
 278:  * returns immediately.
 279:  *
 280:  * @param url the URL of the audio clip
 281:  * @return the retrieved audio clip
 282:  * @throws NullPointerException if url is null
 283:  */
 284:  public AudioClip getAudioClip(URL url)
 285:  {
 286:  return getAppletContext().getAudioClip(url);
 287:  }
 288: 
 289:  /**
 290:  * Returns an audio clip from the specified absolute URL, and relative path
 291:  * from that URL. Note that the clip is not actually retrieved until the
 292:  * applet attempts to play it, so this method returns immediately. This
 293:  * calls <code>getAudioClip(new URL(url, name))</code>, but if building
 294:  * the new URL fails, this returns null.
 295:  *
 296:  * @param url the base URL of the audio clip
 297:  * @param name the name of the clip relative to the URL
 298:  * @return the retrieved audio clip, or null on failure
 299:  * @see #getAudioClip(URL)
 300:  */
 301:  public AudioClip getAudioClip(URL url, String name)
 302:  {
 303:  try
 304:  {
 305:  return getAudioClip(new URL(url, name));
 306:  }
 307:  catch (MalformedURLException e)
 308:  {
 309:  return null;
 310:  }
 311:  }
 312: 
 313:  /**
 314:  * Returns a descriptive string with applet defined information. The
 315:  * implementation in this class returns <code>null</code>, so subclasses
 316:  * must override to return information.
 317:  *
 318:  * @return a string describing the author, version, and applet copyright
 319:  */
 320:  public String getAppletInfo()
 321:  {
 322:  return null;
 323:  }
 324: 
 325:  /**
 326:  * Returns the locale for this applet, if it has been set. If no applet
 327:  * specific locale has been set, the default locale is returned.
 328:  *
 329:  * @return the locale for this applet
 330:  * @see Component#setLocale(Locale)
 331:  * @since 1.1
 332:  */
 333:  public Locale getLocale()
 334:  {
 335:  return super.getLocale();
 336:  }
 337: 
 338:  /**
 339:  * Returns a list of parameters this applet supports. Each element of
 340:  * the outer array is an array of three strings with the name of the
 341:  * parameter, the data type or valid values, and a description. This
 342:  * method is optional and the default implementation returns null.
 343:  *
 344:  * @return the list of parameters supported by this applet
 345:  */
 346:  public String[][] getParameterInfo()
 347:  {
 348:  return null;
 349:  }
 350: 
 351:  /**
 352:  * Loads and plays the audio clip pointed to by the specified URL. This does
 353:  * nothing if the URL does not point to a valid audio clip.
 354:  *
 355:  * @param url the URL of the audio clip
 356:  * @throws NullPointerException if url is null
 357:  * @see #getAudioClip(URL)
 358:  */
 359:  public void play(URL url)
 360:  {
 361:  AudioClip ac = getAudioClip(url);
 362:  try
 363:  {
 364:  ac.play();
 365:  }
 366:  catch (Exception ignored)
 367:  {
 368:  }
 369:  }
 370: 
 371:  /**
 372:  * Loads and plays the audio clip pointed to by the specified absolute URL,
 373:  * and relative path from that URL. This does nothing if the URL cannot be
 374:  * constructed, or if it does not point to a valid audio clip.
 375:  *
 376:  * @param url the base URL of the audio clip
 377:  * @param name the name of the audio clip relative to the URL
 378:  * @see #getAudioClip(URL, String)
 379:  * @see #play(URL)
 380:  */
 381:  public void play(URL url, String name)
 382:  {
 383:  try
 384:  {
 385:  getAudioClip(url, name).play();
 386:  }
 387:  catch (Exception ignored)
 388:  {
 389:  }
 390:  }
 391: 
 392:  /**
 393:  * This method is called when the applet is first loaded, before start().
 394:  * The default implementation does nothing; override to do any one-time
 395:  * initialization.
 396:  *
 397:  * @see #start()
 398:  * @see #stop()
 399:  * @see #destroy()
 400:  */
 401:  public void init()
 402:  {
 403:  }
 404: 
 405:  /**
 406:  * This method is called when the applet should start running. This is
 407:  * normally each time a web page containing it is loaded. The default
 408:  * implemention does nothing; override for your applet to be useful.
 409:  *
 410:  * @see #init()
 411:  * @see #stop()
 412:  * @see #destroy()
 413:  */
 414:  public void start()
 415:  {
 416:  }
 417: 
 418:  /**
 419:  * This method is called when the applet should stop running. This is
 420:  * normally when the next web page is loaded. The default implementation
 421:  * does nothing; override for your applet to stop using resources when
 422:  * it is no longer visible, but may be restarted soon.
 423:  *
 424:  * @see #init()
 425:  * @see #start()
 426:  * @see #destroy()
 427:  */
 428:  public void stop()
 429:  {
 430:  }
 431: 
 432:  /**
 433:  * This method is called when the applet is being unloaded. The default
 434:  * implementation does nothing; override for your applet to clean up
 435:  * resources on exit.
 436:  *
 437:  * @see #init()
 438:  * @see #start()
 439:  * @see #stop()
 440:  */
 441:  public void destroy()
 442:  {
 443:  }
 444: 
 445:  /**
 446:  * Gets the AccessibleContext associated with this applet, creating one if
 447:  * necessary. This always returns an instance of {@link AccessibleApplet}.
 448:  *
 449:  * @return the accessibility context of this applet
 450:  * @since 1.3
 451:  */
 452:  public AccessibleContext getAccessibleContext()
 453:  {
 454:  if (accessibleContext == null)
 455:  accessibleContext = new AccessibleApplet();
 456:  return accessibleContext;
 457:  }
 458: 
 459:  /**
 460:  * Read an applet from an object stream. This checks for a headless
 461:  * environment, then does the normal read.
 462:  *
 463:  * @param s the stream to read from
 464:  * @throws ClassNotFoundException if a class is not found
 465:  * @throws IOException if deserialization fails
 466:  * @throws HeadlessException if this is a headless environment
 467:  * @see GraphicsEnvironment#isHeadless()
 468:  * @since 1.4
 469:  */
 470:  private void readObject(ObjectInputStream s)
 471:  throws ClassNotFoundException, IOException
 472:  {
 473:  if (GraphicsEnvironment.isHeadless())
 474:  throw new HeadlessException();
 475:  s.defaultReadObject();
 476:  }
 477: 
 478:  /**
 479:  * This class provides accessibility support for Applets, and is the
 480:  * runtime type returned by {@link #getAccessibleContext()}.
 481:  *
 482:  * @author Eric Blake (ebb9@email.byu.edu)
 483:  * @since 1.3
 484:  */
 485:  protected class AccessibleApplet extends AccessibleAWTPanel
 486:  {
 487:  /**
 488:  * Compatible with JDK 1.4+.
 489:  */
 490:  private static final long serialVersionUID = 8127374778187708896L;
 491: 
 492:  /**
 493:  * The default constructor.
 494:  */
 495:  protected AccessibleApplet()
 496:  {
 497:  }
 498: 
 499:  /**
 500:  * Get the role of this accessible object, a frame.
 501:  *
 502:  * @return the role of the object
 503:  * @see AccessibleRole#FRAME
 504:  */
 505:  public AccessibleRole getAccessibleRole()
 506:  {
 507:  return AccessibleRole.FRAME;
 508:  }
 509: 
 510:  /**
 511:  * Get the state set of this accessible object. In addition to the default
 512:  * states of a Component, the applet can also be active.
 513:  *
 514:  * @return the role of the object
 515:  * @see AccessibleState
 516:  */
 517:  public AccessibleStateSet getAccessibleStateSet()
 518:  {
 519:  AccessibleStateSet s = super.getAccessibleStateSet();
 520:  if (isActive())
 521:  s.add(AccessibleState.ACTIVE);
 522:  return s;
 523:  }
 524:  } // class AccessibleApplet
 525: 
 526:  private static class URLAudioClip implements AudioClip
 527:  {
 528:  // The URL we will try to play.
 529:  // This is null if we have already tried to create an
 530:  // audio input stream from this URL.
 531:  private URL url;
 532: 
 533:  // The real audio clip. This is null before the URL is read,
 534:  // and might be null afterward if we were unable to read the URL
 535:  // for some reason.
 536:  private Clip clip;
 537:  
 538:  public URLAudioClip(URL url)
 539:  {
 540:  this.url = url;
 541:  }
 542: 
 543:  private synchronized Clip getClip()
 544:  {
 545:  if (url == null)
 546:  return clip;
 547:  try
 548:  {
 549:  clip = AudioSystem.getClip();
 550:  clip.open(AudioSystem.getAudioInputStream(url));
 551:  }
 552:  catch (LineUnavailableException _)
 553:  {
 554:  // Ignore.
 555:  }
 556:  catch (IOException _)
 557:  {
 558:  // Ignore.
 559:  }
 560:  catch (UnsupportedAudioFileException _)
 561:  {
 562:  // Ignore.
 563:  }
 564:  url = null;
 565:  return clip;
 566:  }
 567: 
 568:  public void loop()
 569:  {
 570:  Clip myclip = getClip();
 571:  if (myclip != null)
 572:  myclip.loop(Clip.LOOP_CONTINUOUSLY);
 573:  }
 574: 
 575:  public void play()
 576:  {
 577:  Clip myclip = getClip();
 578:  if (myclip != null)
 579:  myclip.start();
 580:  }
 581: 
 582:  public void stop()
 583:  {
 584:  Clip myclip = getClip();
 585:  if (myclip != null)
 586:  {
 587:  myclip.stop();
 588:  myclip.setFramePosition(0);
 589:  }
 590:  }
 591:  }
 592: } // class Applet