* java/applet/Applet.java, java/applet/AppletContext.java,

	java/applet/AppletStub.java, java/applet/AudioClip.java,
	java/awt/CardLayout.java,
	java/awt/ContainerOrderFocusTraversalPolicy.java,
	java/awt/Cursor.java, java/awt/Event.java, java/awt/Frame.java,
	java/awt/GridBagConstraints.java, java/awt/GridBagLayout.java,
	java/awt/GridLayout.java, java/awt/color/ColorSpace.java,
	java/awt/color/ICC_ColorSpace.java,
	java/awt/color/ICC_Profile.java,
	java/awt/color/ICC_ProfileGray.java,
	java/awt/color/ICC_ProfileRGB.java,
	java/awt/datatransfer/DataFlavor.java,
	java/awt/dnd/DragSourceContext.java, java/awt/dnd/DropTarget.java,
	java/awt/dnd/DropTargetContext.java, java/awt/event/KeyEvent.java:
	New versions from Classpath.
	* Makefile.in: Rebuilt.
	* Makefile.am (awt_java_source_files): Added ICC_ProfileGray and
	ICC_ProfileRGB.


git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@58964 138bc75d-0d04-0410-961f-82ee72b054a4

4 files changed, 535 insertions, 294 deletions

diff --git a/libjava/java/applet/Applet.java b/libjava/java/applet/Applet.java
index 8f9338ffd75..5990c6392da 100644
--- a/libjava/java/applet/Applet.java
+++ b/libjava/java/applet/Applet.java
@@ -1,23 +1,23 @@
 /* Applet.java -- Java base applet class
-   Copyright (C) 1999 Free Software Foundation, Inc.
- 
+   Copyright (C) 1999, 2002 Free Software Foundation, Inc.
+
 This file is part of GNU Classpath.
- 
+
 GNU Classpath is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2, or (at your option)
 any later version.
- 
+
 GNU Classpath is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.
- 
+
 You should have received a copy of the GNU General Public License
 along with GNU Classpath; see the file COPYING.  If not, write to the
 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 02111-1307 USA.
- 
+
 Linking this library statically or dynamically with other modules is
 making a combined work based on this library.  Thus, the terms and
 conditions of the GNU General Public License cover the whole
@@ -39,269 +39,469 @@ exception statement from your version. */
 package java.applet;
 
 import java.awt.Dimension;
+import java.awt.GraphicsEnvironment;
+import java.awt.HeadlessException;
 import java.awt.Image;
+import java.awt.Panel;
+import java.io.IOException;
+import java.io.ObjectInputStream;
+import java.net.MalformedURLException;
 import java.net.URL;
 import java.util.Locale;
