Merge JDK 1.4 exception chaining support from classpath.

	* java/lang/Throwable.java: Merge 1.4 support from classpath.
	(stackTraceBytes): Rename from stackTrace.
	* java/lang/Exception.java: Merge from classpath.
	* java/lang/StackTraceElement: New file from classpath.
	* gcj/javaprims.h: Rebuild CNI namespace declarations.
	* Makefile.am: Add StackTraceElement.
	* Makefile.in: Rebuilt.

From-SVN: r53836

7 files changed, 731 insertions, 67 deletions

diff --git a/libjava/ChangeLog b/libjava/ChangeLog
index 507790f..16c71d7 100644
--- a/libjava/ChangeLog
+++ b/libjava/ChangeLog
@@ -1,3 +1,14 @@
+2002-05-24  Bryce McKinlay  <bryce@waitaki.otago.ac.nz>
+
+	Merge JDK 1.4 exception chaining support from classpath.
+	* java/lang/Throwable.java: Merge 1.4 support from classpath.
+	(stackTraceBytes): Rename from stackTrace.
+	* java/lang/Exception.java: Merge from classpath.
+	* java/lang/StackTraceElement: New file from classpath.
+	* gcj/javaprims.h: Rebuild CNI namespace declarations.
+	* Makefile.am: Add StackTraceElement.
+	* Makefile.in: Rebuilt.
+
 2002-05-23  Bryce McKinlay  <bryce@waitaki.otago.ac.nz>
 
 	* Makefile.am (all-recursive): Depend on $all_java_class_files so that
diff --git a/libjava/Makefile.am b/libjava/Makefile.am
index 773eb20..a96a3cc 100644
--- a/libjava/Makefile.am
+++ b/libjava/Makefile.am
@@ -1084,6 +1084,7 @@ java/lang/SecurityException.java \
 java/lang/SecurityManager.java \
 java/lang/Short.java \
 java/lang/StackOverflowError.java \
+java/lang/StackTraceElement.java \
 java/lang/StrictMath.java \
 java/lang/String.java \
 java/lang/StringBuffer.java \
@@ -1418,7 +1419,7 @@ gnu/java/security/provider/SHA1PRNG.java \
 gnu/java/text/BaseBreakIterator.java \
 gnu/java/text/CharacterBreakIterator.java \
 gnu/java/text/LineBreakIterator.java \
-gnu/java/text/SentenceBreakIterator.java	\
+gnu/java/text/SentenceBreakIterator.java \
 gnu/java/text/WordBreakIterator.java \
 gnu/java/util/DoubleEnumeration.java \
 java/lang/ref/PhantomReference.java \
diff --git a/libjava/Makefile.in b/libjava/Makefile.in
index 9bd41c7..8fff46e 100644
--- a/libjava/Makefile.in
+++ b/libjava/Makefile.in
@@ -851,6 +851,7 @@ java/lang/SecurityException.java \
 java/lang/SecurityManager.java \
 java/lang/Short.java \
 java/lang/StackOverflowError.java \
+java/lang/StackTraceElement.java \
 java/lang/StrictMath.java \
 java/lang/String.java \
 java/lang/StringBuffer.java \
@@ -1180,7 +1181,7 @@ gnu/java/security/provider/SHA1PRNG.java \
 gnu/java/text/BaseBreakIterator.java \
 gnu/java/text/CharacterBreakIterator.java \
 gnu/java/text/LineBreakIterator.java \
-gnu/java/text/SentenceBreakIterator.java	\
+gnu/java/text/SentenceBreakIterator.java \
 gnu/java/text/WordBreakIterator.java \
 gnu/java/util/DoubleEnumeration.java \
 java/lang/ref/PhantomReference.java \
@@ -2267,7 +2268,8 @@ DEP_FILES =  .deps/$(srcdir)/$(CONVERT_DIR)/gen-from-JIS.P \
 .deps/java/lang/Runtime.P .deps/java/lang/RuntimeException.P \
 .deps/java/lang/RuntimePermission.P .deps/java/lang/SecurityException.P \
 .deps/java/lang/SecurityManager.P .deps/java/lang/Short.P \
