Bug 1213: Expose InterruptSource, SourcedInterruptedException and InterruptedRuntimeException

- InterruptSource interface declares methods to retrieve
  the source of a Thread.interrupt() call.

- InterruptSource.Thread implements InterruptSource,
  i.e. allows code running within such thread to learn about
  the interrupt source (stack trace).

- SourcedInterruptedException is a InterruptedException specialization
  which may include the source of the causing Thread.interrupt() call.

- InterruptedRuntimeException
  An unchecked RuntimeException propagating an InterruptedException
  where handling of the latter is not desired.
  The causing InterruptedException may be of type SourcedInterruptedException,
  hence a detailed stack trace analysis might be possible.

1 files changed, 165 insertions, 0 deletions

diff --git a/src/java/com/jogamp/common/util/SourcedInterruptedException.java b/src/java/com/jogamp/common/util/SourcedInterruptedException.java
new file mode 100644
index 0000000..7646652
--- /dev/null
+++ b/src/java/com/jogamp/common/util/SourcedInterruptedException.java
@@ -0,0 +1,165 @@
+/**
+ * Copyright 2015 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+
+package com.jogamp.common.util;
+
+import java.io.PrintStream;
+
+import com.jogamp.common.ExceptionUtils;
+import com.jogamp.common.ExceptionUtils.CustomStackTrace;
+
+/**
+ * {@link InterruptedException}, which may include the source, see {@link #getInterruptSource()}.
+ * <p>
+ * This exception may be created directly where {@link #getCause()} returns {@code null},
+ * or by propagating an existing {@link InterruptedException} as returned by {@link #getCause()}.
+ * </p>
+ */
+@SuppressWarnings("serial")
+public class SourcedInterruptedException extends InterruptedException implements CustomStackTrace {
+    final Throwable interruptSource;
+
+    /**
+     * Wraps the given {@link InterruptedException} into a {@link SourcedInterruptedException}
+     * if it is not yet of the desired type and
+     * if the current thread if a {@link InterruptSource}, i.e. the source is known.
+     * <p>
+     * Otherwise the given {@link InterruptedException} instance is returned.
+     * </p>
+     * <p>
+     * In case method is creating a new wrapping instance,
+     * {@link InterruptSource#clearInterruptSource()} is being issued.
+     * </p>
+     *
+     * @param ie the to be wrapped {@link InterruptedException}
+     */
+    public static InterruptedException wrap(final InterruptedException ie) {
+        return wrap(ie, InterruptSource.Util.currentThread());
+    }
+
+    /**
+     * Wraps the given {@link InterruptedException} into a {@link SourcedInterruptedException}
+     * if it is not yet of the same type and if {@code source} is not {@code null}.
+     * <p>
+     * Otherwise the given {@link InterruptedException} instance is returned.
+     * </p>
+     * <p>
+     * In case method is creating a new wrapping instance,
+     * {@link InterruptSource#clearInterruptSource()} is being issued.
+     * </p>
+     *
+     * @param ie the to be wrapped {@link InterruptedException}
+     * @param source the {@link InterruptSource}
+     */
+    public static InterruptedException wrap(final InterruptedException ie, final InterruptSource source) {
+        if( !(ie instanceof SourcedInterruptedException) && null != source ) {
+            return new SourcedInterruptedException(ie, source.getInterruptSource(true));
+        } else {
+            return ie;
+        }
+    }
+
+    /**
+     * @param message mandatory message of this exception
+     * @param cause optional propagated cause
+     * @param interruptSource optional propagated source of {@link Thread#interrupt()} call
+     */
+    public SourcedInterruptedException(final String message, final InterruptedException cause, final Throwable interruptSource) {
+        super(message);
+        if( null != cause ) {
+            initCause(cause);
+        }
+        this.interruptSource = interruptSource;
+    }
+
+    /**
+     * @param cause mandatory propagated cause
+     * @param interruptSource optional propagated source of {@link Thread#interrupt()} call
+     */
+    public SourcedInterruptedException(final InterruptedException cause, final Throwable interruptSource) {
+        super(cause.getMessage());
+        initCause(cause);
+        this.interruptSource = interruptSource;
+    }
+
+    /**
+     * Returns the source of the {@link Thread#interrupt()} call if known,
+     * otherwise {@code null} is returned.
+     */
+    public final Throwable getInterruptSource() {
+        return interruptSource;
+    }
+
+    /**
+     * Returns the propagated {@link InterruptedException}, i.e. the cause of this exception,
+     * or {@code null} if not applicable.
+     * <p>
+     * {@inheritDoc}
+     * </p>
+     */
+    @Override
+    public InterruptedException getCause() {
+        return (InterruptedException)super.getCause();
+    }
+
+    @Override
+    public String toString() {
+        final StringBuilder sb = new StringBuilder(256);
+        sb.append(getClass().getSimpleName()).append(": ");
+        if (null != interruptSource) {
+            sb.append("[sourced]");
+        } else {
+            sb.append("[unknown]");
+        }
+        final String m = getLocalizedMessage();
+        if( null != m ) {
+            sb.append(" ").append(m);
+        }
+        return sb.toString();
+    }
+
+    @Override
+    public final void dumpCauseStack(final PrintStream s, final String causeStr, final int causeDepth) {
+        final String s0 = causeStr+"["+causeDepth+"]";
+        s.println(s0+" by "+getClass().getSimpleName()+": "+getMessage()+" on thread "+Thread.currentThread().getName());
+        ExceptionUtils.dumpStack(s, getStackTrace(), 0, -1);
+        if( null != interruptSource ) {
+            ExceptionUtils.dumpCause(s, s0, interruptSource, 1);
+        }
+    }
+
+    @Override
+    public final void printStackTrace(final PrintStream s) {
+        s.println(getClass().getSimpleName()+": "+getMessage()+" on thread "+Thread.currentThread().getName());
+        ExceptionUtils.dumpStack(s, getStackTrace(), 0, -1);
+        final int causeDepth = ExceptionUtils.dumpCause(s, "Caused", getCause(), 1);
+        if( null != interruptSource ) {
+            ExceptionUtils.dumpCause(s, "InterruptSource", interruptSource, causeDepth);
+        }
+    }
+}