+import javax.accessibility.AccessibleContext;
+import javax.accessibility.AccessibleRole;
+import javax.accessibility.AccessibleState;
+import javax.accessibility.AccessibleStateSet;
 
 /**
-  * This is the base applet class.  An applet is a Java program that
-  * runs inside a web browser or other applet viewer in a restricted
-  * environment.
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  */
-public class Applet extends java.awt.Panel implements java.io.Serializable
+ * This is the base applet class.  An applet is a Java program that
+ * runs inside a web browser or other applet viewer in a restricted
+ * environment.
+ *
+ * <p>To be useful, a subclass should override at least start(). Also useful
+ * are init, stop, and destroy for control purposes, and getAppletInfo and
+ * getParameterInfo for descriptive purposes.
+ *
+ * @author Aaron M. Renn <arenn@urbanophile.com>
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.0
+ * @status updated to 1.4
+ */
+public class Applet extends Panel
 {
-  // The applet stub for this applet
-  private AppletStub stub;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -5836846270535785031L;
+
+  /** The applet stub for this applet. */
+  private transient AppletStub stub;
+
+  /**
+   * The accessibility context for this applet.
+   *
+   * @serial the accessibleContext for this
+   * @since 1.2
+   */
+  private AccessibleContext accessibleContext;
+
+  /**
+   * Default constructor for subclasses.
+   *
+   * @throws HeadlessException if in a headless environment
+   */
+  public Applet()
+  {
+    if (GraphicsEnvironment.isHeadless())
+      throw new HeadlessException();
+  }
+
+  /**
+   * The browser calls this method to set the applet's stub, which is the
+   * low level interface to the browser. Manually setting this to null is
+   * asking for problems down the road.
+   *
+   * @param stub the applet stub for this applet
+   */
+  public final void setStub(AppletStub stub)
+  {
+    this.stub = stub;
+  }
 
   /**
-    * Default constructor for subclasses.
-    */
-  public Applet() {}
+   * Tests whether or not this applet is currently active. An applet is active
+   * just before the browser invokes start(), and becomes inactive just
+   * before the browser invokes stop().
+   *
+   * @return <code>true</code> if this applet is active
+   */
+  public boolean isActive()
+  {
+    return stub.isActive();
+  }
 
   /**
-    * Returns the URL of the document this applet is embedded in.
-    *
-    * @return The URL of the document this applet is embedded in.
-    */
+   * Returns the basename URL of the document this applet is embedded in. This
+   * is everything up to the final '/'.
+   *
+   * @return the URL of the document this applet is embedded in
+   * @see #getCodeBase()
+   */
   public URL getDocumentBase()
   {
-    return (stub.getDocumentBase ());
+    return stub.getDocumentBase();
   }
 
   /**
-    * Returns the URL of the code base for this applet.
-    *
-    * @return The URL of the code base for this applet.
-    */
+   * Returns the URL of the code base for this applet.
+   *
+   * @return the URL of the code base for this applet
+   */
   public URL getCodeBase()
   {
-    return (stub.getCodeBase ());
+    return stub.getCodeBase();
   }
 
   /**
-    * Returns the value of the specified parameter that was specified in 
-    * the &lt;APPLET&gt; tag for this applet.
-    *
-    * @param name The parameter name.
-    *
-    * @param value The parameter value, or <code>null</code> if the parameter
-    * does not exist.
-    */
+   * Returns the value of the specified parameter that was specified in
+   * the <code>&lt;APPLET&gt;</code> tag for this applet.
+   *
+   * @param name the parameter name
+   * @return the parameter value, or null if the parameter does not exist
+   * @throws NullPointerException if name is null
+   */
   public String getParameter(String name)
   {
-    return (stub.getParameter (name));
+    return stub.getParameter(name);
   }
 
   /**
-    * Returns the applet context for this applet.
-    *
-    * @return The applet context for this applet.
-    */
+   * Returns the applet context for this applet.
+   *
+   * @return the applet context for this applet
+   */
   public AppletContext getAppletContext()
   {
-    return (stub.getAppletContext ());
+    return stub.getAppletContext();
   }
 
   /**
-    * Tests whether or not this applet is currently active.
-    *
-    * @return <code>true</code> if this applet is active, <code>false</code>
-    * otherwise.
-    */
-  public boolean isActive()
+   * Requests that the applet window for this applet be resized.
+   *
+   * @param width the new width in pixels
+   * @param height the new height in pixels
+   */
+  public void resize(int width, int height)
   {
-    return (stub.isActive ());
+    stub.appletResize(width, height);
   }
 
   /**
-    * Requests that the applet window for this applet be resized.
-    *
-    * @param width The new width in pixels.
-    * @param height The new height in pixels.
-    */
-  public void resize(int width, int height)
+   * Requests that the applet window for this applet be resized.
+   *
+   * @param dim the requested dimensions
+   * @throws NullPointerException if dim is null
+   */
+  public void resize(Dimension dim)
   {
-    stub.appletResize (width, height);
+    resize(dim.width, dim.height);
   }
 
   /**
-    * Requests that the applet window for this applet be resized.
-    *
-    * @param dim The <code>Dimension</code> object with the requested
-    * width and height.
-    */
-  public void resize(Dimension dim)
+   * Displays the specified message in the status window if that window
+   * exists.
+   *
+   * @param message the status message, may be null
+   */
+  public void showStatus(String message)
+  {
+    getAppletContext().showStatus(message);
+  }
+
+  /**
+   * Returns an image from the specified URL.  Note that the image is not
+   * actually retrieved until the applet attempts to display it, so this
+   * method returns immediately.
+   *
+   * @param url the URL of the image
+   * @return the retrieved image
+   * @throws NullPointerException if url is null
+   */
+  public Image getImage(URL url)
   {
-    resize (dim.width, dim.height);
+    return getAppletContext().getImage(url);
   }
 
   /**
-    * Returns an audio clip from the specified URL.
-    *
-    * @param url The URL of the audio clip.
-    *
-    * @return The retrieved audio clip. 
-    */
+   * Returns an image from the specified absolute URL, and relative path
+   * from that URL.  Note that the image is not actually retrieved until the
+   * applet attempts to display it, so this method returns immediately.
+   * This calls <code>getImage(new URL(url, name))</code>, but if building
+   * the new URL fails, this returns null.
+   *
+   * @param url the base URL of the image
+   * @param name the name of the image relative to the URL
+   * @return the retrieved image, or null on failure
+   * @see #getImage(URL)
+   */
+  public Image getImage(URL url, String name)
+  {
+    try
+      {
+        return getImage(new URL(url, name));
+      }
+    catch (MalformedURLException e)
+      {
+        return null;
+      }
+  }
+
+  /**
+   * Returns an audio clip from the specified URL. This clip is not tied to
+   * any particular applet.
+   *
+   * XXX Classpath does not yet implement this.
+   *
+   * @param url the URL of the audio clip
+   * @return the retrieved audio clip
+   * @throws NullPointerException if url is null
+   * @see #getAudioClip(URL)
+   * @since 1.2
+   */
+  public static final AudioClip newAudioClip(URL url)
+  {
+    // This requires an implementation of AudioClip in gnu.java.applet.
+    throw new Error("Not implemented");
+  }
+
+  /**
+   * Returns an audio clip from the specified URL. Note that the clip is not
+   * actually retrieved until the applet attempts to play it, so this method
+   * returns immediately.
+   *
+   * @param url the URL of the audio clip
+   * @return the retrieved audio clip
+   * @throws NullPointerException if url is null
+   */
   public AudioClip getAudioClip(URL url)
   {
-    return (getAppletContext ().getAudioClip (url));
+    return getAppletContext().getAudioClip(url);
   }
 
   /**
-    * Returns an audio clip from the specified URL and name
-    *
-    * @param url The base URL of the audio clip.
-    * @param name The name of the clip relative to the URL.
-    *
-    * @return The retrieved audio clip. 
-    */
+   * Returns an audio clip from the specified absolute URL, and relative path
+   * from that URL.  Note that the clip is not actually retrieved until the
+   * applet attempts to play it, so this method returns immediately. This
+   * calls <code>getAudioClip(new URL(url, name))</code>, but if building
+   * the new URL fails, this returns null.
+   *
+   * @param url the base URL of the audio clip
+   * @param name the name of the clip relative to the URL
+   * @return the retrieved audio clip, or null on failure
+   * @see #getAudioClip(URL)
+   */
   public AudioClip getAudioClip(URL url, String name)
   {
     try
       {
-        return (getAppletContext ().getAudioClip (new URL (url.toExternalForm()
-                                                	   + name)));
+        return getAudioClip(new URL(url, name));
       }
-    catch(Exception e)
+    catch (MalformedURLException e)
       {
-        return (getAudioClip (url));
+        return null;
       }
   }
 
   /**
-    * Loads and plays the audio clip pointed to by the specified URL.
-    *
-    * @param The URL of the audio clip.
-    */
-  public void play (URL url)
+   * Returns a descriptive string with applet defined information.  The
+   * implementation in this class returns <code>null</code>, so subclasses
+   * must override to return information.
+   *
+   * @return a string describing the author, version, and applet copyright
+   */
+  public String getAppletInfo()
   {
-    getAudioClip (url).play ();
+    return null;
   }
 
   /**
-    * Loads and plays the audio clip pointed to by the specified URL.
-    *
-    * @param The base URL of the audio clip.
-    * @param name The name of the audio clip relative to the URL.
-    */
-  public void play (URL url, String name)
+   * Returns the locale for this applet, if it has been set.  If no applet
+   * specific locale has been set, the default locale is returned.
+   *
+   * @return the locale for this applet
+   * @see Component#setLocale(Locale)
+   * @since 1.1
+   */
+  public Locale getLocale()
   {
-    getAudioClip (url, name).play ();
+    return super.getLocale();
   }
 
   /**
-    * Returns an image from the specified URL.  Note that the image is not
-    * actually retrieved until the applet attempts to display it, so this
-    * method returns immediately.
-    *
-    * @param url The URL of the image.
-    *
-    * @return The retrieved image.
-    */
-  public Image getImage(URL url)
+   * Returns a list of parameters this applet supports.  Each element of
+   * the outer array is an array of three strings with the name of the
+   * parameter, the data type or valid values, and a description.  This
+   * method is optional and the default implementation returns null.
+   *
+   * @return the list of parameters supported by this applet
+   */
+  public String[][] getParameterInfo()
   {
-    return (getAppletContext ().getImage (url));
+    return null;
   }
 
   /**
-    * Returns an image from the specified URL.  Note that the image is not
-    * actually retrieved until the applet attempts to display it, so this
-    * method returns immediately.
-    *
-    * @param url The base URL of the image.
-    * @param name The name of the image relative to the URL.
-    *
-    * @return The retrieved image.
-    */
-  public Image getImage(URL url, String name)
+   * Loads and plays the audio clip pointed to by the specified URL. This does
+   * nothing if the URL does not point to a valid audio clip.
+   *
+   * @param url the URL of the audio clip
+   * @throws NullPointerException if url is null
+   * @see #getAudioClip(URL)
+   */
+  public void play(URL url)
   {
+    AudioClip ac = getAudioClip(url);
     try
       {
-        return (getAppletContext ().getImage (new URL (url.toExternalForm()
-                                        	       + name)));
+        ac.play();
       }
-    catch(Exception e)
+    catch (Exception ignored)
       {
-        return (getImage (url));
       }
   }
 
   /**
-    * Returns the locale for this applet, if it has been set.  If no applet
-    * specific locale has been set, the default locale is returned.
-    *
-    * @return The locale for this applet.
-    */
-  public Locale getLocale()
+   * Loads and plays the audio clip pointed to by the specified absolute URL,
+   * and relative path from that URL. This does nothing if the URL cannot be
+   * constructed, or if it does not point to a valid audio clip.
+   *
+   * @param url the base URL of the audio clip
+   * @param name the name of the audio clip relative to the URL
+   * @see #getAudioClip(URL, String)
+   * @see #play(URL)
+   */
+  public void play(URL url, String name)
   {
-    return (super.getLocale ());
+    try
+      {
+        getAudioClip(url, name).play();
+      }
+    catch (Exception ignored)
+      {
+      }
   }
 
   /**
-    * Returns a descriptive string with applet defined information.  The
-    * implementation in this class returns <code>null</code>.  Applets who
-    * wish to return this information should override.
-    *
-    * @return A string describing the applet.
-    */
-  public String getAppletInfo()
+   * This method is called when the applet is first loaded, before start().
+   * The default implementation does nothing; override to do any one-time
+   * initialization.
+   *
+   * @see #start()
+   * @see #stop()
+   * @see #destroy()
+   */
+  public void init()
   {
-    return (null);
   }
 
   /**
-    * Returns a list of parameters this applet supports.  Each element of
-    * the array is a list of three strings with the name of the parameter,
-    * the data type or valid values, and a description.  This method is
-    * optional and the default implementation returns <code>null</code>.
-    *
-    * @return The list of parameters supported by this applet.
-    */
-  public String[][] getParameterInfo()
+   * This method is called when the applet should start running.  This is
+   * normally each time a web page containing it is loaded.  The default
+   * implemention does nothing; override for your applet to be useful.
+   *
+   * @see #init()
+   * @see #stop()
+   * @see #destroy()
+   */
+  public void start()
   {
-    return (null);
   }
 
   /**
-    * This method is called when the applet is first loaded.  The default
-    * implementation does nothing.  Applets that wish to do one time
-    * initialization should override.
-    */
-  public void init() {}
+   * This method is called when the applet should stop running.  This is
+   * normally when the next web page is loaded.  The default implementation
+   * does nothing; override for your applet to stop using resources when
+   * it is no longer visible, but may be restarted soon.
+   *
+   * @see #init()
+   * @see #start()
+   * @see #destroy()
+   */
+  public void stop()
+  {
+  }
 
   /**
-    * This method is called when the applet is being unloaded.  The default
-    * implementation does nothing.  Applets that need to clean up resources
-    * on exit should override.
-    */
-  public void destroy() {}
+   * This method is called when the applet is being unloaded.  The default
+   * implementation does nothing; override for your applet to clean up
+   * resources on exit.
+   *
+   * @see #init()
+   * @see #start()
+   * @see #stop()
+   */
+  public void destroy()
+  {
+  }
 
   /**
-    * This method is called when the applet should start running.  This is
-    * normally each time a web page containing it is loaded.  The default
-    * implemention does nothing.  Subclasses should override.
-    */
-  public void start() {}
+   * Gets the AccessibleContext associated with this applet, creating one if
+   * necessary. This always returns an instance of {@link AccessibleApplet}.
+   *
+   * @return the accessibility context of this applet
+   * @since 1.3
+   */
+  public AccessibleContext getAccessibleContext()
+  {
+    if (accessibleContext == null)
+      accessibleContext = new AccessibleApplet();
+    return accessibleContext;
+  }
 
   /**
-    * This method is called when the applet should stop running.  This is
-    * normally when the next web page is loaded.  The default implementation
-    * does nothing.
-    */
-  public void stop() {}
+   * Read an applet from an object stream. This checks for a headless
+   * environment, then does the normal read.
+   *
+   * @param s the stream to read from
+   * @throws ClassNotFoundException if a class is not found
+   * @throws IOException if deserialization fails
+   * @throws HeadlessException if this is a headless environment
+   * @see GraphicsEnvironment#isHeadless()
+   * @since 1.4
+   */
+  private void readObject(ObjectInputStream s)
+    throws ClassNotFoundException, IOException
+  {
+    if (GraphicsEnvironment.isHeadless())
+      throw new HeadlessException();
+    s.defaultReadObject();
+  }
 
   /**
-    * The browser calls this method to set the applet's stub, which is the
-    * low level interface to the browser.
-    *
-    * @param stub The applet stub for this applet.
-    */
-  public final void setStub (AppletStub stub)
+   * This class provides accessibility support for Applets, and is the
+   * runtime type returned by {@link #getAccessibleContext()}.
+   *
+   * @author Eric Blake <ebb9@email.byu.edu>
+   * @since 1.3
+   */
+  protected class AccessibleApplet extends AccessibleAWTPanel
   {
-    this.stub = stub;
-  }
+    /**
+     * Compatible with JDK 1.4+.
+     */
+    private static final long serialVersionUID = 8127374778187708896L;
 
-} // class Applet
+    /**
+     * The default constructor.
+     */
+    protected AccessibleApplet()
+    {
+    }
 
+    /**
+     * Get the role of this accessible object, a frame.
+     *
+     * @return the role of the object
+     * @see AccessibleRole#FRAME
+     */
+    public AccessibleRole getAccessibleRole()
+    {
+      return AccessibleRole.FRAME;
+    }
+
+    /**
+     * Get the state set of this accessible object. In addition to the default
+     * states of a Component, the applet can also be active.
+     *
+     * @return the role of the object
+     * @see AccessibleState
+     */
+    public AccessibleStateSet getAccessibleStateSet()
+    {
+      AccessibleStateSet s = super.getAccessibleStateSet();
+      if (isActive())
+        s.add(AccessibleState.ACTIVE);
+      return s;
+    }
+  } // class AccessibleApplet
+} // class Applet
diff --git a/libjava/java/applet/AppletContext.java b/libjava/java/applet/AppletContext.java
index 86552abc2f8..20206efa75a 100644
--- a/libjava/java/applet/AppletContext.java
+++ b/libjava/java/applet/AppletContext.java
@@ -1,23 +1,23 @@
-/* AppletContext.java -- Access the applet's runtime environment.
-   Copyright (C) 1999 Free Software Foundation, Inc.
- 
+/* AppletContext.java -- access the applet's runtime environment
+   Copyright (C) 1999, 2002 Free Software Foundation, Inc.
+
 This file is part of GNU Classpath.
- 
+
 GNU Classpath is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2, or (at your option)
 any later version.
- 
+
 GNU Classpath is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.
- 
+
 You should have received a copy of the GNU General Public License
 along with GNU Classpath; see the file COPYING.  If not, write to the
 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 02111-1307 USA.
- 
+
 Linking this library statically or dynamically with other modules is
 making a combined work based on this library.  Thus, the terms and
 conditions of the GNU General Public License cover the whole
@@ -39,81 +39,116 @@ exception statement from your version. */
 package java.applet;
 
 import java.awt.Image;