-.deps/java/lang/StackOverflowError.P .deps/java/lang/StrictMath.P \
+.deps/java/lang/StackOverflowError.P \
+.deps/java/lang/StackTraceElement.P .deps/java/lang/StrictMath.P \
 .deps/java/lang/String.P .deps/java/lang/StringBuffer.P \
 .deps/java/lang/StringIndexOutOfBoundsException.P \
 .deps/java/lang/System.P .deps/java/lang/Thread.P \
diff --git a/libjava/gcj/javaprims.h b/libjava/gcj/javaprims.h
index 4337f56..1f1a33b 100644
--- a/libjava/gcj/javaprims.h
+++ b/libjava/gcj/javaprims.h
@@ -193,6 +193,7 @@ extern "Java"
       class SecurityManager;
       class Short;
       class StackOverflowError;
+      class StackTraceElement;
       class StrictMath;
       class String;
       class String$CaseInsensitiveComparator;
@@ -241,32 +242,43 @@ extern "Java"
     {
       class AbstractCollection;
       class AbstractList;
-      class AbstractList$AbstractListItr;
       class AbstractMap;
       class AbstractSequentialList;
       class AbstractSet;
       class ArrayList;
       class Arrays;
+      class Arrays$ArrayList;
       class Arrays$ListImpl;
       class BasicMapEntry;
       class BitSet;
       class Calendar;
       class Collection;
       class Collections;
+      class Collections$CopiesList;
+      class Collections$EmptyList;
+      class Collections$EmptyMap;
+      class Collections$EmptySet;
       class Collections$ReverseComparator;
+      class Collections$SingletonList;
+      class Collections$SingletonMap;
+      class Collections$SingletonSet;
       class Collections$SynchronizedCollection;
       class Collections$SynchronizedIterator;
       class Collections$SynchronizedList;
       class Collections$SynchronizedListIterator;
       class Collections$SynchronizedMap;
+      class Collections$SynchronizedMapEntry;
+      class Collections$SynchronizedRandomAccessList;
       class Collections$SynchronizedSet;
       class Collections$SynchronizedSortedMap;
       class Collections$SynchronizedSortedSet;
       class Collections$UnmodifiableCollection;
+      class Collections$UnmodifiableEntrySet;
       class Collections$UnmodifiableIterator;
       class Collections$UnmodifiableList;
       class Collections$UnmodifiableListIterator;
       class Collections$UnmodifiableMap;
+      class Collections$UnmodifiableRandomAccessList;
       class Collections$UnmodifiableSet;
       class Collections$UnmodifiableSortedMap;
       class Collections$UnmodifiableSortedSet;
@@ -288,10 +300,12 @@ extern "Java"
       class Hashtable$HashEntry;
       class Hashtable$HashIterator;
       class IdentityHashMap;
+      class IdentityHashMap$IdentityEntry;
       class IdentityHashMap$IdentityIterator;
       class Iterator;
       class LinkedHashMap;
       class LinkedHashMap$LinkedHashEntry;
+      class LinkedHashSet;
       class LinkedList;
       class LinkedList$Entry;
       class LinkedList$LinkedListItr;
@@ -311,7 +325,9 @@ extern "Java"
       class PropertyResourceBundle;
       class Random;
       class RandomAccess;
+      class RandomAccessSubList;
       class ResourceBundle;
+      class ResourceBundle$Security;
       class Set;
       class SimpleTimeZone;
       class SortedMap;
@@ -329,12 +345,11 @@ extern "Java"
       class TreeMap$Node;
       class TreeMap$SubMap;
       class TreeMap$TreeIterator;
-      class TreeMap$VerifyResult;
       class TreeSet;
       class Vector;
       class WeakHashMap;
-      class WeakHashMap$Entry;
       class WeakHashMap$WeakBucket;
+      class WeakHashMap$WeakEntry;
       class WeakHashMap$WeakEntrySet;
       namespace jar
       {
@@ -372,7 +387,7 @@ extern "Java"
         class ZipOutputStream;
       };
     };
-  };
+  };  
 };
   
 typedef struct java::lang::Object* jobject;
