AbstractMethodError.java: Re-merged with Classpath.

	* java/lang/AbstractMethodError.java: Re-merged with Classpath.
	* java/lang/ArithmeticException.java: Likewise.
	* java/lang/ArrayIndexOutOfBoundsException.java: Likewise.
	* java/lang/ArrayStoreException.java: Likewise.
	* java/lang/Byte.java: Likewise.
	* java/lang/CharSequence.java: Likewise.
	* java/lang/ClassCastException.java: Likewise.
	* java/lang/ClassCircularityError.java: Likewise.
	* java/lang/ClassFormatError.java: Likewise.
	* java/lang/CloneNotSupportedException.java: Likewise.
	* java/lang/Cloneable.java: Likewise.
	* java/lang/Comparable.java: Likewise.
	* java/lang/Compiler.java: Likewise.
	* java/lang/Error.java: Likewise.
	* java/lang/ExceptionInInitializerError.java: Likewise.
	* java/lang/IllegalAccessError.java: Likewise.
	* java/lang/IllegalAccessException.java: Likewise.
	* java/lang/IllegalArgumentException.java: Likewise.
	* java/lang/IllegalMonitorStateException.java: Likewise.
	* java/lang/IllegalStateException.java: Likewise.
	* java/lang/IllegalThreadStateException.java: Likewise.
	* java/lang/IncompatibleClassChangeError.java: Likewise.
	* java/lang/IndexOutOfBoundsException.java: Likewise.
	* java/lang/InheritableThreadLocal.java: Likewise.
	* java/lang/InstantiationError.java: Likewise.
	* java/lang/InstantiationException.java: Likewise.
	* java/lang/InternalError.java: Likewise.
	* java/lang/InterruptedException.java: Likewise.
	* java/lang/LinkageError.java: Likewise.
	* java/lang/NegativeArraySizeException.java: Likewise.
	* java/lang/NoClassDefFoundError.java: Likewise.
	* java/lang/NoSuchFieldError.java: Likewise.
	* java/lang/NoSuchFieldException.java: Likewise.
	* java/lang/NoSuchMethodError.java: Likewise.
	* java/lang/NoSuchMethodException.java: Likewise.
	* java/lang/NullPointerException.java: Likewise.
	* java/lang/NumberFormatException.java: Likewise.
	* java/lang/OutOfMemoryError.java: Likewise.
	* java/lang/Process.java: Likewise.
	* java/lang/Runnable.java: Likewise.
	* java/lang/RuntimePermission.java: Likewise.
	* java/lang/SecurityException.java: Likewise.
	* java/lang/Short.java: Likewise.
	* java/lang/StackOverflowError.java: Likewise.
	* java/lang/StringIndexOutOfBoundsException.java: Likewise.
	* java/lang/ThreadDeath.java: Likewise.
	* java/lang/ThreadLocal.java: Likewise.
	* java/lang/UnknownError.java: Likewise.
	* java/lang/UnsatisfiedLinkError.java: Likewise.
	* java/lang/UnsupportedClassVersionError.java: Likewise.
	* java/lang/UnsupportedOperationException.java: Likewise.
	* java/lang/VerifyError.java: Likewise.
	* java/lang/VirtualMachineError.java: Likewise.
	* java/lang/reflect/InvocationTargetException.java: Likewise.
	* java/net/BindException.java: Likewise.
	* java/net/ConnectException.java: Likewise.
	* java/net/MalformedURLException.java: Likewise.
	* java/net/NoRouteToHostException.java: Likewise.
	* java/net/ProtocolException.java: Likewise.
	* java/net/SocketException.java: Likewise.
	* java/net/UnknownHostException.java: Likewise.
	* java/net/UnknownServiceException.java: Likewise.

From-SVN: r54656

libjava/ChangeLog

 2002-06-15  Tom Tromey  <tromey@redhat.com>
 
+	* java/lang/AbstractMethodError.java: Re-merged with Classpath.
+	* java/lang/ArithmeticException.java: Likewise.
+	* java/lang/ArrayIndexOutOfBoundsException.java: Likewise.
+	* java/lang/ArrayStoreException.java: Likewise.
+	* java/lang/Byte.java: Likewise.
+	* java/lang/CharSequence.java: Likewise.
+	* java/lang/ClassCastException.java: Likewise.
+	* java/lang/ClassCircularityError.java: Likewise.
+	* java/lang/ClassFormatError.java: Likewise.
+	* java/lang/CloneNotSupportedException.java: Likewise.
+	* java/lang/Cloneable.java: Likewise.
+	* java/lang/Comparable.java: Likewise.
+	* java/lang/Compiler.java: Likewise.
+	* java/lang/Error.java: Likewise.
+	* java/lang/ExceptionInInitializerError.java: Likewise.
+	* java/lang/IllegalAccessError.java: Likewise.
+	* java/lang/IllegalAccessException.java: Likewise.
+	* java/lang/IllegalArgumentException.java: Likewise.
+	* java/lang/IllegalMonitorStateException.java: Likewise.
+	* java/lang/IllegalStateException.java: Likewise.
+	* java/lang/IllegalThreadStateException.java: Likewise.
+	* java/lang/IncompatibleClassChangeError.java: Likewise.
+	* java/lang/IndexOutOfBoundsException.java: Likewise.
+	* java/lang/InheritableThreadLocal.java: Likewise.
+	* java/lang/InstantiationError.java: Likewise.
+	* java/lang/InstantiationException.java: Likewise.
+	* java/lang/InternalError.java: Likewise.
+	* java/lang/InterruptedException.java: Likewise.
+	* java/lang/LinkageError.java: Likewise.
+	* java/lang/NegativeArraySizeException.java: Likewise.
+	* java/lang/NoClassDefFoundError.java: Likewise.
+	* java/lang/NoSuchFieldError.java: Likewise.
+	* java/lang/NoSuchFieldException.java: Likewise.
+	* java/lang/NoSuchMethodError.java: Likewise.
+	* java/lang/NoSuchMethodException.java: Likewise.
+	* java/lang/NullPointerException.java: Likewise.
+	* java/lang/NumberFormatException.java: Likewise.
+	* java/lang/OutOfMemoryError.java: Likewise.
+	* java/lang/Process.java: Likewise.
+	* java/lang/Runnable.java: Likewise.
+	* java/lang/RuntimePermission.java: Likewise.
+	* java/lang/SecurityException.java: Likewise.
+	* java/lang/Short.java: Likewise.
+	* java/lang/StackOverflowError.java: Likewise.
+	* java/lang/StringIndexOutOfBoundsException.java: Likewise.
+	* java/lang/ThreadDeath.java: Likewise.
+	* java/lang/ThreadLocal.java: Likewise.
+	* java/lang/UnknownError.java: Likewise.
+	* java/lang/UnsatisfiedLinkError.java: Likewise.
+	* java/lang/UnsupportedClassVersionError.java: Likewise.
+	* java/lang/UnsupportedOperationException.java: Likewise.
+	* java/lang/VerifyError.java: Likewise.
+	* java/lang/VirtualMachineError.java: Likewise.
+	* java/lang/reflect/InvocationTargetException.java: Likewise.
+	* java/net/BindException.java: Likewise.
+	* java/net/ConnectException.java: Likewise.
+	* java/net/MalformedURLException.java: Likewise.
+	* java/net/NoRouteToHostException.java: Likewise.
+	* java/net/ProtocolException.java: Likewise.
+	* java/net/SocketException.java: Likewise.
+	* java/net/UnknownHostException.java: Likewise.
+	* java/net/UnknownServiceException.java: Likewise.
+
 	* java/io/BufferedOutputStream.java: Re-merged with Classpath.
 	* java/io/CharConversionException.java: Likewise.
 	* java/io/EOFException.java: Likewise.

libjava/java/lang/AbstractMethodError.java