+import java.io.InputStream;
+import java.io.IOException;
 import java.net.URL;
 import java.util.Enumeration;
+import java.util.Iterator;
 
 /**
-  * This interface allows an applet access to the browser to retrieve
-  * additional data files and display documents.  It also allows the
-  * applet to find out other applets in the same document.
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  */
+ * This interface allows an applet access to the browser to retrieve
+ * additional data files and display documents.  It also allows the
+ * applet to find out other applets in the same document.
+ *
+ * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @since 1.0
+ * @status updated to 1.4
+ */
 public interface AppletContext
 {
   /**
-    * Returns an audio clip from the specified URL.
-    *
-    * @param url The URL of the audio clip.
-    *
-    * @return The retrieved audio clip // FIXME: What happens on error?
-    */
+   * Returns an audio clip from the specified URL.
+   *
+   * @param url the URL of the audio clip
+   * @return the retrieved audio clip
+   * @throws NullPointerException if url is null
+   */
   AudioClip getAudioClip(URL url);
 
   /**
-    * Returns an image from the specified URL.  Note that the image is not
-    * actually retrieved until the applet attempts to display it, so this
-    * method returns immediately.
-    *
-    * @param url The URL of the image.
-    *
-    * @return The retrieved image.  // FIXME: What happens on eror?
-    */
+   * Returns an image from the specified URL.  Note that the image is not
+   * actually retrieved until the applet attempts to display it, so this
+   * method returns immediately.
+   *
+   * @param url the absolute URL of the image
+   * @return the retrieved image
+   * @throws NullPointerException if url is null
+   */
   Image getImage(URL url);
 
   /**
-    * Returns the applet in the document for this object that has the
-    * specified name.
-    *
-    * @param name The applet name.
-    *
-    * @return The requested applet, or <code>null</code> if an applet with
-    * the requested name cannot be found.
-    */
+   * Returns the applet in the document for this object that has the
+   * specified name.
+   *
+   * @param name the applet name
+   * @return the requested applet, or <code>null</code> if not found
+   */
   Applet getApplet(String name);
 
   /**
-    * Returns a list of all the applets in the document for this object.
-    *
-    * @return A list of all the applets in the document for this object.
-    */
+   * Returns a list of all the applets in the document for this object.
+   *
+   * @return a list of all the applets
+   */
   Enumeration getApplets();
 
   /**
-    * Displays the web page pointed to by the specified URL in the window
-    * for this object.  This page replaces the document that is currently
-    * there.
-    *
-    * @param url The URL of the web page to load.
-    */
+   * Displays the web page pointed to by the specified URL in the window
+   * for this object.  This page replaces the document that is currently
+   * there.
+   *
+   * @param url the URL of the web page to load; unspecified on an error
+   */
   void showDocument(URL url);
 
   /**
-    * Displays the web page pointed to be the sepcified URL in the window
-    * with the specified name.  The standard names "_top", "_blank",
-    * "_parent", and "_self" are allowed.
-    *
-    * @param url The URL of the web page to load.
-    * @param target The target window.
-    */
+   * Displays the web page pointed to be the sepcified URL in the window
+   * with the specified name.  The standard names "_top", "_blank",
+   * "_parent", and "_self" are allowed. An applet viewer may disregard
+   * this request.
+   *
+   * @param url the URL of the web page to load
+   * @param target the target window
+   */
   void showDocument(URL url, String target);
 
   /**
-    * Displays the specified message in the status window if that window
-    * exists.
-    *
-    * @param message The status message.
-    */
+   * Displays the specified message in the status window if that window
+   * exists.
+   *
+   * @param message the status message, may be null
+   */
   void showStatus(String message);
 
+  /**
+   * Associate a stream to a key for this applet context, possibly replacing
+   * the old value. Stream associations are local to the applet context, for
+   * security purposes.
+   *
+   * @param key the key to associate with
+   * @param stream the stream value to tie to the key, or null to remove
+   * @throws IOException if the stream is too large
+   * @since 1.4
+   */
+  public void setStream(String key, InputStream stream) throws IOException;
+
+  /**
+   * Return the stream associated with a given key in this applet context, or
+   * null if nothing is associated. Stream associations are local to the
+   * applet context, for security purposes.
+   *
+   * @param key the key to look up
+   * @return the associated stream, or null
+   * @since 1.4
+   */
+  public InputStream getStream(String key);
+
+  /**
+   * Iterate over all keys that have associated streams. Sttream associated
+   * are local to the applet context, for security purposes.
+   *
+   * @return an iterator over the association keys
+   * @since 1.4
+   */
+  public Iterator getStreamKeys();
 } // interface AppletContext