diff --git a/libjava/java/lang/Exception.java b/libjava/java/lang/Exception.java
index a1c79ac..edf5de2 100644
--- a/libjava/java/lang/Exception.java
+++ b/libjava/java/lang/Exception.java
@@ -1,6 +1,6 @@
 /* Exception.java -- generic exception thrown to indicate an exceptional
    condition has occurred.
-   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.
 
@@ -8,7 +8,7 @@ GNU Classpath is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2, or (at your option)
 any later version.
- 
+
 GNU Classpath is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
@@ -39,40 +39,66 @@ 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 the cause of the exception, such as
+ * The root class of all exceptions worth catching in a program.  This
+ * includes the special category of <code>RuntimeException</code>, which
+ * does not need to be declared in a throws clause.  Exceptions can be used
+ * to represent almost any exceptional behavior, such as programming errors,
  * mouse movements, keyboard clicking, etc.
  *
- * @since JDK 1.0
- * 
  * @author Brian Jones
  * @author Warren Levy <warrenl@cygnus.com>
- * @date September 18, 1998.
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @status updated to 1.4
  */
 public class Exception extends Throwable
 {
-  static final long serialVersionUID = -3387516993124229948L;
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -3387516993124229948L;
 
   /**
-   * Create an exception without a message.
+   * Create an exception without a message. The cause remains uninitialized.
+   *
+   * @see #initCause(Throwable)
    */
   public Exception()
-    {
-      super();
-    }
+  {
+  }
 
   /**
-   * Create an exception with a message.
+   * Create an exception with a message. The cause remains uninitialized.
+   *
+   * @param s the message
+   * @see #initCause(Throwable)
    */
   public Exception(String s)
-    {
-      super(s);
-    }
+  {
+    super(s);
+  }
+
+  /**
+   * Create an exception with a message and a cause.
+   *
+   * @param s the message string
+   * @param cause the cause of this error
+   * @since 1.4
+   */
+  public Exception(String s, Throwable cause)
+  {
+    super(s, cause);
+  }
+
+  /**
+   * Create an exception with a given cause, and a message of
+   * <code>cause == null ? null : cause.toString()</code>.
+   *
+   * @param cause the cause of this exception
+   * @since 1.4
+   */
+  public Exception(Throwable cause)
+  {
+    super(cause);
+  }
 }
