--- old/jdk/src/share/classes/java/lang/Throwable.java 2010-10-14 00:10:38.000000000 -0700 +++ new/jdk/src/share/classes/java/lang/Throwable.java 2010-10-14 00:10:38.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 @@ -169,6 +169,31 @@ */ private String detailMessage; + /* + * 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 and initialized to a non-null sentinel value + * + * 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 @@ -189,31 +214,30 @@ */ private StackTraceElement[] stackTrace; /* - * 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()}. + * {@link #getSuppressed()}. * * @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 +596,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 +637,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); @@ -786,14 +810,28 @@ 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. } private synchronized void writeObject(ObjectOutputStream s) @@ -808,6 +846,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 +865,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 (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 == null) - suppressedExceptions = new ArrayList(); - suppressedExceptions.add(exception); + 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 +903,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);