--- old/src/share/classes/java/lang/Throwable.java 2010-10-22 19:24:28.000000000 -0700 +++ new/src/share/classes/java/lang/Throwable.java 2010-10-22 19:24:28.000000000 -0700 @@ -1,5 +1,5 @@ /* - * Copyright (c) 1994, 2006, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 1994, 2010, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it @@ -170,6 +170,47 @@ private String detailMessage; /** + * {@linkplain #setStackTrace(StackTraceElement[] Setting the + * stack trace} to a one-element array containing this sentinel + * value indicates future attempts to set the stack trace will be + * ignored. The sentinal is equal to the result of calling:
+ * {@code new StackTraceElement("", "", null, Integer.MIN_VALUE)} + */ + public static final StackTraceElement STACK_TRACE_SENTINEL = + new StackTraceElement("", "", null, Integer.MIN_VALUE); + + /** + * A value indicating the stack trace field has not yet been initialized. + */ + private static final StackTraceElement[] EMPTY_STACK = new StackTraceElement[0]; + + /* + * To allow Throwable objects to be made immutable and safely + * reused by the JVM, such as OutOfMemoryErrors, the three fields + * of Throwable that are writable in response to user actions, + * cause, stackTrace, and suppressedExceptions obey the following + * protocol: + * + * 1) The fields are initialized to a non-null sentinel value + * which indicates the value has logically not been set. + * + * 2) Writing a null to the field indicates further writes + * are forbidden + * + * 3) The sentinel value may be replaced with another non-null + * value. + * + * For example, implementations of the HotSpot JVM have + * preallocated OutOfMemoryError objects to provide for better + * diagnosability of that situation. These objects are created + * without calling the constructor for that class and the fields + * in question are initialized to null. To support this + * capability, any new fields added to Throwable that require + * being initialized to a non-null value require a coordinated JVM + * change. + */ + + /** * The throwable that caused this throwable to get thrown, or null if this * throwable was not caused by another throwable, or if the causative * throwable is unknown. If this field is equal to this throwable itself, @@ -187,33 +228,35 @@ * @serial * @since 1.4 */ - private StackTraceElement[] stackTrace; + private StackTraceElement[] stackTrace = new StackTraceElement[0]; /* - * This field is lazily initialized on first use or serialization and - * nulled out when fillInStackTrace is called. + * This field above is lazily initialized on first use or + * serialization and nulled out when fillInStackTrace is called. */ + // Setting this static field introduces an acceptable + // initialization dependency on a few java.util classes. + private static final List suppressedSentinel = + Collections.unmodifiableList(new ArrayList(0)); + /** - * The list of suppressed exceptions, as returned by - * {@link #getSuppressedExceptions()}. + * The list of suppressed exceptions, as returned by {@link + * #getSuppressed()}. The list is initialized to a zero-element + * unmodifiable sentinel list. When a serialized Throwable is + * read in, if the {@code suppressedExceptions} field points to a + * zero-element list, the field is reset to the sentinel value. * * @serial * @since 1.7 */ - private List suppressedExceptions = null; - /* - * This field is lazily initialized when the first suppressed - * exception is added. - * - * OutOfMemoryError is preallocated in the VM for better OOM - * diagnosability during VM initialization. Constructor can't - * be not invoked. If a new field to be added in the future must - * be initialized to non-null, it requires a synchronized VM change. - */ + private List suppressedExceptions = suppressedSentinel; /** Message for trying to suppress a null exception. */ private static final String NULL_CAUSE_MESSAGE = "Cannot suppress a null exception."; + /** Message for trying to suppress oneself. */ + private static final String SELF_SUPPRESSION_MESSAGE = "Self-suppression not permitted"; + /** Caption for labeling causative exception stack traces */ private static final String CAUSE_CAPTION = "Caused by: "; @@ -572,7 +615,7 @@ s.println("\tat " + traceElement); // Print suppressed exceptions, if any - for (Throwable se : getSuppressedExceptions()) + for (Throwable se : getSuppressed()) se.printEnclosedStackTrace(s, trace, SUPPRESSED_CAPTION, "\t", dejaVu); // Print cause, if any @@ -613,7 +656,7 @@ s.println(prefix + "\t... " + framesInCommon + " more"); // Print suppressed exceptions, if any - for (Throwable se : getSuppressedExceptions()) + for (Throwable se : getSuppressed()) se.printEnclosedStackTrace(s, trace, SUPPRESSED_CAPTION, prefix +"\t", dejaVu); @@ -718,12 +761,15 @@ private synchronized StackTraceElement[] getOurStackTrace() { // Initialize stack trace if this is the first call to this method - if (stackTrace == null) { + if (stackTrace == EMPTY_STACK) { int depth = getStackTraceDepth(); stackTrace = new StackTraceElement[depth]; for (int i=0; i < depth; i++) stackTrace[i] = getStackTraceElement(i); + } else if (stackTrace == null) { + return EMPTY_STACK; } + return stackTrace; } @@ -738,6 +784,11 @@ * when a throwable is constructed or deserialized when a throwable is * read from a serialization stream. * + *

