       1 /*
       2  * Copyright (c) 1994, 2020, Oracle and/or its affiliates. All rights reserved.
       3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
       4  *
       5  * This code is free software; you can redistribute it and/or modify it
       6  * under the terms of the GNU General Public License version 2 only, as
       7  * published by the Free Software Foundation.  Oracle designates this
       8  * particular file as subject to the "Classpath" exception as provided
       9  * by Oracle in the LICENSE file that accompanied this code.
      10  *
      11  * This code is distributed in the hope that it will be useful, but WITHOUT
      12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
      13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
      14  * version 2 for more details (a copy is included in the LICENSE file that
      15  * accompanied this code).
      16  *
      17  * You should have received a copy of the GNU General Public License version
      18  * 2 along with this work; if not, write to the Free Software Foundation,
      19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
      20  *
      21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
      22  * or visit www.oracle.com if you need additional information or have any
      23  * questions.
      24  */
      25
      26 package java.lang;
      27
      28 import java.io.*;
      29 import java.util.*;
      30
      31 /**
      32  * The {@code Throwable} class is the superclass of all errors and
      33  * exceptions in the Java language. Only objects that are instances of this
      34  * class (or one of its subclasses) are thrown by the Java Virtual Machine or
      35  * can be thrown by the Java {@code throw} statement. Similarly, only
      36  * this class or one of its subclasses can be the argument type in a
      37  * {@code catch} clause.
      38  *
      39  * For the purposes of compile-time checking of exceptions, {@code
      40  * Throwable} and any subclass of {@code Throwable} that is not also a
      41  * subclass of either {@link RuntimeException} or {@link Error} are
      42  * regarded as checked exceptions.
      43  *
      44  * <p>Instances of two subclasses, {@link java.lang.Error} and
      45  * {@link java.lang.Exception}, are conventionally used to indicate
      46  * that exceptional situations have occurred. Typically, these instances
      47  * are freshly created in the context of the exceptional situation so
      48  * as to include relevant information (such as stack trace data).
      49  *
      50  * <p>A throwable contains a snapshot of the execution stack of its
      51  * thread at the time it was created. It can also contain a message
      52  * string that gives more information about the error. Over time, a
      53  * throwable can {@linkplain Throwable#addSuppressed suppress} other
      54  * throwables from being propagated.  Finally, the throwable can also
      55  * contain a <i>cause</i>: another throwable that caused this
      56  * throwable to be constructed.  The recording of this causal information
      57  * is referred to as the <i>chained exception</i> facility, as the
      58  * cause can, itself, have a cause, and so on, leading to a "chain" of
      59  * exceptions, each caused by another.
      60  *
      61  * <p>One reason that a throwable may have a cause is that the class that
      62  * throws it is built atop a lower layered abstraction, and an operation on
      63  * the upper layer fails due to a failure in the lower layer.  It would be bad
      64  * design to let the throwable thrown by the lower layer propagate outward, as
      65  * it is generally unrelated to the abstraction provided by the upper layer.
      66  * Further, doing so would tie the API of the upper layer to the details of
      67  * its implementation, assuming the lower layer's exception was a checked
      68  * exception.  Throwing a "wrapped exception" (i.e., an exception containing a
      69  * cause) allows the upper layer to communicate the details of the failure to
      70  * its caller without incurring either of these shortcomings.  It preserves
      71  * the flexibility to change the implementation of the upper layer without
      72  * changing its API (in particular, the set of exceptions thrown by its
      73  * methods).
      74  *
      75  * <p>A second reason that a throwable may have a cause is that the method
      76  * that throws it must conform to a general-purpose interface that does not
      77  * permit the method to throw the cause directly.  For example, suppose
      78  * a persistent collection conforms to the {@link java.util.Collection
      79  * Collection} interface, and that its persistence is implemented atop
      80  * {@code java.io}.  Suppose the internals of the {@code add} method
      81  * can throw an {@link java.io.IOException IOException}.  The implementation
      82  * can communicate the details of the {@code IOException} to its caller
      83  * while conforming to the {@code Collection} interface by wrapping the
      84  * {@code IOException} in an appropriate unchecked exception.  (The
      85  * specification for the persistent collection should indicate that it is
      86  * capable of throwing such exceptions.)
      87  *
      88  * <p>A cause can be associated with a throwable in two ways: via a
      89  * constructor that takes the cause as an argument, or via the
      90  * {@link #initCause(Throwable)} method.  New throwable classes that
      91  * wish to allow causes to be associated with them should provide constructors
      92  * that take a cause and delegate (perhaps indirectly) to one of the
      93  * {@code Throwable} constructors that takes a cause.
      94  *
      95  * Because the {@code initCause} method is public, it allows a cause to be
      96  * associated with any throwable, even a "legacy throwable" whose
      97  * implementation predates the addition of the exception chaining mechanism to
      98  * {@code Throwable}.
      99  *
     100  * <p>By convention, class {@code Throwable} and its subclasses have two
     101  * constructors, one that takes no arguments and one that takes a
     102  * {@code String} argument that can be used to produce a detail message.
     103  * Further, those subclasses that might likely have a cause associated with
     104  * them should have two more constructors, one that takes a
     105  * {@code Throwable} (the cause), and one that takes a
     106  * {@code String} (the detail message) and a {@code Throwable} (the
     107  * cause).
     108  *
     109  * @author  unascribed
     110  * @author  Josh Bloch (Added exception chaining and programmatic access to
     111  *          stack trace in 1.4.)
     112  * @jls 11.2 Compile-Time Checking of Exceptions
     113  * @since 1.0
     114  */
     115 public class Throwable implements Serializable {
     116     /** use serialVersionUID from JDK 1.0.2 for interoperability */
     117     @java.io.Serial
     118     private static final long serialVersionUID = -3042686055658047285L;
     119
     120     /**
     121      * The JVM saves some indication of the stack backtrace in this slot.
     122      */
     123     private transient Object backtrace;
     124
     125     /**
     126      * Specific details about the Throwable.  For example, for
     127      * {@code FileNotFoundException}, this contains the name of
     128      * the file that could not be found.
     129      *
     130      * @serial
     131      */
     132     private String detailMessage;
     133
     134
     135     /**
     136      * Holder class to defer initializing sentinel objects only used
     137      * for serialization.
     138      */
     139     private static class SentinelHolder {
     140         /**
     141          * {@linkplain #setStackTrace(StackTraceElement[]) Setting the
     142          * stack trace} to a one-element array containing this sentinel
     143          * value indicates future attempts to set the stack trace will be
     144          * ignored.  The sentinel is equal to the result of calling:<br>
     145          * {@code new StackTraceElement("", "", null, Integer.MIN_VALUE)}
     146          */
     147         public static final StackTraceElement STACK_TRACE_ELEMENT_SENTINEL =
     148             new StackTraceElement("", "", null, Integer.MIN_VALUE);
     149
     150         /**
     151          * Sentinel value used in the serial form to indicate an immutable
     152          * stack trace.
     153          */
     154         public static final StackTraceElement[] STACK_TRACE_SENTINEL =
     155             new StackTraceElement[] {STACK_TRACE_ELEMENT_SENTINEL};
     156     }
     157
     158     /**
     159      * A shared value for an empty stack.
     160      */
     161     private static final StackTraceElement[] UNASSIGNED_STACK = new StackTraceElement[0];
     162
     163     /*
     164      * To allow Throwable objects to be made immutable and safely
     165      * reused by the JVM, such as OutOfMemoryErrors, fields of
     166      * Throwable that are writable in response to user actions, cause,
     167      * stackTrace, and suppressedExceptions obey the following
     168      * protocol:
     169      *
     170      * 1) The fields are initialized to a non-null sentinel value
     171      * which indicates the value has logically not been set.
     172      *
     173      * 2) Writing a null to the field indicates further writes
     174      * are forbidden
     175      *
     176      * 3) The sentinel value may be replaced with another non-null
     177      * value.
     178      *
     179      * For example, implementations of the HotSpot JVM have
     180      * preallocated OutOfMemoryError objects to provide for better
     181      * diagnosability of that situation.  These objects are created
     182      * without calling the constructor for that class and the fields
     183      * in question are initialized to null.  To support this
     184      * capability, any new fields added to Throwable that require
     185      * being initialized to a non-null value require a coordinated JVM
     186      * change.
     187      */
     188
     189     /**
     190      * The throwable that caused this throwable to get thrown, or null if this
     191      * throwable was not caused by another throwable, or if the causative
     192      * throwable is unknown.  If this field is equal to this throwable itself,
     193      * it indicates that the cause of this throwable has not yet been
     194      * initialized.
     195      *
     196      * @serial
     197      * @since 1.4
     198      */
     199     private Throwable cause = this;
     200
     201     /**
     202      * The stack trace, as returned by {@link #getStackTrace()}.
     203      *
     204      * The field is initialized to a zero-length array.  A {@code
     205      * null} value of this field indicates subsequent calls to {@link
     206      * #setStackTrace(StackTraceElement[])} and {@link
     207      * #fillInStackTrace()} will be no-ops.
     208      *
     209      * @serial
     210      * @since 1.4
     211      */
     212     private StackTraceElement[] stackTrace = UNASSIGNED_STACK;
     213
     214     /**
     215      * The JVM code sets the depth of the backtrace for later retrieval
     216      */
     217     private transient int depth;
     218
     219     // Setting this static field introduces an acceptable
     220     // initialization dependency on a few java.util classes.
     221     private static final List<Throwable> SUPPRESSED_SENTINEL = Collections.emptyList();
     222
     223     /**
     224      * The list of suppressed exceptions, as returned by {@link
     225      * #getSuppressed()}.  The list is initialized to a zero-element
     226      * unmodifiable sentinel list.  When a serialized Throwable is
     227      * read in, if the {@code suppressedExceptions} field points to a
     228      * zero-element list, the field is reset to the sentinel value.
     229      *
     230      * @serial
     231      * @since 1.7
     232      */
     233     @SuppressWarnings("serial") // Not statically typed as Serializable
     234     private List<Throwable> suppressedExceptions = SUPPRESSED_SENTINEL;
     235
     236     /** Message for trying to suppress a null exception. */
     237     private static final String NULL_CAUSE_MESSAGE = "Cannot suppress a null exception.";
     238
     239     /** Message for trying to suppress oneself. */
     240     private static final String SELF_SUPPRESSION_MESSAGE = "Self-suppression not permitted";
     241
     242     /** Caption  for labeling causative exception stack traces */
     243     private static final String CAUSE_CAPTION = "Caused by: ";
     244
     245     /** Caption for labeling suppressed exception stack traces */
     246     private static final String SUPPRESSED_CAPTION = "Suppressed: ";
     247
     248     /**
     249      * Constructs a new throwable with {@code null} as its detail message.
     250      * The cause is not initialized, and may subsequently be initialized by a
     251      * call to {@link #initCause}.
     252      *
     253      * <p>The {@link #fillInStackTrace()} method is called to initialize
     254      * the stack trace data in the newly created throwable.
     255      */
     256     public Throwable() {
     257         fillInStackTrace();
     258     }
     259
     260     /**
     261      * Constructs a new throwable with the specified detail message.  The
     262      * cause is not initialized, and may subsequently be initialized by
     263      * a call to {@link #initCause}.
     264      *
     265      * <p>The {@link #fillInStackTrace()} method is called to initialize
     266      * the stack trace data in the newly created throwable.
     267      *
     268      * @param   message   the detail message. The detail message is saved for
     269      *          later retrieval by the {@link #getMessage()} method.
     270      */
     271     public Throwable(String message) {
     272         fillInStackTrace();
     273         detailMessage = message;
     274     }
     275
     276     /**
     277      * Constructs a new throwable with the specified detail message and
     278      * cause.  <p>Note that the detail message associated with
     279      * {@code cause} is <i>not</i> automatically incorporated in
     280      * this throwable's detail message.
     281      *
     282      * <p>The {@link #fillInStackTrace()} method is called to initialize
     283      * the stack trace data in the newly created throwable.
     284      *
     285      * @param  message the detail message (which is saved for later retrieval
     286      *         by the {@link #getMessage()} method).
     287      * @param  cause the cause (which is saved for later retrieval by the
     288      *         {@link #getCause()} method).  (A {@code null} value is
     289      *         permitted, and indicates that the cause is nonexistent or
     290      *         unknown.)
     291      * @since  1.4
     292      */
     293     public Throwable(String message, Throwable cause) {
     294         fillInStackTrace();
     295         detailMessage = message;
     296         this.cause = cause;
     297     }
     298
     299     /**
     300      * Constructs a new throwable with the specified cause and a detail
     301      * message of {@code (cause==null ? null : cause.toString())} (which
     302      * typically contains the class and detail message of {@code cause}).
     303      * This constructor is useful for throwables that are little more than
     304      * wrappers for other throwables (for example, {@link
     305      * java.security.PrivilegedActionException}).
     306      *
     307      * <p>The {@link #fillInStackTrace()} method is called to initialize
     308      * the stack trace data in the newly created throwable.
     309      *
     310      * @param  cause the cause (which is saved for later retrieval by the
     311      *         {@link #getCause()} method).  (A {@code null} value is
     312      *         permitted, and indicates that the cause is nonexistent or
     313      *         unknown.)
     314      * @since  1.4
     315      */
     316     public Throwable(Throwable cause) {
     317         fillInStackTrace();
     318         detailMessage = (cause==null ? null : cause.toString());
     319         this.cause = cause;
     320     }
     321
     322     /**
     323      * Constructs a new throwable with the specified detail message,
     324      * cause, {@linkplain #addSuppressed suppression} enabled or
     325      * disabled, and writable stack trace enabled or disabled.  If
     326      * suppression is disabled, {@link #getSuppressed} for this object
     327      * will return a zero-length array and calls to {@link
     328      * #addSuppressed} that would otherwise append an exception to the
     329      * suppressed list will have no effect.  If the writable stack
     330      * trace is false, this constructor will not call {@link
     331      * #fillInStackTrace()}, a {@code null} will be written to the
     332      * {@code stackTrace} field, and subsequent calls to {@code
     333      * fillInStackTrace} and {@link
     334      * #setStackTrace(StackTraceElement[])} will not set the stack
     335      * trace.  If the writable stack trace is false, {@link
     336      * #getStackTrace} will return a zero length array.
     337      *
     338      * <p>Note that the other constructors of {@code Throwable} treat
     339      * suppression as being enabled and the stack trace as being
     340      * writable.  Subclasses of {@code Throwable} should document any
     341      * conditions under which suppression is disabled and document
     342      * conditions under which the stack trace is not writable.
     343      * Disabling of suppression should only occur in exceptional
     344      * circumstances where special requirements exist, such as a
     345      * virtual machine reusing exception objects under low-memory
     346      * situations.  Circumstances where a given exception object is
     347      * repeatedly caught and rethrown, such as to implement control
     348      * flow between two sub-systems, is another situation where
     349      * immutable throwable objects would be appropriate.
     350      *
     351      * @param  message the detail message.
     352      * @param cause the cause.  (A {@code null} value is permitted,
     353      * and indicates that the cause is nonexistent or unknown.)
     354      * @param enableSuppression whether or not suppression is enabled or disabled
     355      * @param writableStackTrace whether or not the stack trace should be
     356      *                           writable
     357      *
     358      * @see OutOfMemoryError
     359      * @see NullPointerException
     360      * @see ArithmeticException
     361      * @since 1.7
     362      */
     363     protected Throwable(String message, Throwable cause,
     364                         boolean enableSuppression,
     365                         boolean writableStackTrace) {
     366         if (writableStackTrace) {
     367             fillInStackTrace();
     368         } else {
     369             stackTrace = null;
     370         }
     371         detailMessage = message;
     372         this.cause = cause;
     373         if (!enableSuppression)
     374             suppressedExceptions = null;
     375     }
     376
     377     /**
     378      * Returns the detail message string of this throwable.
     379      *
     380      * @return  the detail message string of this {@code Throwable} instance
     381      *          (which may be {@code null}).
     382      */
     383     public String getMessage() {
     384         return detailMessage;
     385     }
     386
     387     /**
     388      * Creates a localized description of this throwable.
     389      * Subclasses may override this method in order to produce a
     390      * locale-specific message.  For subclasses that do not override this
     391      * method, the default implementation returns the same result as
     392      * {@code getMessage()}.
     393      *
     394      * @return  The localized description of this throwable.
     395      * @since   1.1
     396      */
     397     public String getLocalizedMessage() {
     398         return getMessage();
     399     }
     400
     401     /**
     402      * Returns the cause of this throwable or {@code null} if the
     403      * cause is nonexistent or unknown.  (The cause is the throwable that
     404      * caused this throwable to get thrown.)
     405      *
     406      * <p>This implementation returns the cause that was supplied via one of
     407      * the constructors requiring a {@code Throwable}, or that was set after
     408      * creation with the {@link #initCause(Throwable)} method.  While it is
     409      * typically unnecessary to override this method, a subclass can override
     410      * it to return a cause set by some other means.  This is appropriate for
     411      * a "legacy chained throwable" that predates the addition of chained
     412      * exceptions to {@code Throwable}.  Note that it is <i>not</i>
     413      * necessary to override any of the {@code PrintStackTrace} methods,
     414      * all of which invoke the {@code getCause} method to determine the
     415      * cause of a throwable.
     416      *
     417      * @return  the cause of this throwable or {@code null} if the
     418      *          cause is nonexistent or unknown.
     419      * @since 1.4
     420      */
     421     public synchronized Throwable getCause() {
     422         return (cause==this ? null : cause);
     423     }
     424
     425     /**
     426      * Initializes the <i>cause</i> of this throwable to the specified value.
     427      * (The cause is the throwable that caused this throwable to get thrown.)
     428      *
     429      * <p>This method can be called at most once.  It is generally called from
     430      * within the constructor, or immediately after creating the
     431      * throwable.  If this throwable was created
     432      * with {@link #Throwable(Throwable)} or
     433      * {@link #Throwable(String,Throwable)}, this method cannot be called
     434      * even once.
     435      *
     436      * <p>An example of using this method on a legacy throwable type
     437      * without other support for setting the cause is:
     438      *
     439      * <pre>
     440      * try {
     441      *     lowLevelOp();
     442      * } catch (LowLevelException le) {
     443      *     throw (HighLevelException)
     444      *           new HighLevelException().initCause(le); // Legacy constructor
     445      * }
     446      * </pre>
     447      *
     448      * @param  cause the cause (which is saved for later retrieval by the
     449      *         {@link #getCause()} method).  (A {@code null} value is
     450      *         permitted, and indicates that the cause is nonexistent or
     451      *         unknown.)
     452      * @return  a reference to this {@code Throwable} instance.
     453      * @throws IllegalArgumentException if {@code cause} is this
     454      *         throwable.  (A throwable cannot be its own cause.)
     455      * @throws IllegalStateException if this throwable was
     456      *         created with {@link #Throwable(Throwable)} or
     457      *         {@link #Throwable(String,Throwable)}, or this method has already
     458      *         been called on this throwable.
     459      * @since  1.4
     460      */
     461     public synchronized Throwable initCause(Throwable cause) {
     462         if (this.cause != this)
     463             throw new IllegalStateException("Can't overwrite cause with " +
     464                                             Objects.toString(cause, "a null"), this);
     465         if (cause == this)
     466             throw new IllegalArgumentException("Self-causation not permitted", this);
     467         this.cause = cause;
     468         return this;
     469     }
     470
     471     /*
     472      * This is called by readObject of a few exceptions such as
     473      * ClassNotFoundException and ExceptionInInitializerError to deserialize
     474      * a stream output from an older runtime version where the cause may
     475      * have set to null.
     476      */
     477     final void setCause(Throwable t) {
     478         this.cause = t;
     479     }
     480
     481     /**
     482      * Returns a short description of this throwable.
     483      * The result is the concatenation of:
     484      * <ul>
     485      * <li> the {@linkplain Class#getName() name} of the class of this object
     486      * <li> ": " (a colon and a space)
     487      * <li> the result of invoking this object's {@link #getLocalizedMessage}
     488      *      method
     489      * </ul>
     490      * If {@code getLocalizedMessage} returns {@code null}, then just
     491      * the class name is returned.
     492      *
     493      * @return a string representation of this throwable.
     494      */
     495     public String toString() {
     496         String s = getClass().getName();
     497         String message = getLocalizedMessage();
     498         return (message != null) ? (s + ": " + message) : s;
     499     }
     500
     501     /**
     502      * Prints this throwable and its backtrace to the
     503      * standard error stream. This method prints a stack trace for this
     504      * {@code Throwable} object on the error output stream that is
     505      * the value of the field {@code System.err}. The first line of
     506      * output contains the result of the {@link #toString()} method for
     507      * this object.  Remaining lines represent data previously recorded by
     508      * the method {@link #fillInStackTrace()}. The format of this
     509      * information depends on the implementation, but the following
     510      * example may be regarded as typical:
     511      * <blockquote><pre>
     512      * java.lang.NullPointerException
     513      *         at MyClass.mash(MyClass.java:9)
     514      *         at MyClass.crunch(MyClass.java:6)
     515      *         at MyClass.main(MyClass.java:3)
     516      * </pre></blockquote>
     517      * This example was produced by running the program:
     518      * <pre>
     519      * class MyClass {
     520      *     public static void main(String[] args) {
     521      *         crunch(null);
     522      *     }
     523      *     static void crunch(int[] a) {
     524      *         mash(a);
     525      *     }
     526      *     static void mash(int[] b) {
     527      *         System.out.println(b[0]);
     528      *     }
     529      * }
     530      * </pre>
     531      * The backtrace for a throwable with an initialized, non-null cause
     532      * should generally include the backtrace for the cause.  The format
     533      * of this information depends on the implementation, but the following
     534      * example may be regarded as typical:
     535      * <pre>
     536      * HighLevelException: MidLevelException: LowLevelException
     537      *         at Junk.a(Junk.java:13)
     538      *         at Junk.main(Junk.java:4)
     539      * Caused by: MidLevelException: LowLevelException
     540      *         at Junk.c(Junk.java:23)
     541      *         at Junk.b(Junk.java:17)
     542      *         at Junk.a(Junk.java:11)
     543      *         ... 1 more
     544      * Caused by: LowLevelException
     545      *         at Junk.e(Junk.java:30)
     546      *         at Junk.d(Junk.java:27)
     547      *         at Junk.c(Junk.java:21)
     548      *         ... 3 more
     549      * </pre>
     550      * Note the presence of lines containing the characters {@code "..."}.
     551      * These lines indicate that the remainder of the stack trace for this
     552      * exception matches the indicated number of frames from the bottom of the
     553      * stack trace of the exception that was caused by this exception (the
     554      * "enclosing" exception).  This shorthand can greatly reduce the length
     555      * of the output in the common case where a wrapped exception is thrown
     556      * from same method as the "causative exception" is caught.  The above
     557      * example was produced by running the program:
     558      * <pre>
     559      * public class Junk {
     560      *     public static void main(String args[]) {
     561      *         try {
     562      *             a();
     563      *         } catch(HighLevelException e) {
     564      *             e.printStackTrace();
     565      *         }
     566      *     }
     567      *     static void a() throws HighLevelException {
     568      *         try {
     569      *             b();
     570      *         } catch(MidLevelException e) {
     571      *             throw new HighLevelException(e);
     572      *         }
     573      *     }
     574      *     static void b() throws MidLevelException {
     575      *         c();
     576      *     }
     577      *     static void c() throws MidLevelException {
     578      *         try {
     579      *             d();
     580      *         } catch(LowLevelException e) {
     581      *             throw new MidLevelException(e);
     582      *         }
     583      *     }
     584      *     static void d() throws LowLevelException {
     585      *        e();
     586      *     }
     587      *     static void e() throws LowLevelException {
     588      *         throw new LowLevelException();
     589      *     }
     590      * }
     591      *
     592      * class HighLevelException extends Exception {
     593      *     HighLevelException(Throwable cause) { super(cause); }
     594      * }
     595      *
     596      * class MidLevelException extends Exception {
     597      *     MidLevelException(Throwable cause)  { super(cause); }
     598      * }
     599      *
     600      * class LowLevelException extends Exception {
     601      * }
     602      * </pre>
     603      * As of release 7, the platform supports the notion of
     604      * <i>suppressed exceptions</i> (in conjunction with the {@code
     605      * try}-with-resources statement). Any exceptions that were
     606      * suppressed in order to deliver an exception are printed out
     607      * beneath the stack trace.  The format of this information
     608      * depends on the implementation, but the following example may be
     609      * regarded as typical:
     610      *
     611      * <pre>
     612      * Exception in thread "main" java.lang.Exception: Something happened
     613      *  at Foo.bar(Foo.java:10)
     614      *  at Foo.main(Foo.java:5)
     615      *  Suppressed: Resource$CloseFailException: Resource ID = 0
     616      *          at Resource.close(Resource.java:26)
     617      *          at Foo.bar(Foo.java:9)
     618      *          ... 1 more
     619      * </pre>
     620      * Note that the "... n more" notation is used on suppressed exceptions
     621      * just as it is used on causes. Unlike causes, suppressed exceptions are
     622      * indented beyond their "containing exceptions."
     623      *
     624      * <p>An exception can have both a cause and one or more suppressed
     625      * exceptions:
     626      * <pre>
     627      * Exception in thread "main" java.lang.Exception: Main block
     628      *  at Foo3.main(Foo3.java:7)
     629      *  Suppressed: Resource$CloseFailException: Resource ID = 2
     630      *          at Resource.close(Resource.java:26)
     631      *          at Foo3.main(Foo3.java:5)
     632      *  Suppressed: Resource$CloseFailException: Resource ID = 1
     633      *          at Resource.close(Resource.java:26)
     634      *          at Foo3.main(Foo3.java:5)
     635      * Caused by: java.lang.Exception: I did it
     636      *  at Foo3.main(Foo3.java:8)
     637      * </pre>
     638      * Likewise, a suppressed exception can have a cause:
     639      * <pre>
     640      * Exception in thread "main" java.lang.Exception: Main block
     641      *  at Foo4.main(Foo4.java:6)
     642      *  Suppressed: Resource2$CloseFailException: Resource ID = 1
     643      *          at Resource2.close(Resource2.java:20)
     644      *          at Foo4.main(Foo4.java:5)
     645      *  Caused by: java.lang.Exception: Rats, you caught me
     646      *          at Resource2$CloseFailException.&lt;init&gt;(Resource2.java:45)
     647      *          ... 2 more
     648      * </pre>
     649      */
     650     public void printStackTrace() {
     651         printStackTrace(System.err);
     652     }
     653
     654     /**
     655      * Prints this throwable and its backtrace to the specified print stream.
     656      *
     657      * @param s {@code PrintStream} to use for output
     658      */
     659     public void printStackTrace(PrintStream s) {
     660         printStackTrace(new WrappedPrintStream(s));
     661     }
     662
     663     private void printStackTrace(PrintStreamOrWriter s) {
     664         // Guard against malicious overrides of Throwable.equals by
     665         // using a Set with identity equality semantics.
     666         Set<Throwable> dejaVu = Collections.newSetFromMap(new IdentityHashMap<>());
     667         dejaVu.add(this);
     668
     669         synchronized (s.lock()) {
     670             // Print our stack trace
     671             s.println(this);
     672             StackTraceElement[] trace = getOurStackTrace();
     673             for (StackTraceElement traceElement : trace)
     674                 s.println("\tat " + traceElement);
     675
     676             // Print suppressed exceptions, if any
     677             for (Throwable se : getSuppressed())
     678                 se.printEnclosedStackTrace(s, trace, SUPPRESSED_CAPTION, "\t", dejaVu);
     679
     680             // Print cause, if any
     681             Throwable ourCause = getCause();
     682             if (ourCause != null)
     683                 ourCause.printEnclosedStackTrace(s, trace, CAUSE_CAPTION, "", dejaVu);
     684         }
     685     }
     686
     687     /**
     688      * Print our stack trace as an enclosed exception for the specified
     689      * stack trace.
     690      */
     691     private void printEnclosedStackTrace(PrintStreamOrWriter s,
     692                                          StackTraceElement[] enclosingTrace,
     693                                          String caption,
     694                                          String prefix,
     695                                          Set<Throwable> dejaVu) {
     696         assert Thread.holdsLock(s.lock());
     697         if (dejaVu.contains(this)) {
     698             s.println(prefix + caption + "[CIRCULAR REFERENCE: " + this + "]");
     699         } else {
     700             dejaVu.add(this);
     701             // Compute number of frames in common between this and enclosing trace
     702             StackTraceElement[] trace = getOurStackTrace();
     703             int m = trace.length - 1;
     704             int n = enclosingTrace.length - 1;
     705             while (m >= 0 && n >=0 && trace[m].equals(enclosingTrace[n])) {
     706                 m--; n--;
     707             }
     708             int framesInCommon = trace.length - 1 - m;
     709
     710             // Print our stack trace
     711             s.println(prefix + caption + this);
     712             for (int i = 0; i <= m; i++)
     713                 s.println(prefix + "\tat " + trace[i]);
     714             if (framesInCommon != 0)
     715                 s.println(prefix + "\t... " + framesInCommon + " more");
     716
     717             // Print suppressed exceptions, if any
     718             for (Throwable se : getSuppressed())
     719                 se.printEnclosedStackTrace(s, trace, SUPPRESSED_CAPTION,
     720                                            prefix +"\t", dejaVu);
     721
     722             // Print cause, if any
     723             Throwable ourCause = getCause();
     724             if (ourCause != null)
     725                 ourCause.printEnclosedStackTrace(s, trace, CAUSE_CAPTION, prefix, dejaVu);
     726         }
     727     }
     728
     729     /**
     730      * Prints this throwable and its backtrace to the specified
     731      * print writer.
     732      *
     733      * @param s {@code PrintWriter} to use for output
     734      * @since   1.1
     735      */
     736     public void printStackTrace(PrintWriter s) {
     737         printStackTrace(new WrappedPrintWriter(s));
     738     }
     739
     740     /**
     741      * Wrapper class for PrintStream and PrintWriter to enable a single
     742      * implementation of printStackTrace.
     743      */
     744     private abstract static class PrintStreamOrWriter {
     745         /** Returns the object to be locked when using this StreamOrWriter */
     746         abstract Object lock();
     747
     748         /** Prints the specified string as a line on this StreamOrWriter */
     749         abstract void println(Object o);
     750     }
     751
     752     private static class WrappedPrintStream extends PrintStreamOrWriter {
     753         private final PrintStream printStream;
     754
     755         WrappedPrintStream(PrintStream printStream) {
     756             this.printStream = printStream;
     757         }
     758
     759         Object lock() {
     760             return printStream;
     761         }
     762
     763         void println(Object o) {
     764             printStream.println(o);
     765         }
     766     }
     767
     768     private static class WrappedPrintWriter extends PrintStreamOrWriter {
     769         private final PrintWriter printWriter;
     770
     771         WrappedPrintWriter(PrintWriter printWriter) {
     772             this.printWriter = printWriter;
     773         }
     774
     775         Object lock() {
     776             return printWriter;
     777         }
     778
     779         void println(Object o) {
     780             printWriter.println(o);
     781         }
     782     }
     783
     784     /**
     785      * Fills in the execution stack trace. This method records within this
     786      * {@code Throwable} object information about the current state of
     787      * the stack frames for the current thread.
     788      *
     789      * <p>If the stack trace of this {@code Throwable} {@linkplain
     790      * Throwable#Throwable(String, Throwable, boolean, boolean) is not
     791      * writable}, calling this method has no effect.
     792      *
     793      * @return  a reference to this {@code Throwable} instance.
     794      * @see     java.lang.Throwable#printStackTrace()
     795      */
     796     public synchronized Throwable fillInStackTrace() {
     797         if (stackTrace != null ||
     798             backtrace != null /* Out of protocol state */ ) {
     799             fillInStackTrace(0);
     800             stackTrace = UNASSIGNED_STACK;
     801         }
     802         return this;
     803     }
     804
     805     private native Throwable fillInStackTrace(int dummy);
     806
     807     /**
     808      * Provides programmatic access to the stack trace information printed by
     809      * {@link #printStackTrace()}.  Returns an array of stack trace elements,
     810      * each representing one stack frame.  The zeroth element of the array
     811      * (assuming the array's length is non-zero) represents the top of the
     812      * stack, which is the last method invocation in the sequence.  Typically,
     813      * this is the point at which this throwable was created and thrown.
     814      * The last element of the array (assuming the array's length is non-zero)
     815      * represents the bottom of the stack, which is the first method invocation
     816      * in the sequence.
     817      *
     818      * <p>Some virtual machines may, under some circumstances, omit one
     819      * or more stack frames from the stack trace.  In the extreme case,
     820      * a virtual machine that has no stack trace information concerning
     821      * this throwable is permitted to return a zero-length array from this
     822      * method.  Generally speaking, the array returned by this method will
     823      * contain one element for every frame that would be printed by
     824      * {@code printStackTrace}.  Writes to the returned array do not
     825      * affect future calls to this method.
     826      *
     827      * @return an array of stack trace elements representing the stack trace
     828      *         pertaining to this throwable.
     829      * @since  1.4
     830      */
     831     public StackTraceElement[] getStackTrace() {
     832         return getOurStackTrace().clone();
     833     }
     834
     835     private synchronized StackTraceElement[] getOurStackTrace() {
     836         // Initialize stack trace field with information from
     837         // backtrace if this is the first call to this method
     838         if (stackTrace == UNASSIGNED_STACK ||
     839             (stackTrace == null && backtrace != null) /* Out of protocol state */) {
     840             stackTrace = StackTraceElement.of(this, depth);
     841         } else if (stackTrace == null) {
     842             return UNASSIGNED_STACK;
     843         }
     844         return stackTrace;
     845     }
     846
     847     /**
     848      * Sets the stack trace elements that will be returned by
     849      * {@link #getStackTrace()} and printed by {@link #printStackTrace()}
     850      * and related methods.
     851      *
     852      * This method, which is designed for use by RPC frameworks and other
     853      * advanced systems, allows the client to override the default
     854      * stack trace that is either generated by {@link #fillInStackTrace()}
     855      * when a throwable is constructed or deserialized when a throwable is
     856      * read from a serialization stream.
     857      *
     858      * <p>If the stack trace of this {@code Throwable} {@linkplain
     859      * Throwable#Throwable(String, Throwable, boolean, boolean) is not
     860      * writable}, calling this method has no effect other than
     861      * validating its argument.
     862      *
     863      * @param   stackTrace the stack trace elements to be associated with
     864      * this {@code Throwable}.  The specified array is copied by this
     865      * call; changes in the specified array after the method invocation
     866      * returns will have no affect on this {@code Throwable}'s stack
     867      * trace.
     868      *
     869      * @throws NullPointerException if {@code stackTrace} is
     870      *         {@code null} or if any of the elements of
     871      *         {@code stackTrace} are {@code null}
     872      *
     873      * @since  1.4
     874      */
     875     public void setStackTrace(StackTraceElement[] stackTrace) {
     876         // Validate argument
     877         StackTraceElement[] defensiveCopy = stackTrace.clone();
     878         for (int i = 0; i < defensiveCopy.length; i++) {
     879             if (defensiveCopy[i] == null)
     880                 throw new NullPointerException("stackTrace[" + i + "]");
     881         }
     882
     883         synchronized (this) {
     884             if (this.stackTrace == null && // Immutable stack
     885                 backtrace == null) // Test for out of protocol state
     886                 return;
     887             this.stackTrace = defensiveCopy;
     888         }
     889     }
     890
     891     /**
     892      * Reads a {@code Throwable} from a stream, enforcing
     893      * well-formedness constraints on fields.  Null entries and
     894      * self-pointers are not allowed in the list of {@code
     895      * suppressedExceptions}.  Null entries are not allowed for stack
     896      * trace elements.  A null stack trace in the serial form results
     897      * in a zero-length stack element array. A single-element stack
     898      * trace whose entry is equal to {@code new StackTraceElement("",
     899      * "", null, Integer.MIN_VALUE)} results in a {@code null} {@code
     900      * stackTrace} field.
     901      *
     902      * Note that there are no constraints on the value the {@code
     903      * cause} field can hold; both {@code null} and {@code this} are
     904      * valid values for the field.
     905      *
     906      * @param  s the {@code ObjectInputStream} from which data is read
     907      * @throws IOException if an I/O error occurs
     908      * @throws ClassNotFoundException if a serialized class cannot be loaded
     909      */
     910     @java.io.Serial
     911     private void readObject(ObjectInputStream s)
     912         throws IOException, ClassNotFoundException {
     913         s.defaultReadObject();     // read in all fields
     914
     915         // Set suppressed exceptions and stack trace elements fields
     916         // to marker values until the contents from the serial stream
     917         // are validated.
     918         List<Throwable> candidateSuppressedExceptions = suppressedExceptions;
     919         suppressedExceptions = SUPPRESSED_SENTINEL;
     920
     921         StackTraceElement[] candidateStackTrace = stackTrace;
     922         stackTrace = UNASSIGNED_STACK.clone();
     923
     924         if (candidateSuppressedExceptions != null) {
     925             int suppressedSize = validateSuppressedExceptionsList(candidateSuppressedExceptions);
     926             if (suppressedSize > 0) { // Copy valid Throwables to new list
     927                 var suppList  = new ArrayList<Throwable>(Math.min(100, suppressedSize));
     928
     929                 for (Throwable t : candidateSuppressedExceptions) {
     930                     // Enforce constraints on suppressed exceptions in
     931                     // case of corrupt or malicious stream.
     932                     Objects.requireNonNull(t, NULL_CAUSE_MESSAGE);
     933                     if (t == this)
     934                         throw new IllegalArgumentException(SELF_SUPPRESSION_MESSAGE);
     935                     suppList.add(t);
     936                 }
     937                 // If there are any invalid suppressed exceptions,
     938                 // implicitly use the sentinel value assigned earlier.
     939                 suppressedExceptions = suppList;
     940             }
     941         } else {
     942             suppressedExceptions = null;
     943         }
     944
     945         /*
     946          * For zero-length stack traces, use a clone of
     947          * UNASSIGNED_STACK rather than UNASSIGNED_STACK itself to
     948          * allow identity comparison against UNASSIGNED_STACK in
     949          * getOurStackTrace.  The identity of UNASSIGNED_STACK in
     950          * stackTrace indicates to the getOurStackTrace method that
     951          * the stackTrace needs to be constructed from the information
     952          * in backtrace.
     953          */
     954         if (candidateStackTrace != null) {
     955             // Work from a clone of the candidateStackTrace to ensure
     956             // consistency of checks.
     957             candidateStackTrace = candidateStackTrace.clone();
     958             if (candidateStackTrace.length >= 1) {
     959                 if (candidateStackTrace.length == 1 &&
     960                         // Check for the marker of an immutable stack trace
     961                         SentinelHolder.STACK_TRACE_ELEMENT_SENTINEL.equals(candidateStackTrace[0])) {
     962                     stackTrace = null;
     963                 } else { // Verify stack trace elements are non-null.
     964                     for (StackTraceElement ste : candidateStackTrace) {
     965                         Objects.requireNonNull(ste, "null StackTraceElement in serial stream.");
     966                     }
     967                     stackTrace = candidateStackTrace;
     968                 }
     969             }
     970         }
     971         // A null stackTrace field in the serial form can result from
     972         // an exception serialized without that field in older JDK
     973         // releases; treat such exceptions as having empty stack
     974         // traces by leaving stackTrace assigned to a clone of
     975         // UNASSIGNED_STACK.
     976     }
     977
     978     private int validateSuppressedExceptionsList(List<Throwable> deserSuppressedExceptions)
     979         throws IOException {
     980         if (!Object.class.getModule().
     981             equals(deserSuppressedExceptions.getClass().getModule())) {
     982             throw new StreamCorruptedException("List implementation not in base module.");
     983         } else {
     984             int size = deserSuppressedExceptions.size();
     985             if (size < 0) {
     986                 throw new StreamCorruptedException("Negative list size reported.");
     987             }
     988             return size;
     989         }
     990     }
     991
     992     /**
     993      * Write a {@code Throwable} object to a stream.
     994      *
     995      * A {@code null} stack trace field is represented in the serial
     996      * form as a one-element array whose element is equal to {@code
     997      * new StackTraceElement("", "", null, Integer.MIN_VALUE)}.
     998      *
     999      * @param  s the {@code ObjectOutputStream} to which data is written
    1000      * @throws IOException if an I/O error occurs
    1001      */
    1002     @java.io.Serial
    1003     private synchronized void writeObject(ObjectOutputStream s)
    1004         throws IOException {
    1005         // Ensure that the stackTrace field is initialized to a
    1006         // non-null value, if appropriate.  As of JDK 7, a null stack
    1007         // trace field is a valid value indicating the stack trace
    1008         // should not be set.
    1009         getOurStackTrace();
    1010
    1011         StackTraceElement[] oldStackTrace = stackTrace;
    1012         try {
    1013             if (stackTrace == null)
    1014                 stackTrace = SentinelHolder.STACK_TRACE_SENTINEL;
    1015             s.defaultWriteObject();
    1016         } finally {
    1017             stackTrace = oldStackTrace;
    1018         }
    1019     }
    1020
    1021     /**
    1022      * Appends the specified exception to the exceptions that were
    1023      * suppressed in order to deliver this exception. This method is
    1024      * thread-safe and typically called (automatically and implicitly)
    1025      * by the {@code try}-with-resources statement.
    1026      *
    1027      * <p>The suppression behavior is enabled <em>unless</em> disabled
    1028      * {@linkplain #Throwable(String, Throwable, boolean, boolean) via
    1029      * a constructor}.  When suppression is disabled, this method does
    1030      * nothing other than to validate its argument.
    1031      *
    1032      * <p>Note that when one exception {@linkplain
    1033      * #initCause(Throwable) causes} another exception, the first
    1034      * exception is usually caught and then the second exception is
    1035      * thrown in response.  In other words, there is a causal
    1036      * connection between the two exceptions.
    1037      *
    1038      * In contrast, there are situations where two independent
    1039      * exceptions can be thrown in sibling code blocks, in particular
    1040      * in the {@code try} block of a {@code try}-with-resources
    1041      * statement and the compiler-generated {@code finally} block
    1042      * which closes the resource.
    1043      *
    1044      * In these situations, only one of the thrown exceptions can be
    1045      * propagated.  In the {@code try}-with-resources statement, when
    1046      * there are two such exceptions, the exception originating from
    1047      * the {@code try} block is propagated and the exception from the
    1048      * {@code finally} block is added to the list of exceptions
    1049      * suppressed by the exception from the {@code try} block.  As an
    1050      * exception unwinds the stack, it can accumulate multiple
    1051      * suppressed exceptions.
    1052      *
    1053      * <p>An exception may have suppressed exceptions while also being
    1054      * caused by another exception.  Whether or not an exception has a
    1055      * cause is semantically known at the time of its creation, unlike
    1056      * whether or not an exception will suppress other exceptions
    1057      * which is typically only determined after an exception is
    1058      * thrown.
    1059      *
    1060      * <p>Note that programmer written code is also able to take
    1061      * advantage of calling this method in situations where there are
    1062      * multiple sibling exceptions and only one can be propagated.
    1063      *
    1064      * @param exception the exception to be added to the list of
    1065      *        suppressed exceptions
    1066      * @throws IllegalArgumentException if {@code exception} is this
    1067      *         throwable; a throwable cannot suppress itself.
    1068      * @throws NullPointerException if {@code exception} is {@code null}
    1069      * @since 1.7
    1070      */
    1071     public final synchronized void addSuppressed(Throwable exception) {
    1072         if (exception == this)
    1073             throw new IllegalArgumentException(SELF_SUPPRESSION_MESSAGE, exception);
    1074
    1075         Objects.requireNonNull(exception, NULL_CAUSE_MESSAGE);
    1076
    1077         if (suppressedExceptions == null) // Suppressed exceptions not recorded
    1078             return;
    1079
    1080         if (suppressedExceptions == SUPPRESSED_SENTINEL)
    1081             suppressedExceptions = new ArrayList<>(1);
    1082
    1083         suppressedExceptions.add(exception);
    1084     }
    1085
    1086     private static final Throwable[] EMPTY_THROWABLE_ARRAY = new Throwable[0];
    1087
    1088     /**
    1089      * Returns an array containing all of the exceptions that were
    1090      * suppressed, typically by the {@code try}-with-resources
    1091      * statement, in order to deliver this exception.
    1092      *
    1093      * If no exceptions were suppressed or {@linkplain
    1094      * #Throwable(String, Throwable, boolean, boolean) suppression is
    1095      * disabled}, an empty array is returned.  This method is
    1096      * thread-safe.  Writes to the returned array do not affect future
    1097      * calls to this method.
    1098      *
    1099      * @return an array containing all of the exceptions that were
    1100      *         suppressed to deliver this exception.
    1101      * @since 1.7
    1102      */
    1103     public final synchronized Throwable[] getSuppressed() {
    1104         if (suppressedExceptions == SUPPRESSED_SENTINEL ||
    1105             suppressedExceptions == null)
    1106             return EMPTY_THROWABLE_ARRAY;
    1107         else
    1108             return suppressedExceptions.toArray(EMPTY_THROWABLE_ARRAY);
    1109     }
    1110 }