diff --git a/libjava/java/lang/StackTraceElement.java b/libjava/java/lang/StackTraceElement.java
new file mode 100644
index 0000000..9c60ab1
--- /dev/null
+++ b/libjava/java/lang/StackTraceElement.java
@@ -0,0 +1,259 @@
+/* StackTraceElement.java -- One function call or call stack element
+   Copyright (C) 2001, 2002 Free Software Foundation, Inc.
+
+This file is part of GNU Classpath.
+
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
+
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
+
+
+package java.lang;
+
+import java.io.Serializable;
+
+/**
+ * One function call or stack trace element. Gives information about
+ * the execution point such as the source file name, the line number,
+ * the fully qualified class name, the method name and whether this method
+ * is native, if this information is known.
+ *
+ * @author Mark Wielaard <mark@klomp.org>
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.4
+ * @status updated to 1.4
+ */
+public class StackTraceElement implements Serializable
+{
+  /**
+   * Compatible with JDK 1.4+.
+   */
+  private static final long serialVersionUID = 6992337162326171013L;
+
+  /**
+   * The name of the file, null if unknown.
+   *
+   * @serial the source code filename, if known
+   */
+  private final String fileName;
+
+  /**
+   * The line number in the file, negative if unknown.
+   *
+   * @serial the source code line number, if known
+   */
+  private final int lineNumber;
+
+  /**
+   * The fully qualified class name, null if unknown.
+   *
+   * @serial the enclosing class, if known
+   */
+  private final String className;
+
+  /**
+   * The method name in the class, null if unknown.
+   *
+   * @serial the enclosing method, if known
+   */
+  private final String methodName;
+
+  /** Whether the method is native. */
+  private final transient boolean isNative;
+
+  /**
+   * A package local constructor for the StackTraceElement class, to be
+   * called by the Virtual Machine as part of Throwable.fillInStackTrace.
+   * There are no public constructors defined for this class. Creation
+   * of new elements is implementation specific.
+   *
+   * @param fileName the name of the file, null if unknown
+   * @param lineNumber the line in the file, negative if unknown
+   * @param className the fully qualified name of the class, null if unknown
+   * @param methodName the name of the method, null if unknown
+   * @param isNative true if native, false otherwise
+   */
+  StackTraceElement(String fileName, int lineNumber, String className,
+                    String methodName, boolean isNative)
+  {
+    this.fileName = fileName;
+    this.lineNumber = lineNumber;
+    this.className = className;
+    this.methodName = methodName;
+    this.isNative = isNative;
+  }
+
+  /**
+   * Returns the name of the file, or null if unknown. This is usually
+   * obtained from the <code>SourceFile</code> attribute of the class file
+   * format, if present.
+   *
+   * @return the file name
+   */
+  public String getFileName()
+  {
+    return fileName;
+  }
+
+  /**
+   * Returns the line number in the file, or a negative number if unknown.
+   * This is usually obtained from the <code>LineNumberTable</code> attribute
+   * of the method in the class file format, if present.
+   *
+   * @return the line number
+   */
+  public int getLineNumber()
+  {
+    return lineNumber;
+  }
+
+  /**
+   * Returns the fully qualified class name, or null if unknown.
+   *
+   * @return the class name
+   */
+  public String getClassName()
+  {
+    return className;
+  }
+
+  /**
+   * Returns the method name in the class, or null if unknown. If the
+   * execution point is in a constructor, the name is
+   * <code>&lt;init&gt;</code>; if the execution point is in the class
+   * initializer, the name is <code>&lt;clinit&gt;</code>.
+   *
+   * @return the method name
+   */
+  public String getMethodName()
+  {
+    return methodName;
+  }
+
+  /**
+   * Returns true if the method is native, or false if it is not or unknown.
+   *
+   * @return whether the method is native
+   */
+  public boolean isNativeMethod()
+  {
+    return isNative;
+  }
+
+  /**
+   * Returns a string representation of this stack trace element. The
+   * returned String is implementation specific. This implementation
+   * returns the following String: "[class][.][method]([file][:line])".
+   * If the fully qualified class name or the method is unknown it is
+   * omitted including the point seperator. If the source file name is
+   * unknown it is replaced by "Unknown Source" if the method is not native
+   * or by "Native Method" if the method is native. If the line number
+   * is unknown it and the colon are omitted.
+   *
+   * @return a string representation of this execution point
+   */
+  public String toString()
+  {
+    StringBuffer sb = new StringBuffer();
+    if (className != null)
+      {
+        sb.append(className);
+        if (methodName != null)
+          sb.append('.');
+      }
+    if (methodName != null)
+      sb.append(methodName);
+    sb.append('(');
+    if (fileName != null)
+      sb.append(fileName);
+    else
+      sb.append(isNative ? "Native Method" : "Unknown Source");
+    if (lineNumber >= 0)
+      sb.append(':').append(lineNumber);
+    sb.append(')');
+    return sb.toString();
+  }
+
+  /**
+   * Returns true if the given object is also a StackTraceElement and all
+   * attributes, except the native flag, are equal (either the same attribute
+   * between the two elments are null, or both satisfy Object.equals).
+   *
+   * @param o the object to compare
+   * @return true if the two are equal
+   */
+  public boolean equals(Object o)
+  {
+    if (! (o instanceof StackTraceElement))
+      return false;
+    StackTraceElement e = (StackTraceElement) o;
+    return equals(fileName, e.fileName)
+      && lineNumber == e.lineNumber
+      && equals(className, e.className)
+      && equals(methodName, e.methodName);
+  }
+
+  /**
+   * Returns the hashCode of this StackTraceElement. This implementation
+   * computes the hashcode by xor-ing the hashcode of all attributes except
+   * the native flag.
+   *
+   * @return the hashcode
+   */
+  public int hashCode()
+  {
+    return hashCode(fileName) ^ lineNumber ^ hashCode(className)
+      ^ hashCode(methodName);
+  }
+
+  /**
+   * Compare two objects according to Collection semantics.
+   *
+   * @param o1 the first object
+   * @param o2 the second object
+   * @return o1 == null ? o2 == null : o1.equals(o2)
+   */
+  private static final boolean equals(Object o1, Object o2)
+  {
+    return o1 == null ? o2 == null : o1.equals(o2);
+  }
+
+  /**
+   * Hash an object according to Collection semantics.
+   *
+   * @param o the object to hash
+   * @return o1 == null ? 0 : o1.hashCode()
+   */
+  private static final int hashCode(Object o)
+  {
+    return o == null ? 0 : o.hashCode();
+  }
+}
diff --git a/libjava/java/lang/Throwable.java b/libjava/java/lang/Throwable.java
index 5c330fe..d5488b8 100644
--- a/libjava/java/lang/Throwable.java
+++ b/libjava/java/lang/Throwable.java
@@ -1,21 +1,50 @@
-// Throwable.java - Superclass for all exceptions.
+/* java.lang.Throwable -- Reference implementation of root class for
+   all Exceptions and Errors
+   Copyright (C) 1998, 1999, 2002 Free Software Foundation, Inc.
 
-/* Copyright (C) 1998, 1999  Free Software Foundation
+This file is part of GNU Classpath.
 
-   This file is part of libgcj.
+GNU Classpath is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2, or (at your option)
+any later version.
 
-This software is copyrighted work licensed under the terms of the
-Libgcj License.  Please consult the file "LIBGCJ_LICENSE" for
-details.  */
+GNU Classpath is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with GNU Classpath; see the file COPYING.  If not, write to the
+Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
+02111-1307 USA.
+
+Linking this library statically or dynamically with other modules is
+making a combined work based on this library.  Thus, the terms and
+conditions of the GNU General Public License cover the whole
+combination.
+
+As a special exception, the copyright holders of this library give you
+permission to link this library with independent modules to produce an
+executable, regardless of the license terms of these independent
+modules, and to copy and distribute the resulting executable under
+terms of your choice, provided that you also meet, for each linked
+independent module, the terms and conditions of the license of that
+module.  An independent module is a module which is not derived from
+or based on this library.  If you modify this library, you may extend
+this exception to your version of the library, but you are not
+obligated to do so.  If you do not wish to do so, delete this
+exception statement from your version. */
 
 package java.lang;