If the stack trace is set to one-element array containing + * the {@linkplain #STACK_TRACE_SENTINEL stack trace sentinel} + * value, then future calls to this method have no effect other + * than validating the argument is non-null. + * * @param stackTrace the stack trace elements to be associated with * this {@code Throwable}. The specified array is copied by this * call; changes in the specified array after the method invocation @@ -751,11 +802,21 @@ * @since 1.4 */ public void setStackTrace(StackTraceElement[] stackTrace) { + // Null-check the argument StackTraceElement[] defensiveCopy = stackTrace.clone(); - for (int i = 0; i < defensiveCopy.length; i++) - if (defensiveCopy[i] == null) - throw new NullPointerException("stackTrace[" + i + "]"); + if (stackTrace == null) + return; + + if (defensiveCopy.length == 1 && + STACK_TRACE_SENTINEL.equals(defensiveCopy[0])) + defensiveCopy = null; + else { + for (int i = 0; i < defensiveCopy.length; i++) + if (defensiveCopy[i] == null) + throw new NullPointerException("stackTrace[" + i + "]"); + } + synchronized (this) { this.stackTrace = defensiveCopy; } @@ -786,20 +847,40 @@ List suppressed = null; if (suppressedExceptions != null && !suppressedExceptions.isEmpty()) { // Copy Throwables to new list - suppressed = new ArrayList(); + suppressed = new ArrayList(1); for (Throwable t : suppressedExceptions) { + // Enforce constraints on suppressed exceptions in + // case of corrupt or malicious stream. if (t == null) throw new NullPointerException(NULL_CAUSE_MESSAGE); + if (t == this) + throw new IllegalArgumentException(SELF_SUPPRESSION_MESSAGE); suppressed.add(t); } } - suppressedExceptions = suppressed; + + // If suppressed is a zero-length list, use the sentinel + // value. + if (suppressed != null && suppressed.isEmpty()) + suppressedExceptions = suppressedSentinel; + else + suppressedExceptions = suppressed; + + // Note that there are no constraints on the value the cause + // field can hold; both null and this are valid values for the + // field. + + // Also note that a null stack trace indicates calls to + // setStackTrace do not set the stack trace. } private synchronized void writeObject(ObjectOutputStream s) - throws IOException - { - getOurStackTrace(); // Ensure that stackTrace field is initialized. + throws IOException { + // Ensure that the stackTrace field is initialized to a + // non-null value, if appropriate. As of JDK 7, a null stack + // trace field is a valid value indicating the stack trace + // should not be set. + getOurStackTrace(); s.defaultWriteObject(); } @@ -808,6 +889,14 @@ * were suppressed, typically by the {@code try}-with-resources * statement, in order to deliver this exception. * + * If the first exception to be suppressed is {@code null}, that + * indicates suppressed exception information will not be + * recorded for this exception. Subsequent calls to this method + * will not record any suppressed exceptions. Otherwise, + * attempting to suppress {@code null} after an exception has + * already been successfully suppressed results in a {@code + * NullPointerException}. + * *

Note that when one exception {@linkplain * #initCause(Throwable) causes} another exception, the first * exception is usually caught and then the second exception is @@ -819,20 +908,35 @@ * * @param exception the exception to be added to the list of * suppressed exceptions - * @throws NullPointerException if {@code exception} is null * @throws IllegalArgumentException if {@code exception} is this * throwable; a throwable cannot suppress itself. + * @throws NullPointerException if {@code exception} is null and + * an exception has already been suppressed by this exception * @since 1.7 */ - public synchronized void addSuppressedException(Throwable exception) { - if (exception == null) - throw new NullPointerException(NULL_CAUSE_MESSAGE); + public synchronized void addSuppressed(Throwable exception) { if (exception == this) - throw new IllegalArgumentException("Self-suppression not permitted"); + throw new IllegalArgumentException(SELF_SUPPRESSION_MESSAGE); - if (suppressedExceptions == null) - suppressedExceptions = new ArrayList(); - suppressedExceptions.add(exception); + if (exception == null) { + if (suppressedExceptions == suppressedSentinel) { + suppressedExceptions = null; // No suppression information recorded + return; + } else + throw new NullPointerException(NULL_CAUSE_MESSAGE); + } else { + assert exception != null && exception != this; + + if (suppressedExceptions == null) // Suppressed exceptions not recorded + return; + + if (suppressedExceptions == suppressedSentinel) + suppressedExceptions = new ArrayList(1); + + assert suppressedExceptions != suppressedSentinel; + + suppressedExceptions.add(exception); + } } private static final Throwable[] EMPTY_THROWABLE_ARRAY = new Throwable[0]; @@ -842,12 +946,15 @@ * suppressed, typically by the {@code try}-with-resources * statement, in order to deliver this exception. * + * If no exceptions were suppressed, an empty array is returned. + * * @return an array containing all of the exceptions that were * suppressed to deliver this exception. * @since 1.7 */ - public synchronized Throwable[] getSuppressedExceptions() { - if (suppressedExceptions == null) + public synchronized Throwable[] getSuppressed() { + if (suppressedExceptions == suppressedSentinel || + suppressedExceptions == null) return EMPTY_THROWABLE_ARRAY; else return suppressedExceptions.toArray(EMPTY_THROWABLE_ARRAY);