In order to support fields of the same name in subclasses we are now prefixing them with name of the class that defines them. To provide convenient way to access them from generated bytecode and also directly from JavaScript, there is a getter/setter function for each field. It starts with _ followed by the field name. If called with a parameter, it sets the field, with a parameter it just returns it.
2 * Copyright (c) 1994, 2011, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
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.
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).
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.
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
28 import org.apidesign.bck2brwsr.core.JavaScriptBody;
29 import org.apidesign.bck2brwsr.core.JavaScriptOnly;
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.
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.
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).
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.
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
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.)
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.
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
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
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
115 public class Throwable implements Serializable {
116 /** use serialVersionUID from JDK 1.0.2 for interoperability */
117 private static final long serialVersionUID = -3042686055658047285L;
120 * Native code saves some indication of the stack backtrace in this slot.
122 private transient Object backtrace;
125 * Specific details about the Throwable. For example, for
126 * {@code FileNotFoundException}, this contains the name of
127 * the file that could not be found.
131 private String detailMessage;
135 * Holder class to defer initializing sentinel objects only used
138 private static class SentinelHolder {
140 * {@linkplain #setStackTrace(StackTraceElement[]) Setting the
141 * stack trace} to a one-element array containing this sentinel
142 * value indicates future attempts to set the stack trace will be
143 * ignored. The sentinal is equal to the result of calling:<br>
144 * {@code new StackTraceElement("", "", null, Integer.MIN_VALUE)}
146 public static final StackTraceElement STACK_TRACE_ELEMENT_SENTINEL =
147 new StackTraceElement("", "", null, Integer.MIN_VALUE);
150 * Sentinel value used in the serial form to indicate an immutable
153 public static final StackTraceElement[] STACK_TRACE_SENTINEL =
154 new StackTraceElement[] {STACK_TRACE_ELEMENT_SENTINEL};
158 * A shared value for an empty stack.
160 private static final StackTraceElement[] UNASSIGNED_STACK = new StackTraceElement[0];
163 * To allow Throwable objects to be made immutable and safely
164 * reused by the JVM, such as OutOfMemoryErrors, fields of
165 * Throwable that are writable in response to user actions, cause,
166 * stackTrace, and suppressedExceptions obey the following
169 * 1) The fields are initialized to a non-null sentinel value
170 * which indicates the value has logically not been set.
172 * 2) Writing a null to the field indicates further writes
175 * 3) The sentinel value may be replaced with another non-null
178 * For example, implementations of the HotSpot JVM have
179 * preallocated OutOfMemoryError objects to provide for better
180 * diagnosability of that situation. These objects are created
181 * without calling the constructor for that class and the fields
182 * in question are initialized to null. To support this
183 * capability, any new fields added to Throwable that require
184 * being initialized to a non-null value require a coordinated JVM
189 * The throwable that caused this throwable to get thrown, or null if this
190 * throwable was not caused by another throwable, or if the causative
191 * throwable is unknown. If this field is equal to this throwable itself,
192 * it indicates that the cause of this throwable has not yet been
198 private Throwable cause = this;
201 * The stack trace, as returned by {@link #getStackTrace()}.
203 * The field is initialized to a zero-length array. A {@code
204 * null} value of this field indicates subsequent calls to {@link
205 * #setStackTrace(StackTraceElement[])} and {@link
206 * #fillInStackTrace()} will be be no-ops.
211 private StackTraceElement[] stackTrace = UNASSIGNED_STACK;
213 // Setting this static field introduces an acceptable
214 // initialization dependency on a few java.util classes.
215 // I don't think this dependency is acceptable
216 // private static final List<Throwable> SUPPRESSED_SENTINEL =
217 // Collections.unmodifiableList(new ArrayList<Throwable>(0));
220 * The list of suppressed exceptions, as returned by {@link
221 * #getSuppressed()}. The list is initialized to a zero-element
222 * unmodifiable sentinel list. When a serialized Throwable is
223 * read in, if the {@code suppressedExceptions} field points to a
224 * zero-element list, the field is reset to the sentinel value.
229 // private List<Throwable> suppressedExceptions = SUPPRESSED_SENTINEL;
231 /** Message for trying to suppress a null exception. */
232 private static final String NULL_CAUSE_MESSAGE = "Cannot suppress a null exception.";
234 /** Message for trying to suppress oneself. */
235 private static final String SELF_SUPPRESSION_MESSAGE = "Self-suppression not permitted";
237 /** Caption for labeling causative exception stack traces */
238 @JavaScriptOnly(name="toString", value="function() { return this.toString__Ljava_lang_String_2().toString(); }")
239 private static void jsToString() {
242 @JavaScriptOnly(name="valueOf", value="function() { return this.toString().valueOf(); }")
243 private static void jsValudOf() {
245 private static final String CAUSE_CAPTION = "Caused by: ";
247 /** Caption for labeling suppressed exception stack traces */
248 private static final String SUPPRESSED_CAPTION = "Suppressed: ";
251 * Constructs a new throwable with {@code null} as its detail message.
252 * The cause is not initialized, and may subsequently be initialized by a
253 * call to {@link #initCause}.
255 * <p>The {@link #fillInStackTrace()} method is called to initialize
256 * the stack trace data in the newly created throwable.
263 * Constructs a new throwable with the specified detail message. The
264 * cause is not initialized, and may subsequently be initialized by
265 * a call to {@link #initCause}.
267 * <p>The {@link #fillInStackTrace()} method is called to initialize
268 * the stack trace data in the newly created throwable.
270 * @param message the detail message. The detail message is saved for
271 * later retrieval by the {@link #getMessage()} method.
273 public Throwable(String message) {
275 detailMessage = message;
279 * Constructs a new throwable with the specified detail message and
280 * cause. <p>Note that the detail message associated with
281 * {@code cause} is <i>not</i> automatically incorporated in
282 * this throwable's detail message.
284 * <p>The {@link #fillInStackTrace()} method is called to initialize
285 * the stack trace data in the newly created throwable.
287 * @param message the detail message (which is saved for later retrieval
288 * by the {@link #getMessage()} method).
289 * @param cause the cause (which is saved for later retrieval by the
290 * {@link #getCause()} method). (A {@code null} value is
291 * permitted, and indicates that the cause is nonexistent or
295 public Throwable(String message, Throwable cause) {
297 detailMessage = message;
302 * Constructs a new throwable with the specified cause and a detail
303 * message of {@code (cause==null ? null : cause.toString())} (which
304 * typically contains the class and detail message of {@code cause}).
305 * This constructor is useful for throwables that are little more than
306 * wrappers for other throwables (for example, {@link
307 * java.security.PrivilegedActionException}).
309 * <p>The {@link #fillInStackTrace()} method is called to initialize
310 * the stack trace data in the newly created throwable.
312 * @param cause the cause (which is saved for later retrieval by the
313 * {@link #getCause()} method). (A {@code null} value is
314 * permitted, and indicates that the cause is nonexistent or
318 public Throwable(Throwable cause) {
320 detailMessage = (cause==null ? null : cause.toString());
325 * Constructs a new throwable with the specified detail message,
326 * cause, {@linkplain #addSuppressed suppression} enabled or
327 * disabled, and writable stack trace enabled or disabled. If
328 * suppression is disabled, {@link #getSuppressed} for this object
329 * will return a zero-length array and calls to {@link
330 * #addSuppressed} that would otherwise append an exception to the
331 * suppressed list will have no effect. If the writable stack
332 * trace is false, this constructor will not call {@link
333 * #fillInStackTrace()}, a {@code null} will be written to the
334 * {@code stackTrace} field, and subsequent calls to {@code
335 * fillInStackTrace} and {@link
336 * #setStackTrace(StackTraceElement[])} will not set the stack
337 * trace. If the writable stack trace is false, {@link
338 * #getStackTrace} will return a zero length array.
340 * <p>Note that the other constructors of {@code Throwable} treat
341 * suppression as being enabled and the stack trace as being
342 * writable. Subclasses of {@code Throwable} should document any
343 * conditions under which suppression is disabled and document
344 * conditions under which the stack trace is not writable.
345 * Disabling of suppression should only occur in exceptional
346 * circumstances where special requirements exist, such as a
347 * virtual machine reusing exception objects under low-memory
348 * situations. Circumstances where a given exception object is
349 * repeatedly caught and rethrown, such as to implement control
350 * flow between two sub-systems, is another situation where
351 * immutable throwable objects would be appropriate.
353 * @param message the detail message.
354 * @param cause the cause. (A {@code null} value is permitted,
355 * and indicates that the cause is nonexistent or unknown.)
356 * @param enableSuppression whether or not suppression is enabled or disabled
357 * @param writableStackTrace whether or not the stack trace should be
360 * @see OutOfMemoryError
361 * @see NullPointerException
362 * @see ArithmeticException
365 protected Throwable(String message, Throwable cause,
366 boolean enableSuppression,
367 boolean writableStackTrace) {
368 if (writableStackTrace) {
373 detailMessage = message;
375 // if (!enableSuppression)
376 // suppressedExceptions = null;
380 * Returns the detail message string of this throwable.
382 * @return the detail message string of this {@code Throwable} instance
383 * (which may be {@code null}).
385 public String getMessage() {
386 return detailMessage;
390 * Creates a localized description of this throwable.
391 * Subclasses may override this method in order to produce a
392 * locale-specific message. For subclasses that do not override this
393 * method, the default implementation returns the same result as
394 * {@code getMessage()}.
396 * @return The localized description of this throwable.
399 public String getLocalizedMessage() {
404 * Returns the cause of this throwable or {@code null} if the
405 * cause is nonexistent or unknown. (The cause is the throwable that
406 * caused this throwable to get thrown.)
408 * <p>This implementation returns the cause that was supplied via one of
409 * the constructors requiring a {@code Throwable}, or that was set after
410 * creation with the {@link #initCause(Throwable)} method. While it is
411 * typically unnecessary to override this method, a subclass can override
412 * it to return a cause set by some other means. This is appropriate for
413 * a "legacy chained throwable" that predates the addition of chained
414 * exceptions to {@code Throwable}. Note that it is <i>not</i>
415 * necessary to override any of the {@code PrintStackTrace} methods,
416 * all of which invoke the {@code getCause} method to determine the
417 * cause of a throwable.
419 * @return the cause of this throwable or {@code null} if the
420 * cause is nonexistent or unknown.
423 public synchronized Throwable getCause() {
424 return (cause==this ? null : cause);
428 * Initializes the <i>cause</i> of this throwable to the specified value.
429 * (The cause is the throwable that caused this throwable to get thrown.)
431 * <p>This method can be called at most once. It is generally called from
432 * within the constructor, or immediately after creating the
433 * throwable. If this throwable was created
434 * with {@link #Throwable(Throwable)} or
435 * {@link #Throwable(String,Throwable)}, this method cannot be called
438 * <p>An example of using this method on a legacy throwable type
439 * without other support for setting the cause is:
444 * } catch (LowLevelException le) {
445 * throw (HighLevelException)
446 * new HighLevelException().initCause(le); // Legacy constructor
450 * @param cause the cause (which is saved for later retrieval by the
451 * {@link #getCause()} method). (A {@code null} value is
452 * permitted, and indicates that the cause is nonexistent or
454 * @return a reference to this {@code Throwable} instance.
455 * @throws IllegalArgumentException if {@code cause} is this
456 * throwable. (A throwable cannot be its own cause.)
457 * @throws IllegalStateException if this throwable was
458 * created with {@link #Throwable(Throwable)} or
459 * {@link #Throwable(String,Throwable)}, or this method has already
460 * been called on this throwable.
463 public synchronized Throwable initCause(Throwable cause) {
464 if (this.cause != this)
465 throw new IllegalStateException("Can't overwrite cause");
467 throw new IllegalArgumentException("Self-causation not permitted");
473 * Returns a short description of this throwable.
474 * The result is the concatenation of:
476 * <li> the {@linkplain Class#getName() name} of the class of this object
477 * <li> ": " (a colon and a space)
478 * <li> the result of invoking this object's {@link #getLocalizedMessage}
481 * If {@code getLocalizedMessage} returns {@code null}, then just
482 * the class name is returned.
484 * @return a string representation of this throwable.
486 public String toString() {
487 String s = getClass().getName();
488 String message = getLocalizedMessage();
489 return (message != null) ? (s + ": " + message) : s;
493 * Prints this throwable and its backtrace to the
494 * standard error stream. This method prints a stack trace for this
495 * {@code Throwable} object on the error output stream that is
496 * the value of the field {@code System.err}. The first line of
497 * output contains the result of the {@link #toString()} method for
498 * this object. Remaining lines represent data previously recorded by
499 * the method {@link #fillInStackTrace()}. The format of this
500 * information depends on the implementation, but the following
501 * example may be regarded as typical:
503 * java.lang.NullPointerException
504 * at MyClass.mash(MyClass.java:9)
505 * at MyClass.crunch(MyClass.java:6)
506 * at MyClass.main(MyClass.java:3)
507 * </pre></blockquote>
508 * This example was produced by running the program:
511 * public static void main(String[] args) {
514 * static void crunch(int[] a) {
517 * static void mash(int[] b) {
518 * System.out.println(b[0]);
522 * The backtrace for a throwable with an initialized, non-null cause
523 * should generally include the backtrace for the cause. The format
524 * of this information depends on the implementation, but the following
525 * example may be regarded as typical:
527 * HighLevelException: MidLevelException: LowLevelException
528 * at Junk.a(Junk.java:13)
529 * at Junk.main(Junk.java:4)
530 * Caused by: MidLevelException: LowLevelException
531 * at Junk.c(Junk.java:23)
532 * at Junk.b(Junk.java:17)
533 * at Junk.a(Junk.java:11)
535 * Caused by: LowLevelException
536 * at Junk.e(Junk.java:30)
537 * at Junk.d(Junk.java:27)
538 * at Junk.c(Junk.java:21)
541 * Note the presence of lines containing the characters {@code "..."}.
542 * These lines indicate that the remainder of the stack trace for this
543 * exception matches the indicated number of frames from the bottom of the
544 * stack trace of the exception that was caused by this exception (the
545 * "enclosing" exception). This shorthand can greatly reduce the length
546 * of the output in the common case where a wrapped exception is thrown
547 * from same method as the "causative exception" is caught. The above
548 * example was produced by running the program:
550 * public class Junk {
551 * public static void main(String args[]) {
554 * } catch(HighLevelException e) {
555 * e.printStackTrace();
558 * static void a() throws HighLevelException {
561 * } catch(MidLevelException e) {
562 * throw new HighLevelException(e);
565 * static void b() throws MidLevelException {
568 * static void c() throws MidLevelException {
571 * } catch(LowLevelException e) {
572 * throw new MidLevelException(e);
575 * static void d() throws LowLevelException {
578 * static void e() throws LowLevelException {
579 * throw new LowLevelException();
583 * class HighLevelException extends Exception {
584 * HighLevelException(Throwable cause) { super(cause); }
587 * class MidLevelException extends Exception {
588 * MidLevelException(Throwable cause) { super(cause); }
591 * class LowLevelException extends Exception {
594 * As of release 7, the platform supports the notion of
595 * <i>suppressed exceptions</i> (in conjunction with the {@code
596 * try}-with-resources statement). Any exceptions that were
597 * suppressed in order to deliver an exception are printed out
598 * beneath the stack trace. The format of this information
599 * depends on the implementation, but the following example may be
600 * regarded as typical:
603 * Exception in thread "main" java.lang.Exception: Something happened
604 * at Foo.bar(Foo.java:10)
605 * at Foo.main(Foo.java:5)
606 * Suppressed: Resource$CloseFailException: Resource ID = 0
607 * at Resource.close(Resource.java:26)
608 * at Foo.bar(Foo.java:9)
611 * Note that the "... n more" notation is used on suppressed exceptions
612 * just at it is used on causes. Unlike causes, suppressed exceptions are
613 * indented beyond their "containing exceptions."
615 * <p>An exception can have both a cause and one or more suppressed
618 * Exception in thread "main" java.lang.Exception: Main block
619 * at Foo3.main(Foo3.java:7)
620 * Suppressed: Resource$CloseFailException: Resource ID = 2
621 * at Resource.close(Resource.java:26)
622 * at Foo3.main(Foo3.java:5)
623 * Suppressed: Resource$CloseFailException: Resource ID = 1
624 * at Resource.close(Resource.java:26)
625 * at Foo3.main(Foo3.java:5)
626 * Caused by: java.lang.Exception: I did it
627 * at Foo3.main(Foo3.java:8)
629 * Likewise, a suppressed exception can have a cause:
631 * Exception in thread "main" java.lang.Exception: Main block
632 * at Foo4.main(Foo4.java:6)
633 * Suppressed: Resource2$CloseFailException: Resource ID = 1
634 * at Resource2.close(Resource2.java:20)
635 * at Foo4.main(Foo4.java:5)
636 * Caused by: java.lang.Exception: Rats, you caught me
637 * at Resource2$CloseFailException.<init>(Resource2.java:45)
641 // public void printStackTrace() {
642 // printStackTrace(System.err);
646 // * Prints this throwable and its backtrace to the specified print stream.
648 // * @param s {@code PrintStream} to use for output
650 // public void printStackTrace(PrintStream s) {
651 // printStackTrace(new WrappedPrintStream(s));
654 // private void printStackTrace(PrintStreamOrWriter s) {
655 // // Guard against malicious overrides of Throwable.equals by
656 // // using a Set with identity equality semantics.
657 //// Set<Throwable> dejaVu =
658 //// Collections.newSetFromMap(new IdentityHashMap<Throwable, Boolean>());
659 //// dejaVu.add(this);
661 // synchronized (s.lock()) {
662 // // Print our stack trace
664 // StackTraceElement[] trace = getOurStackTrace();
665 // for (StackTraceElement traceElement : trace)
666 // s.println("\tat " + traceElement);
668 // // Print suppressed exceptions, if any
669 //// for (Throwable se : getSuppressed())
670 //// se.printEnclosedStackTrace(s, trace, SUPPRESSED_CAPTION, "\t", dejaVu);
672 // // Print cause, if any
673 // Throwable ourCause = getCause();
674 //// if (ourCause != null)
675 //// ourCause.printEnclosedStackTrace(s, trace, CAUSE_CAPTION, "", dejaVu);
680 // * Print our stack trace as an enclosed exception for the specified
683 // private void printEnclosedStackTrace(PrintStreamOrWriter s,
684 // StackTraceElement[] enclosingTrace,
688 // assert Thread.holdsLock(s.lock());
690 // // Compute number of frames in common between this and enclosing trace
691 // StackTraceElement[] trace = getOurStackTrace();
692 // int m = trace.length - 1;
693 // int n = enclosingTrace.length - 1;
694 // while (m >= 0 && n >=0 && trace[m].equals(enclosingTrace[n])) {
697 // int framesInCommon = trace.length - 1 - m;
699 // // Print our stack trace
700 // s.println(prefix + caption + this);
701 // for (int i = 0; i <= m; i++)
702 // s.println(prefix + "\tat " + trace[i]);
703 // if (framesInCommon != 0)
704 // s.println(prefix + "\t... " + framesInCommon + " more");
706 // // Print suppressed exceptions, if any
707 // for (Throwable se : getSuppressed())
708 // se.printEnclosedStackTrace(s, trace, SUPPRESSED_CAPTION,
709 // prefix +"\t", dejaVu);
711 // // Print cause, if any
712 // Throwable ourCause = getCause();
713 // if (ourCause != null)
714 // ourCause.printEnclosedStackTrace(s, trace, CAUSE_CAPTION, prefix, dejaVu);
719 // * Prints this throwable and its backtrace to the specified
722 // * @param s {@code PrintWriter} to use for output
725 // public void printStackTrace(PrintWriter s) {
726 // printStackTrace(new WrappedPrintWriter(s));
730 // * Wrapper class for PrintStream and PrintWriter to enable a single
731 // * implementation of printStackTrace.
733 // private abstract static class PrintStreamOrWriter {
734 // /** Returns the object to be locked when using this StreamOrWriter */
735 // abstract Object lock();
737 // /** Prints the specified string as a line on this StreamOrWriter */
738 // abstract void println(Object o);
741 // private static class WrappedPrintStream extends PrintStreamOrWriter {
742 // private final PrintStream printStream;
744 // WrappedPrintStream(PrintStream printStream) {
745 // this.printStream = printStream;
749 // return printStream;
752 // void println(Object o) {
753 // printStream.println(o);
757 // private static class WrappedPrintWriter extends PrintStreamOrWriter {
758 // private final PrintWriter printWriter;
760 // WrappedPrintWriter(PrintWriter printWriter) {
761 // this.printWriter = printWriter;
765 // return printWriter;
768 // void println(Object o) {
769 // printWriter.println(o);
774 * Fills in the execution stack trace. This method records within this
775 * {@code Throwable} object information about the current state of
776 * the stack frames for the current thread.
778 * <p>If the stack trace of this {@code Throwable} {@linkplain
779 * Throwable#Throwable(String, Throwable, boolean, boolean) is not
780 * writable}, calling this method has no effect.
782 * @return a reference to this {@code Throwable} instance.
783 * @see java.lang.Throwable#printStackTrace()
785 public synchronized Throwable fillInStackTrace() {
786 if (stackTrace != null ||
787 backtrace != null /* Out of protocol state */ ) {
789 stackTrace = UNASSIGNED_STACK;
794 @JavaScriptBody(args = { "dummy" }, body = "")
795 private native Throwable fillInStackTrace(int dummy);
798 * Provides programmatic access to the stack trace information printed by
799 * {@link #printStackTrace()}. Returns an array of stack trace elements,
800 * each representing one stack frame. The zeroth element of the array
801 * (assuming the array's length is non-zero) represents the top of the
802 * stack, which is the last method invocation in the sequence. Typically,
803 * this is the point at which this throwable was created and thrown.
804 * The last element of the array (assuming the array's length is non-zero)
805 * represents the bottom of the stack, which is the first method invocation
808 * <p>Some virtual machines may, under some circumstances, omit one
809 * or more stack frames from the stack trace. In the extreme case,
810 * a virtual machine that has no stack trace information concerning
811 * this throwable is permitted to return a zero-length array from this
812 * method. Generally speaking, the array returned by this method will
813 * contain one element for every frame that would be printed by
814 * {@code printStackTrace}. Writes to the returned array do not
815 * affect future calls to this method.
817 * @return an array of stack trace elements representing the stack trace
818 * pertaining to this throwable.
821 public StackTraceElement[] getStackTrace() {
822 return getOurStackTrace().clone();
825 private synchronized StackTraceElement[] getOurStackTrace() {
826 // Initialize stack trace field with information from
827 // backtrace if this is the first call to this method
828 if (stackTrace == UNASSIGNED_STACK ||
829 (stackTrace == null && backtrace != null) /* Out of protocol state */) {
830 int depth = getStackTraceDepth();
831 stackTrace = new StackTraceElement[depth];
832 for (int i=0; i < depth; i++)
833 stackTrace[i] = getStackTraceElement(i);
834 } else if (stackTrace == null) {
835 return UNASSIGNED_STACK;
841 * Sets the stack trace elements that will be returned by
842 * {@link #getStackTrace()} and printed by {@link #printStackTrace()}
843 * and related methods.
845 * This method, which is designed for use by RPC frameworks and other
846 * advanced systems, allows the client to override the default
847 * stack trace that is either generated by {@link #fillInStackTrace()}
848 * when a throwable is constructed or deserialized when a throwable is
849 * read from a serialization stream.
851 * <p>If the stack trace of this {@code Throwable} {@linkplain
852 * Throwable#Throwable(String, Throwable, boolean, boolean) is not
853 * writable}, calling this method has no effect other than
854 * validating its argument.
856 * @param stackTrace the stack trace elements to be associated with
857 * this {@code Throwable}. The specified array is copied by this
858 * call; changes in the specified array after the method invocation
859 * returns will have no affect on this {@code Throwable}'s stack
862 * @throws NullPointerException if {@code stackTrace} is
863 * {@code null} or if any of the elements of
864 * {@code stackTrace} are {@code null}
868 public void setStackTrace(StackTraceElement[] stackTrace) {
870 StackTraceElement[] defensiveCopy = stackTrace.clone();
871 for (int i = 0; i < defensiveCopy.length; i++) {
872 if (defensiveCopy[i] == null)
873 throw new NullPointerException("stackTrace[" + i + "]");
876 synchronized (this) {
877 if (this.stackTrace == null && // Immutable stack
878 backtrace == null) // Test for out of protocol state
880 this.stackTrace = defensiveCopy;
885 * Returns the number of elements in the stack trace (or 0 if the stack
886 * trace is unavailable).
888 * package-protection for use by SharedSecrets.
890 native int getStackTraceDepth();
893 * Returns the specified element of the stack trace.
895 * package-protection for use by SharedSecrets.
897 * @param index index of the element to return.
898 * @throws IndexOutOfBoundsException if {@code index < 0 ||
899 * index >= getStackTraceDepth() }
901 native StackTraceElement getStackTraceElement(int index);
904 * Reads a {@code Throwable} from a stream, enforcing
905 * well-formedness constraints on fields. Null entries and
906 * self-pointers are not allowed in the list of {@code
907 * suppressedExceptions}. Null entries are not allowed for stack
908 * trace elements. A null stack trace in the serial form results
909 * in a zero-length stack element array. A single-element stack
910 * trace whose entry is equal to {@code new StackTraceElement("",
911 * "", null, Integer.MIN_VALUE)} results in a {@code null} {@code
914 * Note that there are no constraints on the value the {@code
915 * cause} field can hold; both {@code null} and {@code this} are
916 * valid values for the field.
918 // private void readObject(ObjectInputStream s)
919 // throws IOException, ClassNotFoundException {
920 // s.defaultReadObject(); // read in all fields
921 // if (suppressedExceptions != null) {
922 // List<Throwable> suppressed = null;
923 // if (suppressedExceptions.isEmpty()) {
924 // // Use the sentinel for a zero-length list
925 // suppressed = SUPPRESSED_SENTINEL;
926 // } else { // Copy Throwables to new list
927 // suppressed = new ArrayList<Throwable>(1);
928 // for (Throwable t : suppressedExceptions) {
929 // // Enforce constraints on suppressed exceptions in
930 // // case of corrupt or malicious stream.
932 // throw new NullPointerException(NULL_CAUSE_MESSAGE);
934 // throw new IllegalArgumentException(SELF_SUPPRESSION_MESSAGE);
935 // suppressed.add(t);
938 // suppressedExceptions = suppressed;
939 // } // else a null suppressedExceptions field remains null
942 // * For zero-length stack traces, use a clone of
943 // * UNASSIGNED_STACK rather than UNASSIGNED_STACK itself to
944 // * allow identity comparison against UNASSIGNED_STACK in
945 // * getOurStackTrace. The identity of UNASSIGNED_STACK in
946 // * stackTrace indicates to the getOurStackTrace method that
947 // * the stackTrace needs to be constructed from the information
950 // if (stackTrace != null) {
951 // if (stackTrace.length == 0) {
952 // stackTrace = UNASSIGNED_STACK.clone();
953 // } else if (stackTrace.length == 1 &&
954 // // Check for the marker of an immutable stack trace
955 // SentinelHolder.STACK_TRACE_ELEMENT_SENTINEL.equals(stackTrace[0])) {
956 // stackTrace = null;
957 // } else { // Verify stack trace elements are non-null.
958 // for(StackTraceElement ste : stackTrace) {
960 // throw new NullPointerException("null StackTraceElement in serial stream. ");
964 // // A null stackTrace field in the serial form can result
965 // // from an exception serialized without that field in
966 // // older JDK releases; treat such exceptions as having
967 // // empty stack traces.
968 // stackTrace = UNASSIGNED_STACK.clone();
973 * Write a {@code Throwable} object to a stream.
975 * A {@code null} stack trace field is represented in the serial
976 * form as a one-element array whose element is equal to {@code
977 * new StackTraceElement("", "", null, Integer.MIN_VALUE)}.
979 // private synchronized void writeObject(ObjectOutputStream s)
980 // throws IOException {
981 // // Ensure that the stackTrace field is initialized to a
982 // // non-null value, if appropriate. As of JDK 7, a null stack
983 // // trace field is a valid value indicating the stack trace
984 // // should not be set.
985 // getOurStackTrace();
987 // StackTraceElement[] oldStackTrace = stackTrace;
989 // if (stackTrace == null)
990 // stackTrace = SentinelHolder.STACK_TRACE_SENTINEL;
991 // s.defaultWriteObject();
993 // stackTrace = oldStackTrace;
998 * Appends the specified exception to the exceptions that were
999 * suppressed in order to deliver this exception. This method is
1000 * thread-safe and typically called (automatically and implicitly)
1001 * by the {@code try}-with-resources statement.
1003 * <p>The suppression behavior is enabled <em>unless</em> disabled
1004 * {@linkplain #Throwable(String, Throwable, boolean, boolean) via
1005 * a constructor}. When suppression is disabled, this method does
1006 * nothing other than to validate its argument.
1008 * <p>Note that when one exception {@linkplain
1009 * #initCause(Throwable) causes} another exception, the first
1010 * exception is usually caught and then the second exception is
1011 * thrown in response. In other words, there is a causal
1012 * connection between the two exceptions.
1014 * In contrast, there are situations where two independent
1015 * exceptions can be thrown in sibling code blocks, in particular
1016 * in the {@code try} block of a {@code try}-with-resources
1017 * statement and the compiler-generated {@code finally} block
1018 * which closes the resource.
1020 * In these situations, only one of the thrown exceptions can be
1021 * propagated. In the {@code try}-with-resources statement, when
1022 * there are two such exceptions, the exception originating from
1023 * the {@code try} block is propagated and the exception from the
1024 * {@code finally} block is added to the list of exceptions
1025 * suppressed by the exception from the {@code try} block. As an
1026 * exception unwinds the stack, it can accumulate multiple
1027 * suppressed exceptions.
1029 * <p>An exception may have suppressed exceptions while also being
1030 * caused by another exception. Whether or not an exception has a
1031 * cause is semantically known at the time of its creation, unlike
1032 * whether or not an exception will suppress other exceptions
1033 * which is typically only determined after an exception is
1036 * <p>Note that programmer written code is also able to take
1037 * advantage of calling this method in situations where there are
1038 * multiple sibling exceptions and only one can be propagated.
1040 * @param exception the exception to be added to the list of
1041 * suppressed exceptions
1042 * @throws IllegalArgumentException if {@code exception} is this
1043 * throwable; a throwable cannot suppress itself.
1044 * @throws NullPointerException if {@code exception} is {@code null}
1047 public final synchronized void addSuppressed(Throwable exception) {
1048 if (exception == this)
1049 throw new IllegalArgumentException(SELF_SUPPRESSION_MESSAGE);
1051 if (exception == null)
1052 throw new NullPointerException(NULL_CAUSE_MESSAGE);
1054 // if (suppressedExceptions == null) // Suppressed exceptions not recorded
1057 // if (suppressedExceptions == SUPPRESSED_SENTINEL)
1058 // suppressedExceptions = new ArrayList<Throwable>(1);
1060 // suppressedExceptions.add(exception);
1063 private static final Throwable[] EMPTY_THROWABLE_ARRAY = new Throwable[0];
1066 * Returns an array containing all of the exceptions that were
1067 * suppressed, typically by the {@code try}-with-resources
1068 * statement, in order to deliver this exception.
1070 * If no exceptions were suppressed or {@linkplain
1071 * #Throwable(String, Throwable, boolean, boolean) suppression is
1072 * disabled}, an empty array is returned. This method is
1073 * thread-safe. Writes to the returned array do not affect future
1074 * calls to this method.
1076 * @return an array containing all of the exceptions that were
1077 * suppressed to deliver this exception.
1080 public final synchronized Throwable[] getSuppressed() {
1081 return new Throwable[0];
1082 // if (suppressedExceptions == SUPPRESSED_SENTINEL ||
1083 // suppressedExceptions == null)
1084 // return EMPTY_THROWABLE_ARRAY;
1086 // return suppressedExceptions.toArray(EMPTY_THROWABLE_ARRAY);