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);