diff --git a/libjava/java/applet/AppletStub.java b/libjava/java/applet/AppletStub.java
index 5ec428a6f2b..7694cc822ef 100644
--- a/libjava/java/applet/AppletStub.java
+++ b/libjava/java/applet/AppletStub.java
@@ -1,23 +1,23 @@
-/* AppletStub.java -- Low level interface to the browser.
-   Copyright (C) 1999 Free Software Foundation, Inc.
- 
+/* AppletStub.java -- low level interface to the browser
+   Copyright (C) 1999, 2002 Free Software Foundation, Inc.
+
 This file is part of GNU Classpath.
- 
+
 GNU Classpath is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2, or (at your option)
 any later version.
- 
+
 GNU Classpath is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.
- 
+
 You should have received a copy of the GNU General Public License
 along with GNU Classpath; see the file COPYING.  If not, write to the
 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 02111-1307 USA.
- 
+
 Linking this library statically or dynamically with other modules is
 making a combined work based on this library.  Thus, the terms and
 conditions of the GNU General Public License cover the whole
@@ -40,60 +40,63 @@ package java.applet;
 import java.net.URL;
 
 /**
-  * This interface is the low level interface between the applet and the
-  * browser.
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  */
+ * This interface is the low level interface between the applet and the
+ * browser.
+ *
+ * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @see Applet#setStub(AppletStub)
+ * @since 1.0
+ * @status updated to 1.4
+ */
 public interface AppletStub
 {
   /**
-    * Returns the URL of the document this applet is embedded in.
-    *
-    * @return The URL of the document this applet is embedded in.
-    */
+   * Tests whether or not this applet is currently active. An applet is active
+   * just before the browser invokes start(), and becomes inactive just
+   * before the browser invokes stop().
+   *
+   * @return <code>true</code> if this applet is active
+   */
+  boolean isActive();
+
+  /**
+   * Returns the basename URL of the document this applet is embedded in. This
+   * is everything up to the final '/'.
+   *
+   * @return the URL of the document this applet is embedded in
+   * @see #getCodeBase()
+   */
   URL getDocumentBase();
 
   /**
-    * Returns the URL of the code base for this applet.
-    *
-    * @return The URL of the code base for this applet.
-    */
+   * Returns the URL of the code base for this applet.
+   *
+   * @return the URL of the code base for this applet
+   */
   URL getCodeBase();
 
   /**
-    * Returns the value of the specified parameter that was specified in 
-    * the &lt;APPLET&gt; tag for this applet.
-    *
-    * @param name The parameter name.
-    *
-    * @param value The parameter value, or <code>null</code> if the parameter
-    * does not exist.
-    */
+   * Returns the value of the specified parameter that was specified in
+   * the <code>&lt;APPLET&gt;</code> tag for this applet.
+   *
+   * @param name the parameter name
+   * @return the parameter value, or null if the parameter does not exist
+   * @throws NullPointerException if name is null
+   */
   String getParameter(String name);
 
   /**
-    * Returns the applet context for this applet.
-    *
-    * @return The applet context for this applet.
-    */
+   * Returns the applet context for this applet.
+   *
+   * @return the applet context for this applet
+   */
   AppletContext getAppletContext();
 
   /**
-    * Tests whether or not this applet is currently active.
-    *
-    * @return <code>true</code> if this applet is active, <code>false</code>
-    * otherwise.
-    */
-  boolean isActive();
-
-  /**
-    * Requests that the applet window for this applet be resized.
-    *
-    * @param width The new width in pixels.
-    * @param height The new height in pixels.
-    */
+   * Requests that the applet window for this applet be resized.
+   *
+   * @param width the new width in pixels
+   * @param height the new height in pixels
+   */
   void appletResize(int width, int height);
-
 } // interface AppletStub