-import java.io.PrintStream;
-import java.io.PrintWriter;
+
 import java.io.Serializable;
-import java.io.OutputStreamWriter;
-import java.io.OutputStream;
-import java.io.FilterOutputStream;
+import java.io.PrintWriter;
+import java.io.PrintStream;
+import java.io.ObjectOutputStream;
+import java.io.ObjectInputStream;
 import java.io.IOException;
+import java.io.OutputStream;
 
 /**
  * @author Tom Tromey <tromey@cygnus.com>
@@ -98,38 +127,341 @@ class CPlusPlusDemangler extends OutputStream
   }    
 }
 
+/**
+ * Throwable is the superclass of all exceptions that can be raised.
+ *
+ * <p>There are two special cases: {@link Error} and {@link RuntimeException}:
+ * these two classes (and their subclasses) are considered unchecked
+ * exceptions, and are either frequent enough or catastrophic enough that you
+ * do not need to declare them in <code>throws</code> clauses.  Everything
+ * else is a checked exception, and is ususally a subclass of
+ * {@link Exception}; these exceptions have to be handled or declared.
+ *
+ * <p>Instances of this class are usually created with knowledge of the
+ * execution context, so that you can get a stack trace of the problem spot
+ * in the code.  Also, since JDK 1.4, Throwables participate in "exception
+ * chaining."  This means that one exception can be caused by another, and
+ * preserve the information of the original.
+ *
+ * <p>One reason this is useful is to wrap exceptions to conform to an
+ * interface.  For example, it would be bad design to require all levels
+ * of a program interface to be aware of the low-level exceptions thrown
+ * at one level of abstraction. Another example is wrapping a checked
+ * exception in an unchecked one, to communicate that failure occured
+ * while still obeying the method throws clause of a superclass.
+ *
+ * <p>A cause is assigned in one of two ways; but can only be assigned once
+ * in the lifetime of the Throwable.  There are new constructors added to
+ * several classes in the exception hierarchy that directly initialize the
+ * cause, or you can use the <code>initCause</code> method. This second
+ * method is especially useful if the superclass has not been retrofitted
+ * with new constructors:<br>
+ * <pre>
+ * try
+ *   {
+ *     lowLevelOp();
+ *   }
+ * catch (LowLevelException lle)
+ *   {
+ *     throw (HighLevelException) new HighLevelException().initCause(lle);
+ *   }
+ * </pre>
+ * Notice the cast in the above example; without it, your method would need
+ * a throws clase that declared Throwable, defeating the purpose of chainig
+ * your exceptions.
+ *
+ * <p>By convention, exception classes have two constructors: one with no
+ * arguments, and one that takes a String for a detail message.  Further,
+ * classes which are likely to be used in an exception chain also provide
+ * a constructor that takes a Throwable, with or without a detail message
+ * string.
+ *
+ * <p>Another 1.4 feature is the StackTrace, a means of reflection that
+ * allows the program to inspect the context of the exception, and which is
+ * serialized, so that remote procedure calls can correctly pass exceptions.
+ *
+ * @author Brian Jones
+ * @author John Keiser
+ * @author Mark Wielaard
+ * @author Tom Tromey
+ * @author Eric Blake <ebb9@email.byu.edu>
+ * @since 1.0
+ * @status still missing 1.4 functionality
+ */
 public class Throwable implements Serializable
 {
-  public native Throwable fillInStackTrace ();
+  /**
+   * Compatible with JDK 1.0+.
+   */
+  private static final long serialVersionUID = -3042686055658047285L;
+
+  /**
+   * The detail message.
+   *
+   * @serial specific details about the exception, may be null
+   */
+  private String detailMessage;
+
+  /**
+   * The cause of the throwable, including null for an unknown or non-chained
+   * cause. This may only be set once; so the field is set to
+   * <code>this</code> until initialized.
+   *
+   * @serial the cause, or null if unknown, or this if not yet set
+   * @since 1.4
+   */
+  private Throwable cause = this;
+
+  /**
+   * The stack trace, in a serialized form.
+   *
+   * @serial the elements of the stack trace; this is non-null, and has
+   *         no null entries
+   * @since 1.4
+   */
+  // XXX Don't initialize this, once fillInStackTrace() does it.
+  private StackTraceElement[] stackTrace = {};
+
+  /**
+   * Instantiate this Throwable with an empty message. The cause remains
+   * uninitialized.  {@link #fillInStackTrace()} will be called to set
+   * up the stack trace.
+   */
+  public Throwable()
+  {
+    this((String) null);
+  }
 
-  public String getLocalizedMessage ()
+  /**
+   * Instantiate this Throwable with the given message. The cause remains
+   * uninitialized.  {@link #fillInStackTrace()} will be called to set
+   * up the stack trace.
+   *
+   * @param message the message to associate with the Throwable
+   */
+  public Throwable(String message)
   {
-    return getMessage ();
+    fillInStackTrace();
+    detailMessage = message;  
   }
 
-  public String getMessage ()
+  /**
+   * Instantiate this Throwable with the given message and cause. Note that
+   * the message is unrelated to the message of the cause.
+   * {@link #fillInStackTrace()} will be called to set up the stack trace.
+   *
+   * @param message the message to associate with the Throwable
+   * @param cause the cause, may be null
+   * @since 1.4
+   */
+  public Throwable(String message, Throwable cause)
+  {
+    this(message);
+    initCause(cause);
+  }
+
+  /**
+   * Instantiate this Throwable with the given cause. The message is then
+   * built as <code>cause == null ? null : cause.toString()</code>.
+   * {@link #fillInStackTrace()} will be called to set up the stack trace.
+   *
+   * @param cause the cause, may be null
+   * @since 1.4
+   */
+  public Throwable(Throwable cause)
+  {
+    this(cause == null ? null : cause.toString(), cause);
+  }
+
+  /**
+   * Get the message associated with this Throwable.
+   *
+   * @return the error message associated with this Throwable, may be null
+   */
+  public String getMessage()
   {
     return detailMessage;
   }
 
-  public void printStackTrace ()
+  /**
+   * Get a localized version of this Throwable's error message.
+   * This method must be overridden in a subclass of Throwable
+   * to actually produce locale-specific methods.  The Throwable
+   * implementation just returns getMessage().
+   *
+   * @return a localized version of this error message
+   * @see #getMessage()
+   * @since 1.1
+   */
+  public String getLocalizedMessage()
+  {
+    return getMessage();
+  }
+
+  /**
+   * Returns the cause of this exception, or null if the cause is not known
+   * or non-existant. This cause is initialized by the new constructors,
+   * or by calling initCause.
+   *
+   * @return the cause of this Throwable
+   * @since 1.4
+   */
+  public Throwable getCause()
   {
-    printStackTrace (System.err);
+    return cause == this ? null : cause;
   }
 
-  public void printStackTrace (PrintStream ps)
+  /**
+   * Initialize the cause of this Throwable.  This may only be called once
+   * during the object lifetime, including implicitly by chaining
+   * constructors.
+   *
+   * @param cause the cause of this Throwable, may be null
+   * @return this
+   * @throws IllegalArgumentException if cause is this (a Throwable can't be
+   *         its own cause!)
+   * @throws IllegalStateException if the cause has already been set
+   * @since 1.4
+   */
+  public Throwable initCause(Throwable cause)
   {
-    PrintWriter writer = new PrintWriter (ps);
-    printStackTrace (writer);
+    if (cause == this)
+      throw new IllegalArgumentException();
+    if (this.cause != this)
+      throw new IllegalStateException();
+    this.cause = cause;
+    return this;
   }
 
+  /**
+   * Get a human-readable representation of this Throwable. The detail message
+   * is retrieved by getLocalizedMessage().  Then, with a null detail
+   * message, this string is simply the object's class name; otherwise
+   * the string is <code>getClass().getName() + ": " + message</code>.
+   *
+   * @return a human-readable String represting this Throwable
+   */
+  public String toString()
+  {
+    String msg = getLocalizedMessage();
+    return getClass().getName() + (msg == null ? "" : ": " + msg);
+  }
+
+  /**
+   * Print a stack trace to the standard error stream. This stream is the
+   * current contents of <code>System.err</code>. The first line of output
+   * is the result of {@link #toString()}, and the remaining lines represent
+   * the data created by {@link #fillInStackTrace()}. While the format is
+   * unspecified, this implementation uses the suggested format, demonstrated
+   * by this example:<br>
+   * <pre>
+   * public class Junk
+   * {
+   *   public static void main(String args[])
+   *   {
+   *     try
+   *       {
+   *         a();
+   *       }
+   *     catch(HighLevelException e)
+   *       {
+   *         e.printStackTrace();
+   *       }
+   *   }
+   *   static void a() throws HighLevelException
+   *   {
+   *     try
+   *       {
+   *         b();
+   *       }
+   *     catch(MidLevelException e)
+   *       {
+   *         throw new HighLevelException(e);
+   *       }
+   *   }
+   *   static void b() throws MidLevelException
+   *   {
+   *     c();
+   *   }
+   *   static void c() throws MidLevelException
+   *   {
+   *     try
+   *       {
+   *         d();
+   *       }
+   *     catch(LowLevelException e)
+   *       {
+   *         throw new MidLevelException(e);
+   *       }
+   *   }
+   *   static void d() throws LowLevelException
+   *   {
+   *     e();
+   *   }
+   *   static void e() throws LowLevelException
+   *   {
+   *     throw new LowLevelException();
+   *   }
+   * }
+   * class HighLevelException extends Exception
+   * {
+   *   HighLevelException(Throwable cause) { super(cause); }
+   * }
+   * class MidLevelException extends Exception
+   * {
+   *   MidLevelException(Throwable cause)  { super(cause); }
+   * }
+   * class LowLevelException extends Exception
+   * {
+   * }
+   * </pre>
+   * <p>
+   * <pre>
+   *  HighLevelException: MidLevelException: LowLevelException
+   *          at Junk.a(Junk.java:13)
+   *          at Junk.main(Junk.java:4)
+   *  Caused by: MidLevelException: LowLevelException
+   *          at Junk.c(Junk.java:23)
+   *          at Junk.b(Junk.java:17)
+   *          at Junk.a(Junk.java:11)
+   *          ... 1 more
+   *  Caused by: LowLevelException
+   *          at Junk.e(Junk.java:30)
+   *          at Junk.d(Junk.java:27)
+   *          at Junk.c(Junk.java:21)
+   *          ... 3 more
+   * </pre>
+   */
+  public void printStackTrace()
+  {
+    printStackTrace(System.err);
+  }
+
+  /**
+   * Print a stack trace to the specified PrintStream. See
+   * {@link #printStackTrace()} for the sample format.
+   *
+   * @param s the PrintStream to write the trace to
+   */
+  public void printStackTrace(PrintStream s)
+  {
+    printStackTrace(new PrintWriter(s));
+  }
+
+  /**
+   * Print a stack trace to the specified PrintWriter. See
+   * {@link #printStackTrace()} for the sample format.
+   *
+   * @param w the PrintWriter to write the trace to
+   * @since 1.1
+   */
   public void printStackTrace (PrintWriter wr)
   {
     try
       {
 	CPlusPlusDemangler cPlusPlusFilter = new CPlusPlusDemangler (wr);
 	PrintWriter writer = new PrintWriter (cPlusPlusFilter);
-	printRawStackTrace (writer);	
+	printRawStackTrace (writer);
 	writer.close ();
 	if (cPlusPlusFilter.written == 0) // The demangler has failed...
 	  printRawStackTrace (wr);
@@ -140,32 +472,50 @@ public class Throwable implements Serializable
       }
   }
 
-  public Throwable ()
-  {
-    detailMessage = null;
-    fillInStackTrace ();
-  }
+  /**
+   * Fill in the stack trace with the current execution stack.
+   *
+   * @return this same throwable
+   * @see #printStackTrace()
+   */
+  public native Throwable fillInStackTrace();
 
-  public Throwable (String message)
+  /**
+   * Provides access to the information printed in {@link #printStackTrace()}.
+   * The array is non-null, with no null entries, although the virtual
+   * machine is allowed to skip stack frames.  If the array is not 0-length,
+   * then slot 0 holds the information on the stack frame where the Throwable
+   * was created (or at least where <code>fillInStackTrace()</code> was
+   * called).
+   *
+   * @return an array of stack trace information, as available from the VM
+   * @since 1.4
+   */
+  public StackTraceElement[] getStackTrace()
   {
-    detailMessage = message;
-    fillInStackTrace ();
+    return stackTrace;
   }
 
-  public String toString ()
+  /**
+   * Change the stack trace manually. This method is designed for remote
+   * procedure calls, which intend to alter the stack trace before or after
+   * serialization according to the context of the remote call.
+   *
+   * @param stackTrace the new trace to use
+   * @throws NullPointerException if stackTrace is null or has null elements
+   * @since 1.4
+   */
+  public void setStackTrace(StackTraceElement[] stackTrace)
   {
-    return ((detailMessage == null)
-	    ? getClass().getName()
-	    : getClass().getName() + ": " + getMessage ());
+    for (int i = stackTrace.length; --i >= 0; )
+      if (stackTrace[i] == null)
+        throw new NullPointerException();
+    this.stackTrace = stackTrace;
   }
 
   private native final void printRawStackTrace (PrintWriter wr);
   
-  // Name of this field comes from serialization spec.
-  private String detailMessage;
-
   // Setting this flag to false prevents fillInStackTrace() from running.
   static boolean trace_enabled = true;
-  private transient byte stackTrace[];
-  private static final long serialVersionUID = -3042686055658047285L;
+  private transient byte stackTraceBytes[];
 }