-/* AbstractMethodError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* AbstractMethodError.java -- thrown if an abstract method is invoked
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,38 +38,35 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * An <code>AbstractMethodError</code> is thrown when an application
- * attempts to access an abstract method.  Compilers typically detect
- * this error, but it can be thrown at run time if the definition of a 
- * class has changed since the application was last compiled.
- *
- * @since JDK 1.0
+ * An <code>AbstractMethodError</code> is thrown when an application attempts
+ * to access an abstract method.  Compilers typically detect this error, but
+ * it can be thrown at run time if the definition of a class has changed
+ * since the application was last compiled. This can also occur when
+ * reflecting on methods.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class AbstractMethodError extends IncompatibleClassChangeError
 {
-  static final long serialVersionUID = -1654391082989018462L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -1654391082989018462L;
 
   /**
    * Create an error without a message.
    */
   public AbstractMethodError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public AbstractMethodError(String s)
   {

libjava/java/lang/ArithmeticException.java

 /* ArithmeticException.java -- exception thrown to indicate conditions
    like divide by zero.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,38 +39,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional circumstances.
- * In this case an ArithmeticException is thrown when things like trying
- * to divide a number by zero.
- *
- * @since JDK 1.0
+ * Thrown when a math error has occured, such as trying to divide an
+ * integer by zero. For example:<br>
+ * <pre>
+ * int i = 0;
+ * int j = 2 / i;
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class ArithmeticException extends RuntimeException
 {
-  static final long serialVersionUID = 2256477558314496007L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 2256477558314496007L;
 
   /**
    * Create an exception without a message.
    */
   public ArithmeticException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public ArithmeticException(String s)
   {

libjava/java/lang/ArrayIndexOutOfBoundsException.java

 /* ArrayIndexOutOfBoundsException.java -- exception thrown when accessing
    an illegal index.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,49 +39,49 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions, in this case
- * when trying to access an illegal index.  This exception is thrown when
- * accessing an index which is either negative or greater than the size of
- * the array minus one.
- *
- * @since JDK 1.0
+ * Thrown when attempting to access a position outside the valid range of
+ * an array. For example:<br>
+ * <pre>
+ * int[] i = { 1 };
+ * i[1] = 2;
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class ArrayIndexOutOfBoundsException extends IndexOutOfBoundsException
 {
-  static final long serialVersionUID = -5116101128118950844L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -5116101128118950844L;
 
   /**
    * Create an exception without a message.
    */
-  public ArrayIndexOutOfBoundsException() {
-    super();
+  public ArrayIndexOutOfBoundsException()
+  {
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
-  public ArrayIndexOutOfBoundsException(String s) {
+  public ArrayIndexOutOfBoundsException(String s)
+  {
     super(s);
   }
 
   /**
    * Create an exception indicating the illegal index.
+   *
+   * @param index the invalid index
    */
-  public ArrayIndexOutOfBoundsException(int index) {
+  public ArrayIndexOutOfBoundsException(int index)
+  {
     super("Array index out of range: " + index);
   }
-
 }

libjava/java/lang/ArrayStoreException.java

 /* ArrayStoreException.java -- exception thrown to when trying to store an
    object into an array of a different type.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,37 +39,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions, in this case
- * when trying to store an object into an array of a different type.
- *
- * @since JDK 1.0
+ * Thrown when trying to store an object of the wrong runtime type in an
+ * array. For example:<br>
+ * <pre>
+ * Object[] o = new Integer[1];
+ * o[0] = "oops";
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class ArrayStoreException extends RuntimeException
 {
-  static final long serialVersionUID = -4522193890499838241L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4522193890499838241L;
 
   /**
    * Create an exception without a message.
    */
   public ArrayStoreException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public ArrayStoreException(String s)
   {

libjava/java/lang/Byte.java

 /* Byte.java -- object wrapper for byte
-   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -48,19 +48,26 @@ package java.lang;
  * @author Paul Fisher
  * @author John Keiser
  * @author Per Bothner
- * @since JDK 1.0
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.1
+ * @status updated to 1.4
  */
 public final class Byte extends Number implements Comparable
 {
-  static final long serialVersionUID = -7183698231559129828L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = -7183698231559129828L;
 
   /**
-   * The minimum value a <code>byte</code> can represent is -128.
+   * The minimum value a <code>byte</code> can represent is -128 (or
+   * -2<sup>7</sup>).
    */
   public static final byte MIN_VALUE = -128;
 
   /**
-   * The maximum value a <code>byte</code> can represent is 127.
+   * The maximum value a <code>byte</code> can represent is 127 (or
+   * 2<sup>7</sup> - 1).
    */
   public static final byte MAX_VALUE = 127;
 
@@ -72,6 +79,8 @@ public final class Byte extends Number implements Comparable
 
   /**
    * The immutable value of this Byte.
+   *
+   * @serial the wrapped byte
    */
   private final byte value;
 
@@ -88,122 +97,98 @@ public final class Byte extends Number implements Comparable
 
   /**
    * Create a <code>Byte</code> object representing the value specified
-   * by the <code>String</code> argument.
+   * by the <code>String</code> argument
    *
-   * @param s the string to convert.
+   * @param s the string to convert
+   * @throws NumberFormatException if the String does not contain a byte
+   * @see #valueOf(String)
    */
-  public Byte(String s) throws NumberFormatException 
+  public Byte(String s)
   {
     value = parseByte(s, 10);
   }
 
   /**
-   * Return a hashcode representing this Object.
-   *
-   * <code>Byte</code>'s hash code is calculated by simply returning its
-   * value.
-   *
-   * @return this Object's hash code.
-   */
-  public int hashCode() 
-  {
-    return value;
-  }
-
-  /**
-   * Returns <code>true</code> if <code>obj</code> is an instance of
-   * <code>Byte</code> and represents the same byte value.
-   * @return whether these Objects are semantically equal.
-   */    
-  public boolean equals(Object obj) 
-  {
-    return ((obj instanceof Byte) && (value == ((Byte)obj).byteValue()));
-  }
-
-  /**
    * Converts the <code>byte</code> to a <code>String</code> and assumes
    * a radix of 10.
-   * @param i the <code>byte</code> to convert to <code>String</code>
-   * @return the <code>String</code> representation of the argument.
+   *
+   * @param b the <code>byte</code> to convert to <code>String</code>
+   * @return the <code>String</code> representation of the argument
    */
-  public static String toString(byte i) 
+  public static String toString(byte b)
   {
-    return Integer.toString ((int) i);
+    return String.valueOf(b);
   }
 
   /**
-   * Converts the <code>Byte</code> value to a <code>String</code> and
-   * assumes a radix of 10.
-   * @return the <code>String</code> representation of this <code>Byte</code>.
+   * Converts the specified <code>String</code> into a <code>byte</code>.
+   * This function assumes a radix of 10.
+   *
+   * @param s the <code>String</code> to convert
+   * @return the <code>byte</code> value of <code>s</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
+   * @see #parseByte(String)
    */
-  public String toString() 
+  public static byte parseByte(String s)
   {
-    return Integer.toString ((int) value);
+    return parseByte(s, 10);
   }
 
   /**
-   * Creates a new <code>Byte</code> object using the <code>String</code>,
-   * assuming a radix of 10.
-   * @param s the <code>String</code> to convert.
-   * @return the new <code>Byte</code>.
-   * @see #Byte(java.lang.String)
-   * @see #parseByte(java.lang.String)
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.
+   * Converts the specified <code>String</code> into an <code>int</code>
+   * using the specified radix (base). The string must not be <code>null</code>
+   * or empty. It may begin with an optional '-', which will negate the answer,
+   * provided that there are also valid digits. Each digit is parsed as if by
+   * <code>Character.digit(d, radix)</code>, and must be in the range
+   * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
+   * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
+   * Unlike Double.parseDouble, you may not have a leading '+'.
+   *
+   * @param s the <code>String</code> to convert
+   * @param radix the radix (base) to use in the conversion
+   * @return the <code>String</code> argument converted to </code>byte</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
    */
-  public static Byte valueOf(String s) throws NumberFormatException 
+  public static byte parseByte(String s, int radix)
   {
-    return new Byte(parseByte(s));
+    int i = Integer.parseInt(s, radix, false);
+    if ((byte) i != i)
+      throw new NumberFormatException();
+    return (byte) i;
   }
 
   /**
    * Creates a new <code>Byte</code> object using the <code>String</code>
    * and specified radix (base).
-   * @param s the <code>String</code> to convert.
-   * @param radix the radix (base) to convert with.
-   * @return the new <code>Byte</code>.
-   * @see #parseByte(java.lang.String,int)
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.
+   *
+   * @param s the <code>String</code> to convert
+   * @param radix the radix (base) to convert with
+   * @return the new <code>Byte</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
+   * @see #parseByte(String, int)
    */
   public static Byte valueOf(String s, int radix)
-    throws NumberFormatException 
   {
     return new Byte(parseByte(s, radix));
   }
 
   /**
-   * Converts the specified <code>String</code> into a <code>byte</code>.
-   * This function assumes a radix of 10.
+   * Creates a new <code>Byte</code> object using the <code>String</code>,
+   * assuming a radix of 10.
    *
    * @param s the <code>String</code> to convert
-   * @return the <code>byte</code> value of the <code>String</code>
-   *         argument.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.
+   * @return the new <code>Byte</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
+   * @see #Byte(String)
+   * @see #parseByte(String)
    */
-  public static byte parseByte(String s) throws NumberFormatException 
+  public static Byte valueOf(String s)
   {
-    return parseByte(s, 10);
-  }
-
-  /**
-   * Converts the specified <code>String</code> into a <code>byte</code>
-   * using the specified radix (base).
-   *
-   * @param str the <code>String</code> to convert
-   * @param radix the radix (base) to use in the conversion
-   * @return the <code>String</code> argument converted to </code>byte</code>.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.    
-   */
-  public static byte parseByte(String str, int radix) 
-    throws NumberFormatException 
-  {
-    int i = Integer.parseInt(str, radix);
-    if (i < MIN_VALUE || i > MAX_VALUE)
-      throw new NumberFormatException();
-    return (byte) i;
+    return new Byte(parseByte(s, 10));
   }
 
   /**
@@ -211,104 +196,162 @@ public final class Byte extends Number implements Comparable
    * The <code>String</code> may represent decimal, hexadecimal, or
    * octal numbers.
    *
-   * The <code>String</code> argument is interpreted based on the leading
-   * characters.  Depending on what the String begins with, the base will be
-   * interpreted differently:
+   * <p>The extended BNF grammar is as follows:<br>
+   * <pre>
+   * <em>DecodableString</em>:
+   *      ( [ <code>-</code> ] <em>DecimalNumber</em> )
+   *    | ( [ <code>-</code> ] ( <code>0x</code> | <code>0X</code>
+   *              | <code>#</code> ) { <em>HexDigit</em> }+ )
+   *    | ( [ <code>-</code> ] <code>0</code> { <em>OctalDigit</em> } )
+   * <em>DecimalNumber</em>:
+   *        <em>DecimalDigit except '0'</em> { <em>DecimalDigit</em> }
+   * <em>DecimalDigit</em>:
+   *        <em>Character.digit(d, 10) has value 0 to 9</em>
+   * <em>OctalDigit</em>:
+   *        <em>Character.digit(d, 8) has value 0 to 7</em>
+   * <em>DecimalDigit</em>:
+   *        <em>Character.digit(d, 16) has value 0 to 15</em>
+   * </pre>
+   * Finally, the value must be in the range <code>MIN_VALUE</code> to
+   * <code>MAX_VALUE</code>, or an exception is thrown.
    *
-   * <table>
-   * <tr><th>Leading<br>Characters</th><th>Base</th></tr>
-   * <tr><td>#</td><td>16</td></tr>
-   * <tr><td>0x</td><td>16</td></tr>
-   * <tr><td>0X</td><td>16</td></tr>
-   * <tr><td>0</td><td>8</td></tr>
-   * <tr><td>Anything<br>Else</td><td>10</td></tr>
-   * </table>
-   *
-   * @param str the <code>String</code> to interpret.
-   * @return the value of the String as a <code>Byte</code>.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>byte</code>.    
+   * @param s the <code>String</code> to interpret
+   * @return the value of the String as a <code>Byte</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>byte</code>
+   * @throws NullPointerException if <code>s</code> is null
+   * @see Integer#decode(String)
    */
-  public static Byte decode(String str) throws NumberFormatException 
+  public static Byte decode(String s)
   {
-    int i = (Integer.decode(str)).intValue();
-    if (i < MIN_VALUE || i > MAX_VALUE)
+    int i = Integer.parseInt(s, 10, true);
+    if ((byte) i != i)
       throw new NumberFormatException();
     return new Byte((byte) i);
   }
 
-  /** Return the value of this <code>Byte</code> as an <code>short</code>.
-   ** @return the value of this <code>Byte</code> as an <code>short</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code>.
+   *
+   * @return the byte value
+   */
   public byte byteValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as an <code>short</code>.
-   ** @return the value of this <code>Byte</code> as an <code>short</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as a <code>short</code>.
+   *
+   * @return the short value
+   */
   public short shortValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as an <code>int</code>.
-   ** @return the value of this <code>Byte</code> as an <code>int</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as an <code>int</code>.
+   *
+   * @return the int value
+   */
   public int intValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as a <code>long</code>.
-   ** @return the value of this <code>Byte</code> as a <code>long</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as a <code>long</code>.
+   *
+   * @return the long value
+   */
   public long longValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as a <code>float</code>.
-   ** @return the value of this <code>Byte</code> as a <code>float</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as a <code>float</code>.
+   *
+   * @return the float value
+   */
   public float floatValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Byte</code> as a <code>double</code>.
-   ** @return the value of this <code>Byte</code> as a <code>double</code>.
-   **/
+  /**
+   * Return the value of this <code>Byte</code> as a <code>double</code>.
+   *
+   * @return the double value
+   */
   public double doubleValue()
   {
     return value;
   }
 
   /**
-   * Compare two Bytes numerically by comparing their
-   * <code>byte</code> values.
-   * @return a positive value if this <code>Byte</code> is greater
-   * in value than the argument <code>Byte</code>; a negative value
-   * if this <code>Byte</code> is smaller in value than the argument
-   * <code>Byte</code>; and <code>0</code>, zero, if this
-   * <code>Byte</code> is equal in value to the argument
-   * <code>Byte</code>.  
+   * Converts the <code>Byte</code> value to a <code>String</code> and
+   * assumes a radix of 10.
+   *
+   * @return the <code>String</code> representation of this <code>Byte</code>
+   * @see Integer#toString()
+   */
+  public String toString()
+  {
+    return String.valueOf(value);
+  }
+
+  /**
+   * Return a hashcode representing this Object. <code>Byte</code>'s hash
+   * code is simply its value.
+   *
+   * @return this Object's hash code
+   */
+  public int hashCode()
+  {
+    return value;
+  }
+
+  /**
+   * Returns <code>true</code> if <code>obj</code> is an instance of
+   * <code>Byte</code> and represents the same byte value.
+   *
+   * @param obj the object to compare
+   * @return whether these Objects are semantically equal
+   */
+  public boolean equals(Object obj)
+  {
+    return obj instanceof Byte && value == ((Byte) obj).value;
+  }
+
+  /**
+   * Compare two Bytes numerically by comparing their <code>byte</code> values.
+   * The result is positive if the first is greater, negative if the second
+   * is greater, and 0 if the two are equal.
+   *
+   * @param b the Byte to compare
+   * @return the comparison
+   * @since 1.2
    */
   public int compareTo(Byte b)
   {
-    return (int)(value - b.byteValue());
+    return value - b.value;
   }
 
   /**
-   * Behaves like <code>compareTo(java.lang.Byte)</code> unless the Object
-   * is not a <code>Byte</code>.  Then it throws a 
-   * <code>ClassCastException</code>.
-   * @exception ClassCastException if the argument is not a
-   * <code>Byte</code>.  
+   * Behaves like <code>compareTo(Byte)</code> unless the Object
+   * is not a <code>Byte</code>.
+   *
+   * @param o the object to compare
+   * @return the comparison
+   * @throws ClassCastException if the argument is not a <code>Byte</code>
+   * @see #compareTo(Byte)
+   * @see Comparable
+   * @since 1.2
    */
   public int compareTo(Object o)
   {
-    return compareTo((Byte)o);
+    return compareTo((Byte) o);
   }
 }

libjava/java/lang/CharSequence.java

-/* java.lang.CharSequence -- Anything that has an indexed sequence of chars
-   Copyright (C) 2001 Free Software Foundation, Inc.
+/* CharSequence.java -- Anything that has an indexed sequence of chars
+   Copyright (C) 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -44,8 +44,8 @@ package java.lang;
  * <code>CharBuffer</code> to give a uniform way to get chars at a certain
  * index, the number of characters in the sequence and a subrange of the
  * chars. Indexes start at 0 and the last index is <code>length()-1</code>.
- * <p>
- * Even when classes implement this interface they are not always
+ *
+ * <p>Even when classes implement this interface they are not always
  * exchangeble because they might implement their compare, equals or hash
  * function differently. This means that in general one should not use a
  * <code>CharSequence</code> as keys in collections since two sequences
@@ -54,31 +54,37 @@ package java.lang;
  * represented by different classes.
  *
  * @author Mark Wielaard (mark@klomp.org)
- *
  * @since 1.4
+ * @status updated to 1.4
  */
-
-public interface CharSequence {
-
+public interface CharSequence
+{
   /**
    * Returns the character at the given index.
    *
-     * @exception IndexOutOfBoundsException when <code>i &lt; 0</code> or
-     * <code>i &gt; length()-1</code>.
+   * @param i the index to retrieve from
+   * @return the character at that location
+   * @throws IndexOutOfBoundsException if i &lt; 0 || i &gt;= length() - 1
    */
   char charAt(int i);
 
   /**
-     * Returns the length of the sequence.
+   * Returns the length of the sequence. This is the number of 16-bit
+   * characters in the sequence, which may differ from the length of the
+   * underlying encoding.
+   *
+   * @return the sequence length
    */
   int length();
 
   /**
    * Returns a new <code>CharSequence</char> of the indicated range.
    *
-     * @exception IndexOutOfBoundsException when <code>begin &lt; 0</code>,
-     *         <code>end &lt; 0</code>, <code>end &gt; length()</code> or
-     *         <code>begin &gt; end</code>
+   * @param begin the start index (inclusive)
+   * @param end the end index (exclusive)
+   * @return a subsequence of this
+   * @throws IndexOutOfBoundsException if begin &gt; end || begin &lt; 0 ||
+   *         end &gt; length()
    */
   CharSequence subSequence(int begin, int end);
 
@@ -86,6 +92,8 @@ public interface CharSequence {
    * Returns the complete <code>CharSequence</code> as a <code>String</code>.
    * Classes that implement this interface should return a <code>String</code>
    * which contains only the characters in the sequence in the correct order.
+   *
+   * @return the character sequence as a String
    */
   String toString();
 }

libjava/java/lang/ClassCastException.java

-/* ClassCastException.java -- exception thrown when incorrectly trying to 
-   cast an object to a subclass it does not belong to.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* ClassCastException.java -- exception thrown on bad cast
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,42 +38,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  In this case
- * when incorrectly trying to cast an object to a subclass it does not 
- * belong to.  The following code generates a <code>ClassCastException</code>.
+ * Thrown when an attempt is made to cast an object which is not of the
+ * appropriate runtime type. For example:<br>
  * <pre>
  * Object o = new Vector();
- * String s = (String)o;
+ * String s = (String) o;
  * </pre>
  *
- * @since JDK 1.0
- *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class ClassCastException extends RuntimeException
 {
-  static final long serialVersionUID = -9223365651070458532L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -9223365651070458532L;
 
   /**
    * Create an exception without a message.
    */
   public ClassCastException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public ClassCastException(String s)
   {

libjava/java/lang/ClassCircularityError.java

-/* ClassCircularityError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* ClassCircularityError.java -- thrown when linking circular classes
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,36 +38,33 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
  * A <code>ClassCircularityError</code> is thrown when a circular dependency
- * has been detected while initializing a class.
- *
- * @since JDK 1.0
+ * has been detected while initializing a class. This signals binary
+ * incompatible versions of class files, as the compiler normally catches this.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class ClassCircularityError extends LinkageError
 {
-  static final long serialVersionUID = 1054362542914539689L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 1054362542914539689L;
 
   /**
    * Create an error without a message.
    */
   public ClassCircularityError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public ClassCircularityError(String s)
   {

libjava/java/lang/ClassFormatError.java

-/* ClassFormatError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* ClassFormatError.java -- thrown if a class file is invalid
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,35 +38,32 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
  * A <code>ClassFormatError</code> is thrown when a Java Virtual Machine
  * unable to read a class file because the file is corrupted or cannot be
  * interpreted as a class file.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
+ * @status updated to 1.4
  */
 public class ClassFormatError extends LinkageError
 {
-  static final long serialVersionUID = -8420114879011949195L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -8420114879011949195L;
 
   /**
    * Create an error without a message.
    */
   public ClassFormatError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public ClassFormatError(String s)
   {

libjava/java/lang/CloneNotSupportedException.java

-/* CloneNotSupportedException.java -- exception thrown to indicate that 
-   the object calling the clone method of Object does not implement the 
-   Cloneable interface.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* CloneNotSupportedException.java -- thrown when an object cannot be cloned
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -40,33 +38,38 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
  * Thrown to indicate an object should not or could not be cloned. This
  * includes the case when {@link Object#clone()} is called on an object
- * which does not implement the {@link Cloneable} interface.
- * <p>
+ * which does not implement the {@link Cloneable} interface. For example:<br>
+ * <pre>
+ * void m() throws CloneNotSupportedException
+ * {
+ *   clone();
+ * }
+ * </pre>
  *
- * Notice that calling <code>clone()</code> on an array will never produce
+ * <p>Notice that calling <code>clone()</code> on an array will never produce
  * this exception, as the VM will always succeed in copying the array, or
- * cause an OutOfMemoryError first.
+ * cause an OutOfMemoryError first. For example:<br>
+ * <pre>
+ * void m(int[] array)
+ * {
+ *   int[] copy = (int[]) array.clone();
+ * }
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
  * @author Eric Blake <ebb9@email.byu.edu>
- * @since 1.0
  * @see Cloneable
  * @see Object#clone()
+ * @status updated to 1.4
  */
 public class CloneNotSupportedException extends Exception
 {
   /**
-   * compatible with JDK 1.0+
+   * Compatible with JDK 1.0+.
    */
   private static final long serialVersionUID = 5195511250079656443L;
 
@@ -79,6 +82,7 @@ public class CloneNotSupportedException extends Exception
 
   /**
    * Create an exception with a message.
+   *
    * @param s the error message
    */
   public CloneNotSupportedException(String s)

libjava/java/lang/Cloneable.java

 /* Cloneable.java -- Interface for marking objects cloneable by Object.clone()
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,12 +38,6 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
  * This interface should be implemented by classes wishing to
  * support of override <code>Object.clone()</code>.  The default
@@ -53,33 +47,30 @@ package java.lang;
  * If <code>clone()</code> is called on an object which does not
  * implement this interface, a <code>CloneNotSupportedException</code>
  * will be thrown.
- * <p>
  *
- * This interface is simply a tagging interface; it carries no
+ * <p>This interface is simply a tagging interface; it carries no
  * requirements on methods to implement.  However, it is typical for
  * a Cloneable class to implement at least <code>equals</code>,
  * <code>hashCode</code>, and <code>clone</code>, sometimes
  * increasing the accessibility of clone to be public. The typical
  * implementation of <code>clone</code> invokes <code>super.clone()</code>
  * rather than a constructor, but this is not a requirement.
- * <p>
  *
- * If an object that implement Cloneable should not be cloned,
+ * <p>If an object that implement Cloneable should not be cloned,
  * simply override the <code>clone</code> method to throw a
  * <code>CloneNotSupportedException</code>.
- * <p>
  *
- * All array types implement Cloneable, and have a public
+ * <p>All array types implement Cloneable, and have a public
  * <code>clone</code> method that will never fail with a
  * <code>CloneNotSupportedException</code>.
  *
- * @since 1.0
  * @author Paul Fisher
  * @author Eric Blake <ebb9@email.byu.edu>
  * @author Warren Levy <warrenl@cygnus.com>
- *
  * @see Object#clone()
  * @see CloneNotSupportedException
+ * @since 1.0
+ * @status updated to 1.4
  */
 public interface Cloneable
 {

libjava/java/lang/Comparable.java

 /* Comparable.java -- Interface for comparaing objects to obtain an ordering
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,32 +38,60 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Interface for objects that can be ordering among other
- * objects. The ordering can be <EM>total</EM>, such that two objects
- * only compare equal if they are equal by the equals method, or
- * <EM>partial</EM> such that this is not necessarily true. For
- * example, a case-sensitive dictionary order comparison of Strings
- * is total, but if it is case-insensitive it is partial, because
- * "abc" and "ABC" compare as equal even though "abc".equals("ABC")
- * returns false.
+ * Interface for objects that can be ordering among other objects. The
+ * ordering can be <em>total</em>, such that two objects only compare equal
+ * if they are also equal by the equals method, or <em>partial</em> such
+ * that this is not necessarily true. For example, a case-sensitive
+ * dictionary order comparison of Strings is total, but if it is
+ * case-insensitive it is partial, because "abc" and "ABC" compare as
+ * equal even though "abc".equals("ABC") returns false. However, if you use
+ * a partial ordering, it is a good idea to document your class as
+ * "inconsistent with equals", because the behavior of your class in a
+ * SortedMap will be different than in a HashMap.
+ *
+ * <p>Lists, arrays, and sets of objects that implement this interface can
+ * be sorted automatically, without the need for an explicit
+ * {@link Comparator}. Note that <code>e1.compareTo(null)</code> should
+ * throw an Exception; as should comparison between incompatible classes.
  *
  * @author Geoff Berry
  * @author Warren Levy <warrenl@cygnus.com>
- *
- * @since JDK1.2
- * @see java.util.Comparator
+ * @see Comparator
+ * @see Collections#sort(List)
+ * @see Arrays#sort(Object[])
+ * @see SortedSet
+ * @see SortedMap
+ * @see TreeSet
+ * @see TreeMap
+ * @since 1.2
+ * @status updated to 1.4
  */
 public interface Comparable
 {
   /**
-   * @return a negative integer if this object is less than
-   * <code>o<code>, zero if this object is equal to <code>o</code>, or
-   * a positive integer if this object is greater than <code>o</code>
+   * Compares this object with another, and returns a numerical result based
+   * on the comparison.  If the result is negative, this object sorts less
+   * than the other; if 0, the two are equal, and if positive, this object
+   * sorts greater than the other.  To translate this into boolean, simply
+   * perform <code>o1.compareTo(o2) <em>&lt;op&gt;</em> 0</code>, where op
+   * is one of &lt;, &lt;=, =, !=, &gt;, or &gt;=.
+   *
+   * <p>You must make sure that the comparison is mutual, ie.
+   * <code>sgn(x.compareTo(y)) == -sgn(y.compareTo(x))</code> (where sgn() is
+   * defined as -1, 0, or 1 based on the sign).  This includes throwing an
+   * exception in either direction if the two are not comparable; hence,
+   * <code>compareTo(null)</code> should always throw an Exception.
+   *
+   * <p>You should also ensure transitivity, in two forms:
+   * <code>x.compareTo(y) &gt; 0 && y.compareTo(z) &gt; 0</code> implies
+   * <code>x.compareTo(z) &gt; 0</code>; and <code>x.compareTo(y) == 0</code>
+   * implies <code>x.compareTo(z) == y.compareTo(z)</code>.
+   *
+   * @param o the object to be compared
+   * @return an integer describing the comparison
+   * @throws NullPointerException if o is null
+   * @throws ClassCastException if o cannot be compared
    */
-  int compareTo( Object o );
+  int compareTo(Object o);
 }

libjava/java/lang/Compiler.java

-/* Compiler.java -- Interface for implementing a method to override 
-   Object.clone()comparaing objects to obtain an ordering
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* Compiler.java -- placeholder for Java-to-native runtime compilers
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,35 +38,31 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- */
-
 /**
- * The <code>Compiler</code> class is a place holder for a JIT
- * compiler implementation does nothing unless there is such a 
- * compiler by default.
- * <p>
- * The system property <code>java.compiler</code> may contain the name
+ * The <code>Compiler</code> class is a placeholder for a JIT compiler
+ * implementation, and does nothing unless there is such a compiler.
+ *
+ * <p>The system property <code>java.compiler</code> may contain the name
  * of a library to load with <code>System.loadLibrary</code> when the
- * virtual machine first starts.  If so and loading the library succeeds,
+ * virtual machine first starts.  If so, and loading the library succeeds,
  * then a function by the name of <code>java_lang_Compiler_start()</code>
  * in that library is called.
  *
- * Note that a VM might not have implemented any of this.
+ * <p>Note that a VM might not have implemented any of this.
  *
  * @author Tom Tromey <tromey@cygnus.com>
- *
+ * @see System#getProperty(String)
+ * @see System#getProperty(String, String)
+ * @see System#loadLibrary(String)
  * @since JDK 1.0
- * @see System#getProperty(java.lang.String)
- * @see System#getProperty(java.lang.String,java.lang.String)
- * @see System#loadLibrary(java.lang.String)
+ * @status updated to 1.4
  */
 public final class Compiler
 {
   /**
    * Don't allow new `Compiler's to be made.
    */
-    private Compiler ()
+  private Compiler()
   {
   }
 
@@ -76,9 +71,10 @@ public final class Compiler
    *
    * @param oneClass the class to compile
    * @return <code>false</code> if no compiler is available or
-     * compilation failed and <code>true</code> if compilation succeeded.
+   *         compilation failed, <code>true</code> if compilation succeeded
+   * @throws NullPointerException if oneClass is null
    */
-    public static boolean compileClass (Class oneClass) 
+  public static boolean compileClass(Class oneClass)
   {
     // Never succeed.
     return false;
@@ -89,9 +85,10 @@ public final class Compiler
    *
    * @param classNames the name of classes to compile
    * @return <code>false</code> if no compiler is available or
-     * compilation failed and <code>true</code> if compilation succeeded.
+   *         compilation failed, <code>true</code> if compilation succeeded
+   * @throws NullPointerException if classNames is null
    */
-    public static boolean compileClasses (String classNames) 
+  public static boolean compileClasses(String classNames)
   {
     // Note the incredibly lame interface.  Always fail.
     return false;
@@ -101,8 +98,12 @@ public final class Compiler
    * This method examines the argument and performs an operation
    * according to the compilers documentation.  No specific operation
    * is required.
+   *
+   * @param arg a compiler-specific argument
+   * @return a compiler-specific value, including null
+   * @throws NullPointerException if the compiler doesn't like a null arg
    */
-    public static Object command (Object arg) 
+  public static Object command(Object arg)
   {
     // Our implementation defines this to a no-op.
     return null;
@@ -110,13 +111,18 @@ public final class Compiler
 
   /**
    * Calling <code>Compiler.enable()</code> will cause the compiler
-     * to resume operation if it was previously disabled.  
+   * to resume operation if it was previously disabled; provided that a
+   * compiler even exists.
    */
-    public static void enable () { }
+  public static void enable()
+  {
+  }
 
   /**
    * Calling <code>Compiler.disable()</code> will cause the compiler
-     * to be suspended.
+   * to be suspended; provided that a compiler even exists.
    */
-    public static void disable () { }
+  public static void disable()
+  {
+  }
 }

libjava/java/lang/Error.java

-/* Error.java - Indication of fatal abnormal conditions
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* Error.java -- Indication of fatal abnormal conditions
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,45 +38,70 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
  * Applications should not try to catch errors since they indicate
  * abnormal conditions.  An abnormal condition is something which should not
- * occur.  A few errors, like <code>ThreadDeath</code> error do normally
- * occur, but most applications should not catch it.  
- * <p>
- * A method is not required to declare any subclass of <code>Error</code> in 
- * its <code>throws</code> clause which might be thrown but not caught while
- * executing the method..
+ * occur, or which should not be recovered from.  This latter category
+ * includes <code>ThreadDeath</code> and <code>AssertionError</code>.
  *
- * @since JDK 1.0
+ * <p>A method is not required to declare any subclass of <code>Error</code> in
+ * its <code>throws</code> clause which might be thrown but not caught while
+ * executing the method.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.0
+ * @status updated to 1.4
  */
 public class Error extends Throwable
 {
-  static final long serialVersionUID = 4980196508277280342L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 4980196508277280342L;
 
   /**
-   * Create an error without a message.
+   * Create an error without a message. The cause remains uninitialized.
+   *
+   * @see #initCause(Throwable)
    */
   public Error()
   {
-      super();
   }
 
   /**
-   * Create an error with a message.
+   * Create an error with a message. The cause remains uninitialized.
+   *
+   * @param s the message string
+   * @see #initCause(Throwable)
    */
   public Error(String s)
   {
     super(s);
   }
+
+  /**
+   * Create an error with a message and a cause.
+   *
+   * @param s the message string
+   * @param cause the cause of this error
+   * @since 1.4
+   */
+  public Error(String s, Throwable cause)
+  {
+    super(s, cause);
+  }
+
+  /**
+   * Create an error with a given cause, and a message of
+   * <code>cause == null ? null : cause.toString()</code>.
+   *
+   * @param cause the cause of this error
+   * @since 1.4
+   */
+  public Error(Throwable cause)
+  {
+    super(cause);
+  }
 }

libjava/java/lang/ExceptionInInitializerError.java

-/* ExceptionInInitializerError.java 
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* ExceptionInInitializerError.java -- thrown when class initialization fails
+   with an uncaught exception
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,65 +39,71 @@ exception statement from your version. */
 
 package java.lang;
 
-import java.io.PrintStream;
-import java.io.PrintWriter;
-
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * An <code>ExceptionInInitializerError</code> is thrown when an 
- * unexpected exception has occurred in a static initializer or the
- * initializer for a static variable.
- *
- * @since JDK 1.1
+ * An <code>ExceptionInInitializerError</code> is thrown when an uncaught
+ * exception has occurred in a static initializer or the initializer for a
+ * static variable. In general, this wraps only RuntimeExceptions, since the
+ * compiler does not allow a checked exception to be uncaught in an
+ * initializer. This exception only occurs during reflection, when a class
+ * is initialized as part of another action.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998 
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.1
+ * @status updated to 1.4
  */
 public class ExceptionInInitializerError extends LinkageError
 {
+  /**
+   * Compatible with JDK 1.1+.
+   */
   static final long serialVersionUID = 1521711792217232256L;
 
-  private Throwable exception = null;
+  /**
+   * The cause of this exception (duplicates the one stored in Throwable).
+   *
+   * @serial the exception cause
+   */
+  private final Throwable exception;
 
   /**
-   * Create an error without a message.
+   * Create an error without a message. The cause is initialized as null.
    */
   public ExceptionInInitializerError()
   {
-      super();
+    this((String) null);
   }
 
   /**
-   * Create an error with a message.
+   * Create an error with a message. The cause is initialized as null.
+   *
+   * @param s the message
    */
   public ExceptionInInitializerError(String s)
   {
     super(s);
+    exception = null;
   }
 
   /**
    * Creates an error an saves a reference to the <code>Throwable</code>
-   * object.
+   * object. The message string is null.
    *
    * @param t the exception thrown
    */
   public ExceptionInInitializerError(Throwable t)
   {
-      super(t.toString());
+    super(null);
+    initCause(t);
     exception = t;
   }
 
   /**
-   * Return the exception that caused this error to be created.
-   * @return the stored <code>Throwable</code> object or <code>null</code>
-   * if this <code>ExceptionInInitializerError</code> has no stored
-   * <code>Throwable</code> object.
+   * Return the exception that caused this error to be created. This is a
+   * legacy method; the preferred choice now is {@link Throwable#getCause()}.
+   *
+   * @return the cause, or null if unknown
    */
   public Throwable getException()
   {
@@ -104,52 +111,13 @@ public class ExceptionInInitializerError extends LinkageError
   }
 
   /**
-   * Print a stack trace of the exception that occurred.
-   */
-  public void printStackTrace()
-    {
-      if (exception == null)
-	{
-	  super.printStackTrace();
-	}
-      else
-	{
-	  System.err.print(this.getClass() + ": ");
-	  exception.printStackTrace();
-	}
-    }
-
-  /**
-   * Print a stack trace of the exception that occurred to 
-   * the specified <code>PrintStream</code>.
-   */
-  public void printStackTrace(PrintStream ps)
-    {
-      if (exception == null)
-	{
-	  super.printStackTrace(ps);
-	}
-      else
-	{
-	  ps.print(this.getClass() + ": ");
-	  exception.printStackTrace(ps);
-	}
-    }
-
-  /**
-   * Print a stack trace of the exception that occurred to 
-   * the specified <code>PrintWriter</code>.
+   * Return the exception that cause this error to be created.
+   *
+   * @return the cause, or null if unknown
+   * @since 1.4
    */
-  public void printStackTrace(PrintWriter pw)
-    {
-      if (exception == null)
+  public Throwable getCause()
   {
-	  super.printStackTrace(pw);
-	}
-      else
-	{
-	  pw.print(this.getClass() + ": ");
-	  exception.printStackTrace(pw);
-	}
+    return exception;
   }
 }

libjava/java/lang/IllegalAccessError.java

-/* IllegalAccessError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalAccessError.java -- thrown when linking to an inaccessible member
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,12 +38,6 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
  * An <code>IllegalAccessError</code> is thrown when an attempt is made to
  * call a method, or access or modify a field that the application does not
@@ -52,26 +46,28 @@ package java.lang;
  * changed in a way that is incompatible with the previously compiled
  * application.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class IllegalAccessError extends IncompatibleClassChangeError
 {
-  static final long serialVersionUID = -8988904074992417891L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -8988904074992417891L;
 
   /**
    * Create an error without a message.
    */
   public IllegalAccessError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public IllegalAccessError(String s)
   {

libjava/java/lang/IllegalAccessException.java

-/* IllegalAccessException.java -- exception thrown when trying to load a 
-   class that is not public and in another package.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalAccessException.java -- thrown on attempt to reflect on
+   inaccessible data
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,42 +39,54 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * Thrown in two cases.  The first is when try to load a class that is
- * not public and in another package using specific methods from 
- * <code>ClassLoader</code> and <code>Class</code>.  The second case is
- * when trying to create a new instance of a class to which you do not have
- * access to the zero argument constructor as in using the 
- * <code>newsInstance</code> method of class <code>Class</code>.
- *
- * @since JDK 1.0
+ * Thrown whenever a reflective method tries to do something that the
+ * compiler would not allow.  For example, using reflection to set a private
+ * variable that belongs to a class in another package is bad.
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @see Class#newInstance()
+ * @see Field#set(Object, Object)
+ * @see Field#setBoolean(Object, boolean)
+ * @see Field#setByte(Object, byte)
+ * @see Field#setShort(Object, short)
+ * @see Field#setChar(Object, char)
+ * @see Field#setInt(Object, int)
+ * @see Field#setLong(Object, long)
+ * @see Field#setFloat(Object, float)
+ * @see Field#setDouble(Object, double)
+ * @see Field#get(Object)
+ * @see Field#getBoolean(Object)
+ * @see Field#getByte(Object)
+ * @see Field#getShort(Object)
+ * @see Field#getChar(Object)
+ * @see Field#getInt(Object)
+ * @see Field#getLong(Object)
+ * @see Field#getFloat(Object)
+ * @see Field#getDouble(Object)
+ * @see Method#invoke(Object, Object[])
+ * @see Constructor#newInstance(Object[])
+ * @status updated to 1.4
  */
 public class IllegalAccessException extends Exception
 {
-  static final long serialVersionUID = 6616958222490762034L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 6616958222490762034L;
 
   /**
    * Create an exception without a message.
    */
   public IllegalAccessException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalAccessException(String s)
   {

libjava/java/lang/IllegalArgumentException.java

-/* IllegalArgumentException.java -- exception may be thrown when a method
-   is passed an illegal or inappropriate argument.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalArgumentException.java -- thrown when a method is passed an
+   illegal or inappropriate argument
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,38 +38,35 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * When a method is passed an illegal or inappropriate argument 
- * this exception may be thrown.
- *
- * @since JDK 1.0
+ * Thrown when a method is passed an illegal or inappropriate argument. For
+ * example:<br>
+ * <pre>
+ * wait(-1);
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class IllegalArgumentException extends RuntimeException
 {
-  static final long serialVersionUID = -5365630128856068164L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -5365630128856068164L;
 
   /**
    * Create an exception without a message.
    */
   public IllegalArgumentException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalArgumentException(String s)
   {

libjava/java/lang/IllegalMonitorStateException.java

-/* IllegalMonitorStateException.java -- exception thrown when a thread 
-   attempts to wait on an object's monitor.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalMonitorStateException.java -- thrown when trying to wait or
+   notify a monitor that is not owned
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,40 +39,37 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * If a thread attempts to wait on an object's monitor then
- * <code>IllegalMonitorStateException</code> can be thrown.  This
- * exception is also thrown to give a message to other threads also waiting
- * on an object's monitor without owning the monitor.
- *
- * @since JDK 1.0
+ * Thrown when a thread attempts to wait or notify on a monitor that it
+ * does not own (ie. it has not synchronized on the object). For example:<br>
+ * <pre>
+ * void m() {
+ *   notify();
+ * }
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class IllegalMonitorStateException extends RuntimeException
 {
-  static final long serialVersionUID = 3713306369498869069L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 3713306369498869069L;
 
   /**
    * Create an exception without a message.
    */
   public IllegalMonitorStateException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalMonitorStateException(String s)
   {

libjava/java/lang/IllegalStateException.java

-/* IllegalStateException.java -- exception thrown when invoking a method at
-   an illegal or inappropriate time.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalStateException.java -- thrown when invoking a method at
+   an illegal or inappropriate time
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,38 +39,39 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * Invoking a method at an illegal or inappropriate time can result
- * in an <code>IllegalStateException</code>.
- *
- * @since JDK 1.1
+ * Thrown when a method is invoked at an illegal or inappropriate time. For
+ * example:<br>
+ * <pre>
+ * void m(Collecion c)
+ * {
+ *   c.iterator().remove();
+ * }
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @since 1.1
+ * @status updated to 1.4
  */
 public class IllegalStateException extends RuntimeException
 {
-  static final long serialVersionUID = -1848914673093119416L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = -1848914673093119416L;
 
   /**
    * Create an exception without a message.
    */
   public IllegalStateException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalStateException(String s)
   {

libjava/java/lang/IllegalThreadStateException.java

-/* IllegalThreadStateException.java -- exception thrown when trying to
-   suspend or resume a Thread when it is not in an appropriate state
-   for the operation.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IllegalThreadStateException.java -- thrown when trying to manipulate a
+   Thread when it is not in an appropriate state
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -40,38 +39,34 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * When trying to <code>suspend</code> or <code>resume</code> an object
- * of class <code>Thread</code> when it is not in an appropriate state
- * for the operation.
+ * Thrown When trying to manipulate a Thread which is in an inappropriate
+ * state. Since the documentation suggests that this can happen with
+ * <code>Thread.suspend</code> or <code>Thread.resume</code>, but these
+ * two methods are deprecated, this exception is likely very rare.
  *
- * @since JDK 1.0
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class IllegalThreadStateException extends IllegalArgumentException
 {
-  static final long serialVersionUID = -7626246362397460174L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -7626246362397460174L;
 
   /**
    * Create an exception without a message.
    */
   public IllegalThreadStateException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IllegalThreadStateException(String s)
   {

libjava/java/lang/IncompatibleClassChangeError.java

-/* IncompatibleClassChangeError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IncompatibleClassChangeError.java -- thrown for binary incompatible classes
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,37 +38,33 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
- * An <code>IncompatibleClassChangeError</code> is thrown when the 
- * definition of a class used by the currently executing method has
- * changed in an incompatible way.
- *
- * @since JDK 1.0
+ * An <code>IncompatibleClassChangeError</code> is thrown when the definition
+ * of a class used by the currently executing method has changed in an
+ * incompatible way.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class IncompatibleClassChangeError extends LinkageError
 {
-  static final long serialVersionUID = -4914975503642802119L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4914975503642802119L;
 
   /**
    * Create an error without a message.
    */
   public IncompatibleClassChangeError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public IncompatibleClassChangeError(String s)
   {

libjava/java/lang/IndexOutOfBoundsException.java

-/* IndexOutOfBoundsException.java -- exception thrown when attempting to 
-   access an index which is out of bounds on objects like String, Array,
-   or Vector.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* IndexOutOfBoundsException.java -- thrown for an invalid index
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -40,41 +38,35 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
  * This exception can be thrown to indicate an attempt to access an
  * index which is out of bounds on objects like String, Array, or Vector.
  * Usually any negative integer less than or equal to -1 and positive 
  * integer greater than or equal to the size of the object is an index
  * which would be out of bounds.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class IndexOutOfBoundsException extends RuntimeException
 {
-  static final long serialVersionUID = 234122996006267687L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 234122996006267687L;
 
   /**
    * Create an exception without a message.
    */
   public IndexOutOfBoundsException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public IndexOutOfBoundsException(String s)
   {

libjava/java/lang/InheritableThreadLocal.java

-/* java.lang.InheritableThreadLocal
-   Copyright (C) 2000, 2001 Free Software Foundation, Inc.
+/* InheritableThreadLocal -- a ThreadLocal which inherits values across threads
+   Copyright (C) 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,140 +38,101 @@ exception statement from your version. */
 package java.lang;
 
 import java.util.Iterator;
-import java.util.HashSet;
-import java.util.Map;
-import java.util.Set;
+import java.util.List;
+import java.util.ArrayList;
 import java.util.WeakHashMap;
 
 /**
- * ThreadLocal whose value is inherited by child Threads.
- * The value of the InheritableThreadLocal associated with the (parent) Thread
- * on the moment that it creates a new (child) Thread is set as the value that
- * is associated with the new (child) Thread.
- * <p>
- * It is possible to make the value associated with the child Thread a function
- * of the value that is associated with the parent Thread by overriding the
- * <code>childValue()</code> method.
+ * A ThreadLocal whose value is inherited by child Threads. The value of the
+ * InheritableThreadLocal associated with the (parent) Thread is copied to
+ * the new (child) Thread at the moment of creation.
  *
+ * <p>It is possible to make the value associated with the child Thread a
+ * function of the value that is associated with the parent Thread by
+ * overriding the <code>childValue()</code> method. The utility of this class
+ * is in transferring items like User ID or Transaction ID across threads
+ * automatically.
+ *
+ * @author Mark Wielaard <mark@klomp.org>
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see ThreadLocal
  * @since 1.2
- * @author Mark Wielaard (mark@klomp.org)
+ * @status updated to 1.4
  */
-public class InheritableThreadLocal extends ThreadLocal {
-	
+public class InheritableThreadLocal extends ThreadLocal
+{
   /**
-	 * Maps Threads to a Set of InheritableThreadLocals
-	 * (the heritage of that Thread).
-	 * Uses a WeakHashMap so if the Thread is garbage collected the reference
-	 * to that Set disappears.
-	 * Both <code>AddToHeritage</code> access and modify it so they have to
-	 * synchronize on the threadMap when they do.
+   * Maps Threads to a List of InheritableThreadLocals (the heritage of that
+   * Thread). Uses a WeakHashMap so if the Thread is garbage collected the
+   * List can be collected, too. Maps to a list in case the user overrides
+   * equals.
    */
-	private static Map threadMap = new WeakHashMap();
+  private static final WeakHashMap threadMap = new WeakHashMap();
 
   /**
    * Creates a new InheritableThreadLocal that has no values associated
    * with it yet.
    */
-	public InheritableThreadLocal() {
-		super();
-	}
-	
-	/**
-	 * Determines the value associated with a newly created child Thread
-	 * as a function of the value associated with the currently executing
-	 * (parent) Thread.
-	 * <p>
-	 * The default implementation just returns the parentValue.
-	 */
-	protected Object childValue(Object parentValue) {
-		return parentValue;
+  public InheritableThreadLocal()
+  {
+    Thread currentThread = Thread.currentThread();
+    // Note that we don't have to synchronize, as only this thread will
+    // ever modify the returned heritage.
+    List heritage = (List) threadMap.get(currentThread);
+    if (heritage == null)
+      {
+        heritage = new ArrayList();
+        threadMap.put(currentThread, heritage);
       }
-	
-	/**
-	 * Adds this <code>InheritableThreadLocal</code> to the heritage of the
-	 * current Thread and returns the value of the <code>ThreadLocal</code>
-	 * for the Thread. The value will be either the last value that the
-	 * current Thread has set, or the childValue of the last value that the
-	 * parent Thread set before the current Thread was created, or the
-	 * initialValue of the <code>ThreadLocal</code>.
-	 *
-	 * @see ThreadLocal#get()
-	 */
-	public Object get() {
-		addToHeritage(); 
-		return super.get();
+    heritage.add(this);
   }
 
   /**
-	 * Adds this <code>InheritableThreadLocal</code> to the heritage of the
-	 * current Thread and sets the value of the <code>ThreadLocal</code>
-	 * for the Thread.
+   * Determines the value associated with a newly created child Thread as a
+   * function of the value associated with the currently executing (parent)
+   * Thread. The default implementation just returns the parentValue.
    *
-	 * @see ThreadLocal#set(Object)
+   * @param parentValue the value of this object in the parent thread at
+   *        the moment of creation of the child
+   * @return the initial value for the child thread
    */
-	public void set(Object value) {
-		addToHeritage();
-		super.set(value);
-	}
-	
-	/**
-	 * Adds this <code>InheritableThreadLocal</code> to the heritage
-	 * of the current Thread.
-	 */
-	private void addToHeritage() {
-		Thread currentThread = Thread.currentThread();
-		Set heritage;
-		synchronized(threadMap) {
-			heritage = (Set)threadMap.get(currentThread);
-		}
-		// Note that we don't have to synchronize on the heritage Set
-		// since only this Thread (or the parent Thread when creating
-		// the heritage) ever modifies it.
-		if (heritage == null) {
-			heritage = new HashSet();
-			synchronized(threadMap) {
-				threadMap.put(currentThread, heritage);
-			}
-		}
-		if (!heritage.contains(this)) {
-			heritage.add(this);
-		}
+  protected Object childValue(Object parentValue)
+  {
+    return parentValue;
   }
 
   /**
    * Generates the childValues of all <code>InheritableThreadLocal</code>s
    * that are in the heritage of the current Thread for the newly created
-	 * childThread.
-	 * Should be called from the contructor of java.lang.Thread.
+   * childThread. Should be called from the contructor Thread.
+   *
+   * @param childThread the newly created thread, to inherit from this thread
+   * @see Thread#Thread(ThreadGroup, Runnable, String)
    */
-	static void newChildThread(Thread childThread) {
-		// The currentThread is the parent of the new thread
+  static void newChildThread(Thread childThread)
+  {
+    // The currentThread is the parent of the new thread.
     Thread parentThread = Thread.currentThread();
-		
-		// Inherit all the InheritableThreadLocals of the parent thread
-		Set heritage;
-		synchronized(threadMap) {
-			heritage = (Set)threadMap.get(parentThread);
-		}
-		// Note that we don't have to synchronize on the heritage Set
-		// since only this Thread (or the parent Thread when creating
-		// the heritage) ever modifies it.
-		if (heritage != null) {
-			synchronized(threadMap) {
-				threadMap.put(childThread, new HashSet(heritage));
-			}
-			// And constructs all the new child values
-			// (has to be done now that we are executing in the parentThread)
+    // Note that we don't have to synchronize, as only this thread will
+    // ever modify the returned heritage.
+    ArrayList heritage = (ArrayList) threadMap.get(parentThread);
+    if (heritage != null)
+      {
+        threadMap.put(childThread, heritage.clone());
+        // Perform the inheritance.
         Iterator it = heritage.iterator();
-			while (it.hasNext()) {
-				InheritableThreadLocal local =
-					(InheritableThreadLocal) it.next();
-				// Note that the parentValue cannot be null
-				// If it was it would not be in the heritage
-				Object parentValue = local.get(parentThread).getValue();
-				Object childValue = local.childValue(parentValue);
-				ThreadLocal.Value v = new ThreadLocal.Value(childValue);
-				local.set(childThread, v);
+        int i = heritage.size();
+        while (--i >= 0)
+          {
+            InheritableThreadLocal local = (InheritableThreadLocal) it.next();
+            Object parentValue = local.valueMap.get(parentThread);
+            if (parentValue != null)
+              {
+                Object childValue = local.childValue(parentValue == NULL
+                                                     ? null : parentValue);
+                local.valueMap.put(childThread, (childValue == null
+                                                 ? NULL : parentValue));
+              }
           }
       }
   }

libjava/java/lang/InstantiationError.java

-/* InstantiationError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* InstantiationError.java -- thrown when the linker cannot create an instance
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,40 +38,35 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
  * An <code>InstantiationError</code> is thrown when an attempt is made to
  * create an instance of an abstract class or an interface.  Because this
- * error is usually caught by a compiler, 
- * the error only occurs at runtime when the definition of a class has
- * changed in a way that is incompatible with the previously compiled 
- * application.
- *
- * @since JDK 1.0
+ * error is usually caught by a compiler, the error only occurs at runtime
+ * when the definition of a class has changed in a way that is incompatible
+ * with the previously compiled application.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class InstantiationError extends IncompatibleClassChangeError
 {
-  static final long serialVersionUID = -4885810657349421204L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4885810657349421204L;
 
   /**
    * Create an error without a message.
    */
   public InstantiationError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public InstantiationError(String s)
   {

libjava/java/lang/InstantiationException.java

-/* InstantiationException.java -- exception thrown when trying to instantiate
-   interfaces and abstract classes using Class.newInstance.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* InstantiationException.java -- thrown when reflection cannot create an
+   instance
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,39 +39,33 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.
- * Interfaces and abstract classes cannot be instantiated using the 
- * <code>newInstance</code> method of class <code>Class</code>.  Trying
- * to do so results in this exception being thrown.
- *
- * @since JDK 1.0
+ * Thrown when an attempt is made to use reflection to build a
+ * non-instantiable class (an interface or abstract class).
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @see Class#newInstance()
+ * @status updated to 1.4
  */
 public class InstantiationException extends Exception
 {
-  static final long serialVersionUID = -8441929162975509110L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -8441929162975509110L;
 
   /**
    * Create an exception without a message.
    */
   public InstantiationException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public InstantiationException(String s)
   {

libjava/java/lang/InternalError.java

-/* InternalError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* InternalError.java -- thrown when the VM encounters an internal error
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,36 +38,32 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
  * An <code>InternalError</code> is thrown when a mystical error has
  * occurred in the Java Virtual Machine.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class InternalError extends VirtualMachineError
 {
-  static final long serialVersionUID = -9062593416125562365L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -9062593416125562365L;
 
   /**
    * Create an error without a message.
    */
   public InternalError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public InternalError(String s)
   {

libjava/java/lang/InterruptedException.java

-/* InterruptedException.java -- exception thrown when a thread interrupts 
-   another thread which was previously sleeping, waiting, or paused in some 
-   other way.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* InterruptedException.java -- thrown when a thread is interrupted
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -40,39 +38,40 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.
  * Thrown when a thread interrupts another thread which was previously
  * sleeping, waiting, or paused in some other way.  See the
  * <code>interrupt</code> method of class <code>Thread</code>.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @see Object#wait()
+ * @see Object#wait(long)
+ * @see Object#wait(long, int)
+ * @see Thread#sleep(long)
+ * @see Thread#interrupt()
+ * @see Thread#interrupted()
+ * @status updated to 1.4
  */
 public class InterruptedException extends Exception
 {
-  static final long serialVersionUID = 6700697376100628473L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 6700697376100628473L;
 
   /**
    * Create an exception without a message.
    */
   public InterruptedException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   *
+   * @param s the message
    */
   public InterruptedException(String s)
   {

libjava/java/lang/LinkageError.java

-/* LinkageError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* LinkageError.java -- thrown when classes valid at separate compile times
+   cannot be linked to each other
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,37 +39,33 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
- * Subclasses of <code>LinkageError</code> are thrown to indicate 
- * a class which is depended upon by another class has incompatibly 
- * changed after the compilation of the latter class.
- *
- * @since JDK 1.0
+ * Subclasses of <code>LinkageError</code> are thrown to indicate that two
+ * classes which were compatible at separate compilation times cannot be
+ * linked to one another.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class LinkageError extends Error
 {
-  static final long serialVersionUID = 3579600108157160122L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 3579600108157160122L;
 
   /**
    * Create an error without a message.
    */
   public LinkageError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public LinkageError(String s)
   {

libjava/java/lang/NegativeArraySizeException.java

-/* NegativeArraySizeException.java -- exception thrown when an attempt is 
-   made to create an array with a negative size.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NegativeArraySizeException.java -- thrown on attempt to create array
+   with a negative size
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,38 +39,36 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
  * Thrown when an attempt is made to create an array with a negative
- * size.
- *
- * @since JDK 1.0
+ * size. For example:<br>
+ * <pre>
+ * int i = -1;
+ * int[] array = new int[i];
+ * </pre>
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class NegativeArraySizeException extends RuntimeException
 {
-  static final long serialVersionUID = -8960118058596991861L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -8960118058596991861L;
 
   /**
    * Create an exception without a message.
    */
   public NegativeArraySizeException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NegativeArraySizeException(String s)
   {

libjava/java/lang/NoClassDefFoundError.java

-/* NoClassDefFoundError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoClassDefFoundError.java -- thrown when a ClassLoader cannot find a class
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,12 +38,6 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
  * A <code>NoClassDefFoundError</code> is thrown when a classloader or the
  * Java Virtual Machine tries to load a class and no definition of the class
@@ -52,26 +46,28 @@ package java.lang;
  * because the missing class definition existed when the currently executing 
  * class was compiled, but now that definition cannot be found.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class NoClassDefFoundError extends LinkageError
 {
-  static final long serialVersionUID = 9095859863287012458L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 9095859863287012458L;
 
   /**
    * Create an error without a message.
    */
   public NoClassDefFoundError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public NoClassDefFoundError(String s)
   {

libjava/java/lang/NoSuchFieldError.java

-/* NoSuchFieldError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoSuchFieldError.java -- thrown when the linker does not find a field
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,37 +38,34 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
  * A <code>NoSuchFieldError</code> is thrown if an application attempts
- * to access the field of an object and that object no longer has that 
- * field.  
- *
- * @since JDK 1.0
+ * to access a field of a class, and that class no longer has that field.
+ * This is normally detected by the compiler, so it signals that you are
+ * using binary incompatible class versions.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class NoSuchFieldError extends IncompatibleClassChangeError
 {
-  static final long serialVersionUID = -3456430195886129035L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -3456430195886129035L;
 
   /**
    * Create an error without a message.
    */
   public NoSuchFieldError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public NoSuchFieldError(String s)
   {

libjava/java/lang/NoSuchFieldException.java

-/* NoSuchFieldException.java -- exception thrown to indicate the class does
-   not have the specified field.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoSuchFieldException.java -- thrown when reflecting a non-existant field
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,37 +38,33 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * Thrown to indicate the class does not have the specified field.
- *
- * @since JDK 1.1
+ * Thrown to indicate the class does not have the specified field. This is
+ * caused by a variety of reflection methods, when looking up a field by name.
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @since 1.1
+ * @status updated to 1.4
  */
 public class NoSuchFieldException extends Exception
 {
-  static final long serialVersionUID = -6143714805279938260L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = -6143714805279938260L;
 
   /**
    * Create an exception without a message.
    */
   public NoSuchFieldException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NoSuchFieldException(String s)
   {

libjava/java/lang/NoSuchMethodError.java

-/* NoSuchMethodError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoSuchMethodError.java -- thrown when the linker does not find a method
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,25 +38,21 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
  * A <code>NoSuchMethodError</code> is thrown if an application attempts
- * to access a method of a class, and that class no longer has that 
- * method.  
- *
- * @since JDK 1.0
+ * to access a method of a class, and that class no longer has that method.
+ * This is normally detected by the compiler, so it signals that you are
+ * using binary incompatible class versions.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class NoSuchMethodError extends IncompatibleClassChangeError
 {
+  /**
+   * Compatible with JDK 1.0+.
+   */
   static final long serialVersionUID = -3765521442372831335L;
 
   /**
@@ -64,11 +60,12 @@ public class NoSuchMethodError extends IncompatibleClassChangeError
    */
   public NoSuchMethodError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public NoSuchMethodError(String s)
   {

libjava/java/lang/NoSuchMethodException.java

-/* NoSuchMethodException.java -- exception thrown to indicate the class
-   does not have the specified method.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NoSuchMethodException.java -- thrown when reflecting a non-existant method
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,37 +38,32 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * Thrown to indicate the class does not have the specified method.
- *
- * @since JDK 1.0
+ * Thrown to indicate the class does not have the specified method. This is
+ * caused by a variety of reflection methods, when looking up a method by name.
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class NoSuchMethodException extends Exception
 {
-  static final long serialVersionUID = 5034388446362600923L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 5034388446362600923L;
 
   /**
    * Create an exception without a message.
    */
   public NoSuchMethodException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NoSuchMethodException(String s)
   {

libjava/java/lang/NullPointerException.java

-/* NullPointerException.java -- exception thrown when attempting to use null
-   where an object is required.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NullPointerException.java -- thrown when using null instead of an object
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,38 +38,42 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
  * Thrown when attempting to use <code>null</code> where an object
- * is required, such as when accessing an instance method of a null object.
- *
- * @since JDK 1.0
+ * is required. The Virtual Machine automatically throws this exception
+ * for the following:<br><ul>
+ * <li>Calling an instance method on a null object</li>
+ * <li>Accessing or modifying a field of a null object</li>
+ * <li>Taking the array length of a null array</li>
+ * <li>Accessing or modifying the slots of a null array</li>
+ * <li>Throwing a null Throwable</li>
+ * <li>Synchronizing on a null object</li>
+ * </ul>
+ * <p>Applications should also throw NullPointerExceptions whenever
+ * <code>null</code> is an inappropriate parameter to a method.
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class NullPointerException extends RuntimeException
 {
-  static final long serialVersionUID = 5162710183389028792L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 5162710183389028792L;
 
   /**
    * Create an exception without a message.
    */
   public NullPointerException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NullPointerException(String s)
   {

libjava/java/lang/NumberFormatException.java

-/* NumberFormatException.java -- exception may be thrown when attempting to
-   convert a String to one of the numeric types, but the operation fails.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* NumberFormatException.java -- thrown when parsing a bad string as a number
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,39 +38,33 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
  * Can be thrown when attempting to convert a <code>String</code> to
  * one of the numeric types, but the operation fails because the string
  * has the wrong format.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class NumberFormatException extends IllegalArgumentException
 {
-  static final long serialVersionUID = -2848938806368998894L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -2848938806368998894L;
 
   /**
    * Create an exception without a message.
    */
   public NumberFormatException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public NumberFormatException(String s)
   {

libjava/java/lang/OutOfMemoryError.java

-/* OutOfMemoryError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* OutOfMemoryError.java -- thrown when a memory allocation fails
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,37 +38,33 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
- * When the Java Virtual Machine is unable to allocate an object because it 
- * is out of memory and no more memory could be made available by the 
- * garbage collector an <code>OutOfMemoryError</code> is thrown.
- *
- * @since JDK 1.0
+ * Thrown when the Java Virtual Machine is unable to allocate an object
+ * because it is out of memory and no more memory could be made available
+ * by the garbage collector.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class OutOfMemoryError extends VirtualMachineError
 {
-  static final long serialVersionUID = 8228564086184010517L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 8228564086184010517L;
 
   /**
    * Create an error without a message.
    */
   public OutOfMemoryError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public OutOfMemoryError(String s)
   {

libjava/java/lang/Process.java

-/* Process.java - Represent spawned system process.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* Process.java - Represent spawned system process
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -41,9 +41,6 @@ package java.lang;
 import java.io.OutputStream;
 import java.io.InputStream;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- */
-
 /**
  * An instance of a subclass of <code>Process</code> is created by the
  * <code>Runtime.exec</code> methods.  Methods in <code>Process</code>
@@ -51,36 +48,56 @@ import java.io.InputStream;
  * subprocess, destroy a subprocess, obtain the exit value from a
  * subprocess, and wait for a subprocess to complete.
  *
- * @since JDK 1.0
+ * <p>This is dependent on the platform, and some processes (like native
+ * windowing processes, 16-bit processes in Windows, or shell scripts) may
+ * be limited in functionality. Because some platforms have limited buffers
+ * between processes, you may need to provide input and read output to prevent
+ * the process from blocking, or even deadlocking.
+ *
+ * <p>Even if all references to this object disapper, the process continues
+ * to execute to completion. There are no guarantees that the
+ * subprocess execute asynchronously or concurrently with the process which
+ * owns this object.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
+ * @see Runtime#exec(String[], String[], File)
+ * @since 1.0
+ * @status updated to 1.4
  */
 public abstract class Process
 {
   /**
    * Empty constructor does nothing.
    */
-  public Process() { }
+  public Process()
+  {
+  }
 
   /**
-   * Obtain the output stream of the subprocess.  It may help to 
-   * associate this stream as the redirected STDIN file descriptor of
-   * the subprocess.
+   * Obtain the output stream that sends data to the subprocess. This is
+   * the STDIN of the subprocess. When implementing, you should probably
+   * use a buffered stream.
+   *
+   * @return the output stream that pipes to the process input
    */
   public abstract OutputStream getOutputStream();
 
   /**
-   * Obtain the input stream of the subprocess.  It may help to 
-   * associate this stream as the redirected STDOUT file descriptor of
-   * the subprocess.
+   * Obtain the input stream that receives data from the subprocess. This is
+   * the STDOUT of the subprocess. When implementing, you should probably
+   * use a buffered stream.
+   *
+   * @return the input stream that pipes data from the process output
    */
   public abstract InputStream getInputStream();
 
   /**
-   * Obtain the error input stream of the subprocess.  It may help to 
-   * associate this stream as the redirected STDERR file descriptor of
-   * the subprocess.
+   * Obtain the input stream that receives data from the subprocess. This is
+   * the STDERR of the subprocess. When implementing, you should probably
+   * use a buffered stream.
+   *
+   * @return the input stream that pipes data from the process error output
    */
   public abstract InputStream getErrorStream();
 
@@ -89,23 +106,18 @@ public abstract class Process
    * has terminated. If the process has already terminated then the method
    * immediately returns with the exit value of the subprocess.
    *
-   * @returns the exit value of the subprocess.  A return of <code>0</code> 
-   * denotes normal process termination by convention.
-   *
-   * @throws InterruptedException is thrown if another thread interrupts 
-   * the waiting thread.  The waiting thread stops waiting.
+   * @return the subprocess exit value; 0 conventionally denotes success
+   * @throws InterruptedException if another thread interrups the blocked one
    */
-  public abstract int waitFor()
-    throws InterruptedException;
+  public abstract int waitFor() throws InterruptedException;
 
   /**
    * When a process terminates there is associated with that termination
    * an exit value for the process to indicate why it terminated. A return
    * of <code>0</code> denotes normal process termination by convention.
    *
-   * @returns the exit value of the subprocess.
-   * @throws IllegalThreadStateException is thrown if the subprocess 
-   * represented by the subclass of this class has not yet terminated.
+   * @return the exit value of the subprocess
+   * @throws IllegalThreadStateException if the subprocess has not terminated
    */
   public abstract int exitValue();
 
@@ -113,5 +125,4 @@ public abstract class Process
    * Kills the subprocess and all of its children forcibly.
    */
   public abstract void destroy();
-
-}
+} // class Process

libjava/java/lang/Runnable.java

-/* java.lang.Runnable
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* Runnable -- interface for a method tied to an Object; often for Threads
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,12 +38,6 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Complete.
- */
-
 /**
  * Runnable is an interface you implement to indicate that your class can be
  * executed as the main part of a Thread, among other places.  When you want
@@ -52,14 +46,17 @@ package java.lang;
  *
  * @author Paul Fisher
  * @author Tom Tromey <tromey@cygnus.com>
+ * @see Thread
+ * @since 1.0
+ * @status updated to 1.4
  */
-
 public interface Runnable
 {
   /**
    * This method will be called by whoever wishes to run your class
-   * implementing Runnable.
-   * @since JDK1.0
+   * implementing Runnable. Note that there are no restrictions on what
+   * you are allowed to do in the run method, except that you cannot
+   * throw a checked exception.
    */
   void run();
 }

libjava/java/lang/RuntimePermission.java

-/* RuntimePermission.java
-   Copyright (C) 1998, 2000 Free Software Foundation, Inc.
+/* RuntimePermission.java -- permission for a secure runtime action
+   Copyright (C) 1998, 2000, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,7 +38,7 @@ exception statement from your version. */
 
 package java.lang;
 
-import java.security.*;
+import java.security.BasicPermission;
 
 /**
  * A <code>RuntimePermission</code> contains a permission name, but no
@@ -56,109 +56,153 @@ import java.security.*;
  * <br>
  *
  * The following table provides a list of all the possible RuntimePermission
- * permission names with a description of what that permission allows.
- * <br>
+ * permission names with a description of what that permission allows.<br>
  * <table border=1>
- * <tr><th>Permission Name</th><th>Permission Allows</th></tr>
+ * <tr><th>Permission Name</th><th>Permission Allows</th><th>Risks</th</tr>
  * <tr>
  *   <td><code>createClassLoader</code></td>
- *   <td>creation of a class loader</td></tr>
+ *   <td>creation of a class loader</td>
+ *   <td>a class loader can load rogue classes which bypass all security
+ *       permissions</td></tr>
  * <tr>
  *   <td><code>getClassLoader</code></td>
- *   <td>retrieval of the class loader for the calling class</td></tr>
+ *   <td>retrieval of the class loader for the calling class</td>
+ *   <td>rogue code could load classes not otherwise available</td></tr>
  * <tr>
  *   <td><code>setContextClassLoader</code></td>
- *   <td>allows the setting of the context class loader used by a 
- *       thread including system threads</td></tr>
+ *   <td>allows the setting of the context class loader used by a thread</td>
+ *   <td>rogue code could change the context class loader needed by system
+ *       threads</td></tr>
  * <tr>
  *   <td><code>setSecurityManager</code></td>
- *   <td>allows the application to replace the security manager with
- *       another, possibly less restrictive one.</td></tr>
+ *   <td>allows the application to replace the security manager</td>
+ *   <td>the new manager may be less restrictive, so that rogue code can
+ *       bypass existing security checks</td></tr>
  * <tr>
  *   <td><code>createSecurityManager</code></td>
- *   <td>allows the application to create a new security manager</td></tr>
+ *   <td>allows the application to create a new security manager</td>
+ *   <td>rogue code can use the new security manager to discover information
+ *       about the execution stack</td></tr>
  * <tr>
  *   <td><code>exitVM</code></td>
- *   <td>allows the application to halt the virtual machine</td></tr>
+ *   <td>allows the application to halt the virtual machine</td>
+ *   <td>rogue code can mount a denial-of-service attack by killing the
+ *       virtual machine</td></tr>
+ * <tr>
+ *   <td><code>shutdownHooks</code></td>
+ *   <td>allows registration and modification of shutdown hooks</td>
+ *   <td>rogue code can add a hook that interferes with clean
+ *       virtual machine shutdown</td></tr>
  * <tr>
  *   <td><code>setFactory</code></td>
  *   <td>allows the application to set the socket factory for socket,
- *       server socket, stream handler, or RMI socket factory.</td></tr>
+ *       server socket, stream handler, or RMI socket factory.</td>
+ *   <td>rogue code can create a rogue network object which mangles or
+ *       intercepts data</td></tr>
  * <tr>
  *   <td><code>setIO</code></td>
  *   <td>allows the application to set System.out, System.in, and
- *       System.err</td></tr>
+ *       System.err</td>
+ *   <td>rogue code could sniff user input and intercept or mangle
+ *       output</td></tr>
  * <tr>
  *   <td><code>modifyThread</code></td>
  *   <td>allows the application to modify any thread in the virtual machine
  *       using any of the methods <code>stop</code>, <code>resume</code>,
  *       <code>suspend</code>, <code>setPriority</code>, and
- *       <code>setName</code> of classs <code>Thread</code></td></tr>
+ *       <code>setName</code> of classs <code>Thread</code></td>
+ *   <td>rogue code could adversely modify system or user threads</td></tr>
  * <tr>
  *   <td><code>stopThread</code></td>
  *   <td>allows the application to <code>stop</code> any thread it has
- *       access to in the system</td></tr>
+ *       access to in the system</td>
+ *   <td>rogue code can stop arbitrary threads</td></tr>
  * <tr>
  *   <td><code>modifyThreadGroup</td>
  *   <td>allows the application to modify thread groups using any of the
  *       methods <code>destroy</code>, <code>resume</code>,
  *       <code>setDaemon</code>, <code>setMaxPriority</code>,
  *       <code>stop</code>, and <code>suspend</code> of the class
- *       <code>ThreadGroup</code></td></tr>
+ *       <code>ThreadGroup</code></td>
+ *   <td>rogue code can mount a denial-of-service attack by changing run
+ *       priorities</td></tr>
  * <tr>
  *   <td><code>getProtectionDomain</code></td>
- *   <td></td></tr>
+ *   <td>retrieve a class's ProtectionDomain</td>
+ *   <td>rogue code can gain information about the security policy, to
+ *       prepare a better attack</td></tr>
  * <tr>
  *   <td><code>readFileDescriptor</code></td>
- *   <td></td></tr>
+ *   <td>read a file descriptor</td>
+ *   <td>rogue code can read sensitive information</td></tr>
  * <tr>
- *   <td><code>writeFileDescriptor</code</td>
- *   <td></td></tr>
+ *   <td><code>writeFileDescriptor</code></td>
+ *   <td>write a file descriptor</td>
+ *   <td>rogue code can write files, including viruses, and can modify the
+ *       virtual machine binary; if not just fill up the disk</td></tr>
  * <tr>
- *   <td><code>loadLibrary.{library name}</code></td>
- *   <td></td></tr>
+ *   <td><code>loadLibrary.<code><em>library name</em></td>
+ *   <td>dynamic linking of the named library</td>
+ *   <td>native code can bypass many security checks of pure Java</td></tr>
  * <tr>
- *   <td><code>accessClassInPackage.{package name}</code></td>
- *   <td></td></tr>
+ *   <td><code>accessClassInPackage.</code><em>package name</em></td>
+ *   <td>access to a package via a ClassLoader</td>
+ *   <td>rogue code can access classes not normally available</td></tr>
  * <tr>
- *   <td><code>defineClassInPackage.{package name}</code></td>
- *   <td></td></tr>
+ *   <td><code>defineClassInPackage.</code><em>package name</em></td>
+ *   <td>define a class inside a given package</td>
+ *   <td>rogue code can install rogue classes, including in trusted packages
+ *       like java.security or java.lang</td></tr>
  * <tr>
  *   <td><code>accessDeclaredMembers</code></td>
- *   <td></td></tr>
+ *   <td>access declared class members via reflection</td>
+ *   <td>rogue code can discover information, invoke methods, or modify fields
+ *       that are not otherwise available</td></tr>
  * <tr>
  *   <td><code>queuePrintJob</code></td>
- *   <td></td></tr>
+ *   <td>initiate a print job</td>
+ *   <td>rogue code could make a hard copy of sensitive information, or
+ *       simply waste paper</td></tr>
  * </table>
  *
- * @since JDK 1.2
- * 
  * @author Brian Jones
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @see BasicPermission
+ * @see Permission
+ * @see SecurityManager
+ * @since 1.2
+ * @status updated to 1.4
  */
-public final class RuntimePermission extends java.security.BasicPermission
+public final class RuntimePermission extends BasicPermission
 {
   /**
+   * Compatible with JDK 1.2+.
+   */
+  private static final long serialVersionUID = 7399184964622342223L;
+
+  /**
+   * Create a new permission with the specified name.
    *
    * @param permissionName the name of the granted permission
-   * 
-   * @throws IllegalArgumentException thrown if the name contains an invalid 
-   * wildcard character
+   * @throws NullPointerException if name is null
+   * @throws IllegalArgumentException thrown if name is empty or invalid
    */
   public RuntimePermission(String permissionName)
     {
-      this(permissionName, null);
+      super(permissionName);
     }
 
   /**
+   * Create a new permission with the specified name. The actions argument
+   * is ignored, as runtime permissions have no actions.
    *
    * @param permissionName the name of the granted permission
-   * @param actions this should always be null
-   * 
-   * @throws IllegalArgumentException throw if the name contains an invalid
-   * wildcard character
+   * @param actions ignored
+   * @throws NullPointerException if name is null
+   * @throws IllegalArgumentException thrown if name is empty or invalid
    */
   public RuntimePermission(String permissionName, String actions)
   {
-      super(permissionName, actions);
+    super(permissionName);
   }
 }

libjava/java/lang/SecurityException.java

-/* SecurityException.java -- exception thrown to indicate a security 
-   violation.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* SecurityException.java -- thrown to indicate a security violation
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,38 +38,34 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
  * The security manager will throw this exception to indicate a security
- * violation.
- *
- * @since JDK 1.0
+ * violation.  This can occur any time an operation is attempted which is
+ * deemed unsafe by the current security policies.
  *
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @see SecurityManager
+ * @status updated to 1.4
  */
 public class SecurityException extends RuntimeException
 {
-  static final long serialVersionUID = 6878364983674394167L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 6878364983674394167L;
 
   /**
    * Create an exception without a message.
    */
   public SecurityException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public SecurityException(String s)
   {

libjava/java/lang/Short.java

-/* java.lang.Short
-   Copyright (C) 1998, 2001 Free Software Foundation, Inc.
+/* Short.java -- object wrapper for short
+   Copyright (C) 1998, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -47,19 +47,26 @@ package java.lang;
  *
  * @author Paul Fisher
  * @author John Keiser
- * @since JDK 1.0
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.1
+ * @status updated to 1.4
  */
 public final class Short extends Number implements Comparable
 {
-  static final long serialVersionUID = 7515723908773894738L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = 7515723908773894738L;
 
   /**
-   * The minimum value a <code>short</code> can represent is -32768.
+   * The minimum value a <code>short</code> can represent is -32768 (or
+   * -2<sup>15</sup).
    */
   public static final short MIN_VALUE = -32768;
 
   /**
-   * The minimum value a <code>short</code> can represent is 32767.
+   * The minimum value a <code>short</code> can represent is 32767 (or
+   * 2<sup>15</sup).
    */
   public static final short MAX_VALUE = 32767;
 
@@ -71,6 +78,8 @@ public final class Short extends Number implements Comparable
 
   /**
    * The immutable value of this Short.
+   *
+   * @serial the wrapped short
    */
   private final short value;
 
@@ -89,121 +98,94 @@ public final class Short extends Number implements Comparable
    * Create a <code>Short</code> object representing the value of the
    * argument after conversion to a <code>short</code>.
    *
-   * @param s the string to convert.
+   * @param s the string to convert
+   * @throws NumberFormatException if the String cannot be parsed
    */
-  public Short(String s) throws NumberFormatException
+  public Short(String s)
   {
     value = parseShort(s, 10);
   }
 
   /**
-   * Return a hashcode representing this Object.
-   *
-   * <code>Short</code>'s hash code is calculated by simply returning its
-   * value.
-   *
-   * @return this Object's hash code.
-   */
-  public int hashCode()
-  {
-    return value;
-  }
-
-  /**
-   * If the <code>Object</code> is not <code>null</code>, is an
-   * <code>instanceof</code> <code>Short</code>, and represents
-   * the same primitive <code>short</code> value return 
-   * <code>true</code>.  Otherwise <code>false</code> is returned.
-   */
-  public boolean equals(Object obj)
-  {
-    return obj instanceof Short && ((Short)obj).value == value;
-  }
-
-  /**
    * Converts the <code>short</code> to a <code>String</code> and assumes
    * a radix of 10.
-   * @param i the <code>short</code> to convert to <code>String</code>
-   * @return the <code>String</code> representation of the argument.
+   *
+   * @param s the <code>short</code> to convert to <code>String</code>
+   * @return the <code>String</code> representation of the argument
    */
-  public static String toString(short i)
+  public static String toString(short s)
   {
-    return Integer.toString((int) i);
+    return String.valueOf(s);
   }
 
   /**
-   * Converts the <code>Short</code> value to a <code>String</code> and
-   * assumes a radix of 10.
-   * @return the <code>String</code> representation of this <code>Short</code>.
+   * Converts the specified <code>String</code> into a <code>short</code>.
+   * This function assumes a radix of 10.
+   *
+   * @param s the <code>String</code> to convert
+   * @return the <code>short</code> value of <code>s</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
    */
-  public String toString()
+  public static short parseShort(String s)
   {
-    return Integer.toString ((int) value);
+    return parseShort(s, 10);
   }
 
   /**
-   * Creates a new <code>Short</code> object using the <code>String</code>,
-   * assuming a radix of 10.
-   * @param s the <code>String</code> to convert.
-   * @return the new <code>Short</code>.
-   * @see #Short(java.lang.String)
-   * @see #parseShort(java.lang.String)
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.
+   * Converts the specified <code>String</code> into a <code>short</code>
+   * using the specified radix (base). The string must not be <code>null</code>
+   * or empty. It may begin with an optional '-', which will negate the answer,
+   * provided that there are also valid digits. Each digit is parsed as if by
+   * <code>Character.digit(d, radix)</code>, and must be in the range
+   * <code>0</code> to <code>radix - 1</code>. Finally, the result must be
+   * within <code>MIN_VALUE</code> to <code>MAX_VALUE</code>, inclusive.
+   * Unlike Double.parseDouble, you may not have a leading '+'.
+   *
+   * @param s the <code>String</code> to convert
+   * @param radix the radix (base) to use in the conversion
+   * @return the <code>String</code> argument converted to </code>short</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
    */
-  public static Short valueOf(String s) throws NumberFormatException
+  public static short parseShort(String s, int radix)
   {
-    return new Short(parseShort(s));
+    int i = Integer.parseInt(s, radix, false);
+    if ((short) i != i)
+      throw new NumberFormatException();
+    return (short) i;
   }
 
   /**
    * Creates a new <code>Short</code> object using the <code>String</code>
    * and specified radix (base).
-   * @param s the <code>String</code> to convert.
-   * @param radix the radix (base) to convert with.
-   * @return the new <code>Short</code>.
-   * @see #parseShort(java.lang.String,int)
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.
-   */
-  public static Short valueOf(String s, int radix)
-    throws NumberFormatException
-  {
-    return new Short(parseShort(s, radix));
-  }
-
-  /**
-   * Converts the specified <code>String</code> into a <code>short</code>.
-   * This function assumes a radix of 10.
    *
    * @param s the <code>String</code> to convert
-   * @return the <code>short</code> value of the <code>String</code>
-   *         argument.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.
+   * @param radix the radix (base) to convert with
+   * @return the new <code>Short</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
+   * @see #parseShort(String, int)
    */
-  public static short parseShort(String s) throws NumberFormatException
+  public static Short valueOf(String s, int radix)
   {
-    return parseShort(s, 10);
+    return new Short(parseShort(s, radix));
   }
 
   /**
-   * Converts the specified <code>String</code> into a <code>short</code>
-   * using the specified radix (base).
+   * Creates a new <code>Short</code> object using the <code>String</code>,
+   * assuming a radix of 10.
    *
    * @param s the <code>String</code> to convert
-   * @param radix the radix (base) to use in the conversion
-   * @return the <code>String</code> argument converted to </code>short</code>.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.
+   * @return the new <code>Short</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
+   * @see #Short(String)
+   * @see #parseShort(String)
    */
-  public static short parseShort(String s, int radix) 
-    throws NumberFormatException
+  public static Short valueOf(String s)
   {
-    int i = Integer.parseInt(s, radix);
-    if (i < MIN_VALUE || i > MAX_VALUE)
-      throw new NumberFormatException();
-    return (short) i;
+    return new Short(parseShort(s, 10));
   }
 
   /**
@@ -211,90 +193,141 @@ public final class Short extends Number implements Comparable
    * The <code>String</code> may represent decimal, hexadecimal, or
    * octal numbers.
    *
-   * The <code>String</code> argument is interpreted based on the leading
-   * characters.  Depending on what the String begins with, the base will be
-   * interpreted differently:
-   *
-   * <table>
-   * <tr><th>Leading<br>Characters</th><th>Base</th></tr>
-   * <tr><td>#</td><td>16</td></tr>
-   * <tr><td>0x</td><td>16</td></tr>
-   * <tr><td>0X</td><td>16</td></tr>
-   * <tr><td>0</td><td>8</td></tr>
-   * <tr><td>Anything<br>Else</td><td>10</td></tr>
-   * </table>
+   * <p>The extended BNF grammar is as follows:<br>
+   * <pre>
+   * <em>DecodableString</em>:
+   *      ( [ <code>-</code> ] <em>DecimalNumber</em> )
+   *    | ( [ <code>-</code> ] ( <code>0x</code> | <code>0X</code>
+   *              | <code>#</code> ) <em>HexDigit</em> { <em>HexDigit</em> } )
+   *    | ( [ <code>-</code> ] <code>0</code> { <em>OctalDigit</em> } )
+   * <em>DecimalNumber</em>:
+   *        <em>DecimalDigit except '0'</em> { <em>DecimalDigit</em> }
+   * <em>DecimalDigit</em>:
+   *        <em>Character.digit(d, 10) has value 0 to 9</em>
+   * <em>OctalDigit</em>:
+   *        <em>Character.digit(d, 8) has value 0 to 7</em>
+   * <em>DecimalDigit</em>:
+   *        <em>Character.digit(d, 16) has value 0 to 15</em>
+   * </pre>
+   * Finally, the value must be in the range <code>MIN_VALUE</code> to
+   * <code>MAX_VALUE</code>, or an exception is thrown.
    *
-   * @param s the <code>String</code> to interpret.
-   * @return the value of the String as a <code>Short</code>.
-   * @exception NumberFormatException thrown if the <code>String</code> 
-   * cannot be parsed as a <code>short</code>.    
+   * @param s the <code>String</code> to interpret
+   * @return the value of the String as a <code>Short</code>
+   * @throws NumberFormatException if <code>s</code> cannot be parsed as a
+   *         <code>short</code>
+   * @throws NullPointerException if <code>s</code> is null
+   * @see Integer#decode(String)
    */
-  public static Short decode(String s) throws NumberFormatException
+  public static Short decode(String s)
   {
-    int i = (Integer.decode(s)).intValue();
-    if (i < MIN_VALUE || i > MAX_VALUE)
+    int i = Integer.parseInt(s, 10, true);
+    if ((short) i != i)
       throw new NumberFormatException();
     return new Short((short) i);
   }
 
-  /** Return the value of this <code>Short</code> as an <code>short</code>.
-   ** @return the value of this <code>Short</code> as an <code>short</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as a <code>byte</code>.
+   *
+   * @return the byte value
+   */
   public byte byteValue()
   {
     return (byte) value;
   }
 
-  /** Return the value of this <code>Short</code> as an <code>short</code>.
-   ** @return the value of this <code>Short</code> as an <code>short</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code>.
+   *
+   * @return the short value
+   */
   public short shortValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Short</code> as an <code>int</code>.
-   ** @return the value of this <code>Short</code> as an <code>int</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as an <code>int</code>.
+   *
+   * @return the int value
+   */
   public int intValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Short</code> as a <code>long</code>.
-   ** @return the value of this <code>Short</code> as a <code>long</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as a <code>long</code>.
+   *
+   * @return the long value
+   */
   public long longValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Short</code> as a <code>float</code>.
-   ** @return the value of this <code>Short</code> as a <code>float</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as a <code>float</code>.
+   *
+   * @return the float value
+   */
   public float floatValue()
   {
     return value;
   }
 
-  /** Return the value of this <code>Short</code> as a <code>double</code>.
-   ** @return the value of this <code>Short</code> as a <code>double</code>.
-   **/
+  /**
+   * Return the value of this <code>Short</code> as a <code>double</code>.
+   *
+   * @return the double value
+   */
   public double doubleValue()
   {
     return value;
   }
 
   /**
-   * Compare two Shorts numerically by comparing their
-   * <code>short</code> values.
-   * @return a positive value if this <code>Short</code> is greater
-   * in value than the argument <code>Short</code>; a negative value
-   * if this <code>Short</code> is smaller in value than the argument
-   * <code>Short</code>; and <code>0</code>, zero, if this
-   * <code>Short</code> is equal in value to the argument
-   * <code>Short</code>.  
+   * Converts the <code>Short</code> value to a <code>String</code> and
+   * assumes a radix of 10.
+   *
+   * @return the <code>String</code> representation of this <code>Short</code>
+   */
+  public String toString()
+  {
+    return String.valueOf(value);
+  }
+
+  /**
+   * Return a hashcode representing this Object. <code>Short</code>'s hash
+   * code is simply its value.
+   *
+   * @return this Object's hash code
+   */
+  public int hashCode()
+  {
+    return value;
+  }
+
+  /**
+   * Returns <code>true</code> if <code>obj</code> is an instance of
+   * <code>Short</code> and represents the same short value.
+   *
+   * @param obj the object to compare
+   * @return whether these Objects are semantically equal
+   */
+  public boolean equals(Object obj)
+  {
+    return obj instanceof Short && value == ((Short) obj).value;
+  }
+
+  /**
+   * Compare two Shorts numerically by comparing their <code>short</code>
+   * values. The result is positive if the first is greater, negative if the
+   * second is greater, and 0 if the two are equal.
    *
+   * @param s the Short to compare
+   * @return the comparison
    * @since 1.2
    */
   public int compareTo(Short s)
@@ -303,12 +336,14 @@ public final class Short extends Number implements Comparable
   }
 
   /**
-   * Behaves like <code>compareTo(java.lang.Short)</code> unless the Object
-   * is not a <code>Short</code>.  Then it throws a 
-   * <code>ClassCastException</code>.
-   * @exception ClassCastException if the argument is not a
-   * <code>Short</code>.
+   * Behaves like <code>compareTo(Short)</code> unless the Object
+   * is not a <code>Short</code>.
    *
+   * @param o the object to compare
+   * @return the comparison
+   * @throws ClassCastException if the argument is not a <code>Short</code>
+   * @see #compareTo(Short)
+   * @see Comparable
    * @since 1.2
    */
   public int compareTo(Object o)

libjava/java/lang/StackOverflowError.java

-/* StackOverflowError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* StackOverflowError.java -- thrown when the stack depth is exceeded
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,36 +38,32 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
- * A <code>StackOverflowError</code> is thrown when a stack overflow occurs.
- * This can occur because an application recurses too deeply.
- *
- * @since JDK 1.0
+ * A <code>StackOverflowError</code> is thrown when the execution stack
+ * overflow occurs. This often occurs when a method enters infinit recursion.
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class StackOverflowError extends VirtualMachineError
 {
-  static final long serialVersionUID = 8609175038441759607L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 8609175038441759607L;
 
   /**
    * Create an error without a message.
    */
   public StackOverflowError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public StackOverflowError(String s)
   {

libjava/java/lang/StringIndexOutOfBoundsException.java

-/* StringIndexOutOfBoundsException.java -- exception thrown to indicate 
-   an attempt to access an index which is out of bounds.
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* StringIndexOutOfBoundsException.java -- thrown to indicate attempt to
+   exceed string bounds
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,41 +39,34 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
- * Exceptions may be thrown by one part of a Java program and caught
- * by another in order to deal with exceptional conditions.  
- * This exception can be thrown to indicate an attempt to access an
- * index which is out of bounds.
- * Any negative integer less than or equal to -1 and positive 
- * integer greater than or equal to the size of the string is an index
+ * This exception can be thrown to indicate an attempt to access an index
+ * which is out of bounds of a String. Any negative integer, and a positive
+ * integer greater than or equal to the size of the string, is an index
  * which would be out of bounds.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @status updated to 1.4
  */
 public class StringIndexOutOfBoundsException extends IndexOutOfBoundsException
 {
-  static final long serialVersionUID = -6762910422159637258L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -6762910422159637258L;
 
   /**
    * Create an exception without a message.
    */
   public StringIndexOutOfBoundsException()
   {
-      super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
   public StringIndexOutOfBoundsException(String s)
   {
@@ -82,6 +75,8 @@ public class StringIndexOutOfBoundsException extends IndexOutOfBoundsException
 
   /**
    * Create an exception noting the illegal index.
+   *
+   * @param index the invalid index
    */
   public StringIndexOutOfBoundsException(int index)
   {

libjava/java/lang/ThreadDeath.java

-/* java.lang.ThreadDeath - Special exception registering Thread death.
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* ThreadDeath.java - special exception registering Thread death
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,23 +38,31 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Complete to version 1.1
+/**
+ * ThreadDeath is thrown in a thread when someone calls <code>stop()</code>
+ * on that thread. <b>Important:</b> Make sure you rethrow this exception
+ * if you catch it.  If you don't, the thread will not die.
+ *
+ * <p>This is an Error rather than an exception, so that normal code will
+ * not catch it. It is intended for asynchronous cleanup when using the
+ * deprecated Thread.stop() method.
+ *
+ * @author John Keiser
+ * @author Tom Tromey <tromey@cygnus.com>
+ * @see Thread#stop()
+ * @status updated to 1.4
+ */
+public class ThreadDeath extends Error
+{
+  /**
+   * Compatible with JDK 1.0+.
    */
+  private static final long serialVersionUID = -4417128565033088268L;
 
-/**
- ** ThreadDeath is thrown in a thread when someone calls <CODE>stop()</CODE> on that thread.
- **
- ** <B>Important:</B> Make sure you rethrow this exception if you catch it.  If you don't, the thread will not die.
- **
- ** @author John Keiser
- ** @author Tom Tromey <tromey@cygnus.com>
- ** @version 1.1.0, 5 Feb 1998, August 26 1998
- ** @since JDK1.0
- ** @see java.lang.Thread#stop()
- **/
-
-public class ThreadDeath extends Error {
+  /**
+   * Create an error without a message.
+   */
+  public ThreadDeath()
+  {
+  }
 }

libjava/java/lang/ThreadLocal.java

-/* java.lang.ThreadLocal
-   Copyright (C) 2000 Free Software Foundation, Inc.
+/* ThreadLocal -- a variable with a unique value per thread
+   Copyright (C) 2000, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -46,131 +46,117 @@ import java.util.WeakHashMap;
  * (through the <code>get()</code> and <code>set()</code> methods)
  * only affects the state of the object as seen by the currently
  * executing Thread.
- * <p>
- * The first time a ThreadLocal object is accessed on a particular
- * Thread (and no state is associated with that Thread yet)
- * the state for that Thread is set by executing the method
- * <code>initialValue()</code>.
- * <p>
- * An example how you can use this:
+ *
+ * <p>The first time a ThreadLocal object is accessed on a particular
+ * Thread, the state for that Thread's copy of the local variable is set by
+ * executing the method <code>initialValue()</code>.
+ *
+ * <p>An example how you can use this:
  * <pre>
- * class Connection {
- *     private static ThreadLocal owner = new ThreadLocal() {
- *        public Object initialValue() {
+ * class Connection
+ * {
+ *   private static ThreadLocal owner = new ThreadLocal()
+ *     {
+ *       public Object initialValue()
+ *       {
  *         return("nobody");
  *       }
  *     };
  * ...
  * }
- * </pre>
+ * </pre></br>
+ *
  * Now all instances of connection can see who the owner of the currently
  * executing Thread is by calling <code>owner.get()</code>. By default any
  * Thread would be associated with 'nobody'. But the Connection object could
  * offer a method that changes the owner associated with the Thread on
  * which the method was called by calling <code>owner.put("somebody")</code>.
  * (Such an owner changing method should then be guarded by security checks.)
- * <p>
- * When a Thread is garbage collected all references to values of
+ *
+ * <p>When a Thread is garbage collected all references to values of
  * the ThreadLocal objects associated with that Thread are removed.
  *
+ * @author Mark Wielaard <mark@klomp.org>
+ * @author Eric Blake <ebb9@email.byu.edu>
  * @since 1.2
- * @author Mark Wielaard (mark@klomp.org)
+ * @status updated to 1.4
  */
-public class ThreadLocal {
-	
+public class ThreadLocal
+{
   /**
-	 * Trivial container to wrap the stored values.
-	 * Needed to see if the value is null or not yet set.
-	 * If it is not yet set we must call intialValue() once.
-	 * Package local so InheritableThreadLocal can see it.
+   * Placeholder to distinguish between uninitialized and null set by the
+   * user. Do not expose this to the public. Package visible for use by
+   * InheritableThreadLocal
    */
-	final static class Value {
-		final Object value;
-		
-		Value(Object value) {
-			this.value = value;
-		}
-		
-		Object getValue() {
-			return value;
-		}
-	}
+  static final Object NULL = new Object();
 
   /**
-	 * Maps Threads to Values. Uses a WeakHashMap so if a Thread is garbage
-	 * collected the reference to the Value will disappear. Only the
-	 * <code>set(Thread, Value)</code> and <code>get(Thread)</code> methods
-	 * access it. Since this can happen from multiple Threads simultaniously
-	 * those methods are synchronized.
-	 */
-	private final Map valueMap = new WeakHashMap();
+   * The stored value. Package visible for use by InheritableThreadLocal. */
+  Object value;
 	
   /**
-	 * Creates a ThreadLocal object without associating any value to it
-	 * yet.
+   * Maps Threads to values. Uses a WeakHashMap so if a Thread is garbage
+   * collected the reference to the Value will disappear. A null value means
+   * uninitialized, while NULL means a user-specified null. Only the
+   * <code>set(Thread, Object)</code> and <code>get(Thread)</code> methods
+   * access it. Package visible for use by InheritableThreadLocal.
    */
-	public ThreadLocal() {
-	}
+  final Map valueMap = new WeakHashMap();
 	
   /**
-	 * Gets the value associated with the ThreadLocal object for the
-	 * currently executing Thread. If there is no value is associated
-	 * with this Thread yet then the valued returned by the
-	 * <code>initialValue()</code> method is assosiated with this Thread
-	 * and returned.
+   * Creates a ThreadLocal object without associating any value to it yet.
    */
-	public Object get() {
-		Thread currentThread = Thread.currentThread();
-		Value v = get(currentThread);
-		if (v == null) {
-			v = new Value(initialValue());
-			set(currentThread, v);
-		}
-		return v.getValue();
+  public ThreadLocal()
+  {
   }
 
   /**
-	 * Gets the Value of this ThreadLocal for a particular Thread.
-	 * It is synchronized so the <code>set(Thread, Value)</code> method cannot
-	 * simultaniously modify the </code>valueMap</code> from another thread.
-	 * Package local so InheritableThreadLocal can access it when a new child
-	 * Thread inherits values from its parent Thread.
+   * Called once per thread on the first invocation of get(), if set() was
+   * not already called. The default implementation returns <code>null</code>.
+   * Often, this method is overridden to create the appropriate initial object
+   * for the current thread's view of the ThreadLocal.
+   *
+   * @return the initial value of the variable in this thread
    */
-	synchronized final Value get(Thread thread) {
-		return (Value)valueMap.get(thread);
+  protected Object initialValue()
+  {
+    return null;
   }
 
   /**
-	 * Sets the value associated with the ThreadLocal object for the
-	 * currently executing Thread. This overrides any existing value
-	 * associated with the current Thread and does not call the
-	 * <code>initialValue()</code> method, even if this is the first
-	 * time this Thread accesses this ThreadLocal.
+   * Gets the value associated with the ThreadLocal object for the currently
+   * executing Thread. If this is the first time the current thread has called
+   * get(), and it has not already called set(), the value is obtained by
+   * <code>initialValue()</code>.
+   *
+   * @return the value of the variable in this thread
    */
-	public void set(Object value) {
+  public Object get()
+  {
     Thread currentThread = Thread.currentThread();
-		Value v = new Value(value);
-		set(currentThread, v);
+    // Note that we don't have to synchronize, as only this thread will
+    // ever modify the returned value.
+    Object value = valueMap.get(currentThread);
+    if (value == null)
+      {
+        value = initialValue();
+        valueMap.put(currentThread, value == null ? NULL : value);
       }
-	
-	/**
-	 * Sets the Value for this ThreadLocal for a particular Thread.
-	 * It is synchronized so the <code>get(Thread)</code> method cannot
-	 * simultaniously read the </code>valueMap</code> from another thread.
-	 * Package local so InheritableThreadLocal can access it when a new child
-	 * Thread inherits values from its parent Thread.
-	 */
-	synchronized final void set(Thread thread, Value value) {
-		valueMap.put(thread, value);
+    return value == NULL ? null : value;
   }
 
   /**
-	 * Called when <code>get()</code> is called and no state is associated
-	 * with the currently executing Thread yet.
-	 * <p>
-	 * The default implementation returns <code>null</code>.
+   * Sets the value associated with the ThreadLocal object for the currently
+   * executing Thread. This overrides any existing value associated with the
+   * current Thread and prevents <code>initialValue()</code> from being
+   * called if this is the first access to this ThreadLocal in this Thread.
+   *
+   * @param value the value to set this thread's view of the variable to
    */
-	protected Object initialValue() {
-		return null;
+  public void set(Object value)
+  {
+    // Note that we don't have to synchronize, as only this thread will
+    // ever modify the returned value.
+    valueMap.put(Thread.currentThread(), value == null ? NULL : value);
   }
 }

libjava/java/lang/UnknownError.java

-/* UnknownError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* UnknownError.java -- thrown when the VM cannot provide more information
+   about a catastrophic error
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,34 +39,31 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
  * An <code>UnknownError</code> is thrown when a serious but unknown
  * problem has occurred in the Java Virtual Machine.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
+ * @status updated to 1.4
  */
 public class UnknownError extends VirtualMachineError
 {
-  static final long serialVersionUID = 2524784860676771849L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 2524784860676771849L;
 
   /**
    * Create an error without a message.
    */
   public UnknownError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public UnknownError(String s)
   {

libjava/java/lang/UnsatisfiedLinkError.java

-/* UnsatisfiedLinkError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* UnsatisfiedLinkError.java -- thrown when a native method cannot be loaded
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,37 +38,34 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct. 
- */
-
 /**
  * A <code>UnsatisfiedLinkError</code> is thrown if an appropriate
  * native language definition of a method declared <code>native</code>
  * cannot be found by the Java Virtual Machine.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @see Runtime
+ * @status updated to 1.4
  */
 public class UnsatisfiedLinkError extends LinkageError
 {
-  static final long serialVersionUID = -4019343241616879428L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -4019343241616879428L;
 
   /**
    * Create an error without a message.
    */
   public UnsatisfiedLinkError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public UnsatisfiedLinkError(String s)
   {

libjava/java/lang/UnsupportedClassVersionError.java

-/* UnsupportedClassVersionError.java 
-   Copyright (C) 1998 Free Software Foundation, Inc.
+/* UnsupportedClassVersionError.java -- thrown when a class file version
+   exceeds the capability of the virtual machine
+   Copyright (C) 1998, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -43,24 +44,28 @@ package java.lang;
  * Java Virtual Machine determines it does not support the major and minor
  * version numbers in the class file it is attempting to read.
  *
- * @since JDK 1.2
- * 
  * @author Brian Jones
+ * @since 1.2
+ * @status updated to 1.4
  */
 public class UnsupportedClassVersionError extends ClassFormatError
 {
-  static final long serialVersionUID = -7123279212883497373L;
+  /**
+   * Compatible with JDK 1.2+.
+   */
+  private static final long serialVersionUID = -7123279212883497373L;
 
   /**
    * Create an error without a message.
    */
   public UnsupportedClassVersionError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public UnsupportedClassVersionError(String s)
   {

libjava/java/lang/UnsupportedOperationException.java

-/* UnsupportedOperationException.java -- Exception thrown when an
-   unsupported operation is attempted on an object
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* UnsupportedOperationException.java -- thrown when an operation is not
+   supported
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,37 +39,34 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
  * This exception is thrown by an object when an operation is
  * requested of it that it does not support.
  *
- * @since JDK 1.2
- *
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @since 1.2
+ * @status updated to 1.4
  */
 public class UnsupportedOperationException extends RuntimeException
 {
-  static final long serialVersionUID = -1242599979055084673L;
+  /**
+   * Compatible with JDK 1.2+.
+   */
+  private static final long serialVersionUID = -1242599979055084673L;
 
   /**
    * Create an exception without a message.
    */
   public UnsupportedOperationException()
   {
-    super();
   }
 
   /**
    * Create an exception with a message.
+   *
+   * @param s the message
    */
-  public UnsupportedOperationException( String s )
+  public UnsupportedOperationException(String s)
   {
     super(s);
   }

libjava/java/lang/VerifyError.java

-/* VerifyError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* VerifyError.java -- thrown when a class fails verification
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,36 +38,32 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
  * A <code>VerifyError</code> is thrown if there is a security problem or
- * internal inconsistency in a class file as deteced by the "verifier."
- *
- * @since JDK 1.0
+ * internal inconsistency in a class file as detected by the "verifier."
  *
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public class VerifyError extends LinkageError
 {
-  static final long serialVersionUID = 7001962396098498785L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 7001962396098498785L;
 
   /**
    * Create an error without a message.
    */
   public VerifyError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public VerifyError(String s)
   {

libjava/java/lang/VirtualMachineError.java

-/* VirtualMachineError.java 
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+/* VirtualMachineError.java -- thrown when the Virtual Machine has a problem
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,37 +38,33 @@ exception statement from your version. */
 
 package java.lang;
 
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * plus online API docs for JDK 1.2 beta from http://www.javasoft.com.
- * Status:  Believed complete and correct.
- */
-
 /**
  * A <code>VirtualMachineError</code> or its subclasses are thrown to
  * indicate there is something wrong with the Java Virtual Machine or that
  * it does not have the resources needed for it to continue execution.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Tom Tromey <tromey@cygnus.com>
- * @date October 1, 1998
+ * @status updated to 1.4
  */
 public abstract class VirtualMachineError extends Error
 {
-  static final long serialVersionUID = 4161983926571568670L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = 4161983926571568670L;
 
   /**
    * Create an error without a message.
    */
   public VirtualMachineError()
   {
-      super();
   }
 
   /**
    * Create an error with a message.
+   *
+   * @param s the message
    */
   public VirtualMachineError(String s)
   {

libjava/java/lang/reflect/InvocationTargetException.java

-/* InvocationTargetException.java - Wrapper exception for reflection
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* InvocationTargetException.java -- Wrapper exception for reflection
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,47 +38,52 @@ exception statement from your version. */
 
 package java.lang.reflect;
 
-import java.io.PrintStream;
-import java.io.PrintWriter;
-
-/* Written using "Java Class Libraries", 2nd edition, ISBN 0-201-31002-3
- * "The Java Language Specification", ISBN 0-201-63451-1
- * Status:  Believed complete and correct.
- */
-
 /**
  * InvocationTargetException is sort of a way to "wrap" whatever exception
- * comes up when a method or constructor is called via Reflection.
+ * comes up when a method or constructor is called via Reflection. As of
+ * JDK 1.4, it was retrofitted to match the exception chaining of all other
+ * exceptions, but <code>getTargetException()</code> still works.
  *
  * @author John Keiser
- * @version 1.1.0, 31 May 1998
  * @author Tom Tromey <tromey@cygnus.com>
- * @date December 12, 1998
- *
+ * @author Eric Blake <ebb9@email.byu.edu>
  * @see Method#invoke(Object,Object[])
  * @see Constructor#newInstance(Object[])
+ * @since 1.1
+ * @status updated to 1.4
  */
-
 public class InvocationTargetException extends Exception
 {
-  static final long serialVersionUID = 4085088731926701167L;
+  /**
+   * Compatible with JDK 1.1+.
+   */
+  private static final long serialVersionUID = 4085088731926701167L;
 
-  private Throwable target = null;
+  /**
+   * The chained exception. This field is only around for serial compatibility.
+   *
+   * @serial the chained exception
+   */
+  private final Throwable target;
 
+  /**
+   * Construct an exception with null as the cause. The cause is initialized
+   * to null.
+   */
   protected InvocationTargetException()
   {
-      super();
+    this(null, null);
   }
 
   /**
    * Create an <code>InvocationTargetException</code> using another
    * exception.
+   *
    * @param targetException the exception to wrap
    */
   public InvocationTargetException(Throwable targetException)
   {
-      super(targetException.toString());
-      target = targetException;
+    this(targetException, null);
   }
 
   /**
@@ -90,50 +95,29 @@ public class InvocationTargetException extends Exception
    */
   public InvocationTargetException(Throwable targetException, String err)
   {
-      super(err);
+    super(err, targetException);
     target = targetException;
   }
 
   /**
    * Get the wrapped (targeted) exception.
    *
-   * @return the targeted exception.
+   * @return the targeted exception
+   * @see #getCause()
    */
   public Throwable getTargetException()
   {
     return target;
   }
 
-  public void printStackTrace()
-    {
-      if (target == null)
-	super.printStackTrace();
-      else
-      {
-	System.err.print(this.getClass() + ": ");
-	target.printStackTrace();
-      }
-    }
-
-  public void printStackTrace(PrintStream ps)
-    {
-      if (target == null)
-	super.printStackTrace(ps);
-      else
-      {
-	ps.print(this.getClass() + ": ");
-	target.printStackTrace(ps);
-      }
-    }
-
-  public void printStackTrace(PrintWriter pw)
-    {
-      if (target == null)
-	super.printStackTrace(pw);
-      else
+  /**
+   * Returns the cause of this exception (which may be null).
+   *
+   * @return the cause
+   * @since 1.4
+   */
+  public Throwable getCause()
   {
-	pw.print(this.getClass() + ": ");
-	target.printStackTrace(pw);
-      }
+    return target;
   }
 }

libjava/java/net/BindException.java

 /* BindException.java -- An exception occurred while binding to a socket
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -38,49 +38,35 @@ exception statement from your version. */
 package java.net;
 
 /**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
-
-/**
  * This exception indicates that an error occurred while attempting to bind
  * socket to a particular port.
  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @author Aaron M. Renn <arenn@urbanophile.com>
  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
+ * @status updated to 1.4
  */
 public class BindException extends SocketException
 {
-
-/*
- * Constructors
+  /**
+   * Compatible with JDK 1.1+.
    */
+  private static final long serialVersionUID = -5945005768251722951L;
 
-/**
-  * Initializes a new instance of <code>BindException</code> without
-  * a descriptive error message.
+  /**
+   * Create a new instance without a descriptive error message.
    */
-public
-BindException()
-{
-  super();
-}
+  public BindException()
+  {
+  }
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>BindException</code> with
-  * a descriptive error message, such as the text from strerror(3).
+  /**
+   * Create a new instance with a descriptive error message, such as the
+   * text from strerror(3).
    *
-  * @param message A message describing the error that occurred.
+   * @param message a message describing the error that occurred
    */
-public
-BindException(String message)
-{
+  public BindException(String message)
+  {
     super(message);
-}
-
+  }
 } // class BindException
-

libjava/java/net/ConnectException.java

 /* ConnectException.java -- An exception occurred while connecting to a host
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,50 +39,37 @@ exception statement from your version. */
 package java.net;
 
 /**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
-
-/**
  * This exception indicates that an error occurred while attempting to
  * connect to a remote host.  Often this indicates that the remote host
  * refused the connection (ie, is not listening on the target socket).
  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @author Aaron M. Renn <arenn@urbanophile.com>
  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
+ * @since 1.1
+ * @status updated to 1.4
  */
 public class ConnectException extends SocketException
 {
-
-/*
- * Constructors
+  /**
+   * Compatible with JDK 1.1+.
    */
+  private static final long serialVersionUID = 3831404271622369215L;
 
-/**
-  * Initializes a new instance of <code>ConnectException</code> without
-  * a descriptive error message.
+  /**
+   * Create a new instance without a descriptive error message.
    */
-public
-ConnectException()
-{
-  super();
-}
+  public ConnectException()
+  {
+  }
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>ConnectException</code> with
-  * a descriptive error message, such as the text from strerror(3).
+  /**
+   * Create a new instance with a descriptive error message, such as the
+   * text from strerror(3).
    *
-  * @param message A message describing the error that occurred.
+   * @param message a message describing the error that occurred
    */
-public
-ConnectException(String message)
-{
+  public ConnectException(String message)
+  {
     super(message);
-}
-
+  }
 } // class ConnectException
-

libjava/java/net/MalformedURLException.java

 /* MalformedURLException.java -- A URL was not in a valid format
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -37,50 +37,37 @@ exception statement from your version. */
 
 package java.net;
 
-/**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
  * This exception indicates that a URL passed to an object was not in a
  * valid format.
  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @author Aaron M. Renn <arenn@urbanophile.com>
  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
+ * @status updated to 1.4
  */
-public class MalformedURLException extends java.io.IOException
+public class MalformedURLException extends IOException
 {
-
-/*
- * Constructors
+  /**
+   * Compatible with JDK 1.0+.
    */
+  private static final long serialVersionUID = -182787522200415866L;
 
-/**
-  * Initializes a new instance of <code>MalformedURLException</code> without
-  * a descriptive error message.
+  /**
+   * Create a new instance without a descriptive error message.
    */
-public
-MalformedURLException()
-{
-  super();
-}
+  public MalformedURLException()
+  {
+  }
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>MalformedURLException</code> without
-  * a descriptive error message.
+  /**
+   * Create a new instance with a descriptive error message.
    *
-  * @param message A message describing the error that occurred.
+   * @param message a message describing the error that occurred
    */
-public
-MalformedURLException(String message)
-{
+  public MalformedURLException(String message)
+  {
     super(message);
-}
-
+  }
 } // class MalformedURLException
-

libjava/java/net/NoRouteToHostException.java

 /* NoRouteToHostException.java -- Cannot connect to a host
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -39,49 +39,36 @@ exception statement from your version. */
 package java.net;
 
 /**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
-
-/**
   * This exception indicates that there is no TCP/IP route to the requested
   * host.  This is often due to a misconfigured routing table.
   *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
+  * @author Aaron M. Renn <arenn@urbanophile.com>
   * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
+  * @since 1.1
+  * @status updated to 1.4
   */
 public class NoRouteToHostException extends SocketException
 {
-
-/*
- * Constructors
+  /**
+   * Compatible with JDK 1.1+.
    */
+  private static final long serialVersionUID = -1897550894873493790L;
 
-/**
-  * Initializes an instance of <code>NoRouteToHostException</code>
-  * without a descriptive error message.
+  /**
+   * Create an instance without a descriptive error message.
    */
-public
-NoRouteToHostException()
-{
-  super();
-}
+  public NoRouteToHostException()
+  {
+  }
 
-/*************************************************************************/
-
-/**
-  * Initializes an instance of <code>NoRouteToHostException</code>
-  * witha descriptive error message, such as the text from strerror(3).
+  /**
+   * Create an instance with a descriptive error message, such as the text
+   * from strerror(3).
    *
-  * @param message A message describing the error that occurred.
+   * @param message a message describing the error that occurred
    */
-public
-NoRouteToHostException(String message)
-{
+  public NoRouteToHostException(String message)
+  {
     super(message);
-}
-
+  }
 } // class NoRouteToHostException
-

libjava/java/net/ProtocolException.java

-/* ProtocolException.java -- A low level protocol error occurred
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* ProtocolException.java -- a low level protocol error occurred
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -37,51 +37,38 @@ exception statement from your version. */
 
 package java.net;
 
-/**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
  * This exception indicates that some sort of low level protocol
  * exception occurred.  Look in the descriptive message (if any) for
-  * details on what went wrong
+ * details on what went wrong.
  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @author Aaron M. Renn <arenn@urbanophile.com>
  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
+ * @status updated to 1.4
  */
-public class ProtocolException extends java.io.IOException
+public class ProtocolException extends IOException
 {
-
-/*
- * Constructors
+  /**
+   * Compatible with JDK 1.0+.
    */
+  private static final long serialVersionUID = -6098449442062388080L;
 
-/**
-  * Initializes a new instance of <code>ProtocolException</code>
-  * without a descriptive error message.
+  /**
+   * Create a new instance without a descriptive error message.
    */
-public
-ProtocolException()
-{
-  super();
-}
+  public ProtocolException()
+  {
+  }
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>ProtocolException</code>
-  * with a descriptive error message.
+  /**
+   * Create a new instance with a descriptive error message.
    *
-  * @param message A message describing the error that occurred.
+   * @param message a message describing the error that occurred
    */
-public
-ProtocolException(String message)
-{
+  public ProtocolException(String message)
+  {
     super(message);
-}
-
+  }
 } // class ProtocolException
-

libjava/java/net/SocketException.java

 /* SocketException.java -- An exception occurred while performing a socket op
-   Copyright (C) 1998, 1999, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -37,49 +37,38 @@ exception statement from your version. */
 
 package java.net;
 
-/* Written using on-line Java Platform 1.2 API Specification.
- * Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
  * This exception indicates that a generic error occurred related to an
  * operation on a socket.  Check the descriptive message (if any) for
  * details on the nature of this error
  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @author Aaron M. Renn <arenn@urbanophile.com>
  * @author Per Bothner
-  * @date January 6, 1999.
+ * @status updated to 1.4
  */
-public class SocketException extends java.io.IOException
+public class SocketException extends IOException
 {
-
-/*
- * Constructors
+  /**
+   * Compatible with JDK 1.0+.
    */
+  private static final long serialVersionUID = -5935874303556886934L;
 
-/**
-  * Initializes a new instance of <code>SocketException</code> without
-  * a descriptive error message.
+  /**
+   * Create a new instance without a descriptive error message.
    */
-public
-SocketException()
-{
-  super();
-}
-
-/*************************************************************************/
+  public SocketException()
+  {
+  }
 
-/**
-  * Initializes a new instance of <code>SocketException</code> without
-  * a descriptive error message.
+  /**
+   * Create a new instance with a descriptive error message.
    *
-  * @param message A message describing the error that occurred.
+   * @param message a message describing the error that occurred
    */
-public
-SocketException(String message)
-{
+  public SocketException(String message)
+  {
     super(message);
-}
-
+  }
 } // class SocketException
-

libjava/java/net/UnknownHostException.java

-/* UnknownHostException.java -- The hostname is not unknown
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+/* UnknownHostException.java -- The hostname is unknown
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -37,10 +37,7 @@ exception statement from your version. */
 
 package java.net;
 
-/*
- * Written using on-line Java Platform 1.2 API Specification.
- * Status:  Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
  * This exception indicates that an attempt was made to reference a hostname
@@ -48,41 +45,32 @@ package java.net;
  * DNS problem has occurred, but most often means that the host was not
  * correctly specified.
  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @author Aaron M. Renn <arenn@urbanophile.com>
  * @author Per Bothner
-  * @date January 6, 1999.
+ * @status updated to 1.4
  */
-public class UnknownHostException extends java.io.IOException
+public class UnknownHostException extends IOException
 {
-
-/*
- * Constructors
+  /**
+   * Compatible with JDK 1.0+.
    */
+  private static final long serialVersionUID = -4639126076052875403L;
 
-/**
-  * Initializes a new instance of <code>UnknownHostException</code>
-  * without a descriptive error message.
+  /**
+   * Create a new instance without a descriptive error message.
    */
-public
-UnknownHostException()
-{
-  super();
-}
-
-/*************************************************************************/
+  public UnknownHostException()
+  {
+  }
 
-/**
-  * Initializes a new instance of <code>UnknownHostException</code>
-  * with a descriptive error message, such as the name of the host
-  * that could not be resolved.
+  /**
+   * Create a new instance with a descriptive error message, such as the
+   * name of the host that could not be resolved.
    *
-  * @param message A message describing the error that occurrred.
+   * @param message a message describing the error that occurred
    */
-public
-UnknownHostException(String message)
-{
+  public UnknownHostException(String message)
+  {
     super(message);
-}
-
+  }
 } // class UnknownHostException
-

libjava/java/net/UnknownServiceException.java

 /* UnknownServiceException.java -- A service error occurred
-   Copyright (C) 1998, 1999, 2000, 2001 Free Software Foundation, Inc.
+   Copyright (C) 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -37,11 +37,7 @@ exception statement from your version. */
 
 package java.net;
 
-/**
- * Written using on-line Java Platform 1.2 API Specification, as well
- * as "The Java Class Libraries", 2nd edition (Addison-Wesley, 1998).
- * Status:  Believed complete and correct.
- */
+import java.io.IOException;
 
 /**
  * Contrary to what you might think, this does not indicate that the
@@ -49,40 +45,31 @@ package java.net;
  * the MIME type returned from a URL could not be determined or that an
  * attempt was made to write to a read-only URL.
  *
-  * @author Aaron M. Renn (arenn@urbanophile.com)
+ * @author Aaron M. Renn <arenn@urbanophile.com>
  * @author Warren Levy <warrenl@cygnus.com>
-  * @date March 5, 1999.
+ * @status updated to 1.4
  */
-public class UnknownServiceException extends java.io.IOException
+public class UnknownServiceException extends IOException
 {
-
-/*
- * Constructors
+  /**
+   * Compatible with JDK 1.0+.
    */
+  private static final long serialVersionUID = -4169033248853639508L;
 
-/**
-  * Initializes a new instance of <code>UnknownServiceException</code>
-  * without a descriptive error message.
+  /**
+   * Create a new instance without a descriptive error message.
    */
-public
-UnknownServiceException()
-{
-  super();
-}
+  public UnknownServiceException()
+  {
+  }
 
-/*************************************************************************/
-
-/**
-  * Initializes a new instance of <code>UnknownServiceException</code>
-  * without a descriptive error message.
+  /**
+   * Create a new instance with a descriptive error message.
    *
-  * @param message A message describing the error that occurred.
+   * @param message a message describing the error that occurred
    */
-public
-UnknownServiceException(String message)
-{
+  public UnknownServiceException(String message)
+  {
     super(message);
-}
-
+  }
 } // class UnknownServiceException
-