-
diff --git a/libjava/java/applet/AudioClip.java b/libjava/java/applet/AudioClip.java
index 97cf9008a66..41dd3be2af5 100644
--- a/libjava/java/applet/AudioClip.java
+++ b/libjava/java/applet/AudioClip.java
@@ -1,23 +1,23 @@
-/* AudioClip.java -- Play an audio clip.
-   Copyright (C) 1999 Free Software Foundation, Inc.
- 
+/* AudioClip.java -- play an audio clip in an applet
+   Copyright (C) 1999, 2002 Free Software Foundation, Inc.
+
 This file is part of GNU Classpath.
- 
+
 GNU Classpath is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2, or (at your option)
 any later version.
- 
+
 GNU Classpath is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.
- 
+
 You should have received a copy of the GNU General Public License
 along with GNU Classpath; see the file COPYING.  If not, write to the
 Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
 02111-1307 USA.
- 
+
 Linking this library statically or dynamically with other modules is
 making a combined work based on this library.  Thus, the terms and
 conditions of the GNU General Public License cover the whole
@@ -39,26 +39,29 @@ exception statement from your version. */
 package java.applet;
 
 /**
-  * This interface provides a simple mechanism for playing audio clips.
-  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
-  */
+ * This interface provides a simple mechanism for playing audio clips.
+ * If multiple clips are played at once, the browser combines them into a
+ * composite clip.
+ *
+ * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @since 1.0
+ * @status updated to 1.4
+ */
 public interface AudioClip
 {
   /**
-    * Plays the audio clip starting from the beginning.
-    */
+   * Plays the audio clip starting from the beginning.
+   */
   void play();
 
   /**
-    * Stops playing this audio clip.  There is no mechanism for restarting
-    * at the point where the clip is stopped.
-    */
+   * Stops playing this audio clip.  There is no mechanism for restarting
+   * at the point where the clip is stopped.
+   */
   void stop();
 
   /**
-    * Plays this audio clip in a continuous loop.
-    */
+   * Plays this audio clip in a continuous loop.
+   */
   void loop();
-
 } // interface AudioClip