[LANG-610] Introduced ConcurrentRuntimeException and extended the exception handling methods of ConcurrentUtils to support runtime exceptions, too.

git-svn-id: https://svn.apache.org/repos/asf/commons/proper/lang/trunk@925818 13f79535-47bb-0310-9956-ffa450edef68

src/main/java/org/apache/commons/lang3/concurrent/ConcurrentRuntimeException.java

@@ -0,0 +1,72 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.lang3.concurrent;
+
+/**
+ * <p>
+ * An exception class used for reporting runtime error conditions related to
+ * accessing data of background tasks.
+ * </p>
+ * <p>
+ * This class is an analogon of the {@link ConcurrentException} exception class.
+ * However, it is a runtime exception and thus does not need explicit catch
+ * clauses. Some methods of {@link ConcurrentUtils} throw {@code
+ * ConcurrentRuntimeException} exceptions rather than
+ * {@link ConcurrentException} exceptions. They can be used by client code that
+ * does not want to be bothered with checked exceptions.
+ * </p>
+ *
+ * @author Apache Software Foundation
+ * @version $Id$
+ */
+public class ConcurrentRuntimeException extends RuntimeException {
+    /**
+     * The serial version UID.
+     */
+    private static final long serialVersionUID = -6582182735562919670L;
+
+    /**
+     * Creates a new, uninitialized instance of {@code
+     * ConcurrentRuntimeException}.
+     */
+    protected ConcurrentRuntimeException() {
+        super();
+    }
+
+    /**
+     * Creates a new instance of {@code ConcurrentRuntimeException} and
+     * initializes it with the given cause.
+     *
+     * @param cause the cause of this exception
+     * @throws IllegalArgumentException if the cause is not a checked exception
+     */
+    public ConcurrentRuntimeException(Throwable cause) {
+        super(ConcurrentUtils.checkedException(cause));
+    }
+
+    /**
+     * Creates a new instance of {@code ConcurrentRuntimeException} and
+     * initializes it with the given message and cause.
+     *
+     * @param msg the error message
+     * @param cause the cause of this exception
+     * @throws IllegalArgumentException if the cause is not a checked exception
+     */
+    public ConcurrentRuntimeException(String msg, Throwable cause) {
+        super(msg, ConcurrentUtils.checkedException(cause));
+    }
+}

src/main/java/org/apache/commons/lang3/concurrent/ConcurrentUtils.java

@@ -65,6 +65,28 @@ public static ConcurrentException extractCause(ExecutionException ex) {
         return new ConcurrentException(ex.getMessage(), ex.getCause());
     }
 
+    /**
+     * Inspects the cause of the specified {@code ExecutionException} and
+     * creates a {@code ConcurrentRuntimeException} with the checked cause if
+     * necessary. This method works exactly like
+     * {@link #extractCause(ExecutionException)}. The only difference is that
+     * the cause of the specified {@code ExecutionException} is extracted as a
+     * runtime exception. This is an alternative for client code that does not
+     * want to deal with checked exceptions.
+     *
+     * @param ex the exception to be processed
+     * @return a {@code ConcurrentRuntimeException} with the checked cause
+     */
+    public static ConcurrentRuntimeException extractCauseUnchecked(
+            ExecutionException ex) {
+        if (ex == null || ex.getCause() == null) {
+            return null;
+        }
+
+        throwCause(ex);
+        return new ConcurrentRuntimeException(ex.getMessage(), ex.getCause());
+    }
+
     /**
      * Handles the specified {@code ExecutionException}. This method calls
      * {@link #extractCause(ExecutionException)} for obtaining the cause of the
@@ -87,6 +109,27 @@ public static void handleCause(ExecutionException ex)
         }
     }
 
+    /**
+     * Handles the specified {@code ExecutionException} and transforms it into a
+     * runtime exception. This method works exactly like
+     * {@link #handleCause(ExecutionException)}, but instead of a
+     * {@link ConcurrentException} it throws a
+     * {@link ConcurrentRuntimeException}. This is an alternative for client
+     * code that does not want to deal with checked exceptions.
+     *
+     * @param ex the exception to be handled
+     * @throws ConcurrentRuntimeException if the cause of the {@code
+     * ExecutionException} is a checked exception; this exception is then
+     * wrapped in the thrown runtime exception
+     */
+    public static void handleCauseUnchecked(ExecutionException ex) {
+        ConcurrentRuntimeException crex = extractCauseUnchecked(ex);
+
+        if (crex != null) {
+            throw crex;
+        }
+    }
+
     /**
      * Tests whether the specified {@code Throwable} is a checked exception. If
      * not, an exception is thrown.
@@ -132,7 +175,7 @@ private static void throwCause(ExecutionException ex) {
      * concurrent processing, perhaps as part of avoiding nulls.
      * A constant future can also be useful in testing.
      * </p>
-     * 
+     *
      * @param value  the constant value to return, may be null
      * @return an instance of Future that will return the value, never null
      */

src/test/java/org/apache/commons/lang3/concurrent/ConcurrentUtilsTest.java

@@ -57,6 +57,30 @@ public void testConcurrentExceptionCauseNull() {
         new ConcurrentException(null);
     }
 
+    /**
+     * Tries to create a ConcurrentRuntimeException with a runtime as cause.
+     */
+    @Test(expected = IllegalArgumentException.class)
+    public void testConcurrentRuntimeExceptionCauseUnchecked() {
+        new ConcurrentRuntimeException(new RuntimeException());
+    }
+
+    /**
+     * Tries to create a ConcurrentRuntimeException with an error as cause.
+     */
+    @Test(expected = IllegalArgumentException.class)
+    public void testConcurrentRuntimeExceptionCauseError() {
+        new ConcurrentRuntimeException("An error", new Error());
+    }
+
+    /**
+     * Tries to create a ConcurrentRuntimeException with null as cause.
+     */
+    @Test(expected = IllegalArgumentException.class)
+    public void testConcurrentRuntimeExceptionCauseNull() {
+        new ConcurrentRuntimeException(null);
+    }
+
     /**
      * Tests extractCause() for a null exception.
      */
@@ -92,7 +116,7 @@ public void testExtractCauseError() {
      * Tests extractCause() if the cause is an unchecked exception.
      */
     @Test
-    public void testExtractCauseUnchecked() {
+    public void testExtractCauseUncheckedException() {
         RuntimeException rex = new RuntimeException("Test");
         try {
             ConcurrentUtils.extractCause(new ExecutionException(rex));
@@ -113,6 +137,62 @@ public void testExtractCauseChecked() {
         assertSame("Wrong cause", ex, cex.getCause());
     }
 
+    /**
+     * Tests extractCauseUnchecked() for a null exception.
+     */
+    @Test
+    public void testExtractCauseUncheckedNull() {
+        assertNull("Non null result", ConcurrentUtils.extractCauseUnchecked(null));
+    }
+
+    /**
+     * Tests extractCauseUnchecked() if the cause of the passed in exception is null.
+     */
+    @Test
+    public void testExtractCauseUncheckedNullCause() {
+        assertNull("Non null result", ConcurrentUtils
+                .extractCauseUnchecked(new ExecutionException("Test", null)));
+    }
+
+    /**
+     * Tests extractCauseUnchecked() if the cause is an error.
+     */
+    @Test
+    public void testExtractCauseUncheckedError() {
+        Error err = new AssertionError("Test");
+        try {
+            ConcurrentUtils.extractCauseUnchecked(new ExecutionException(err));
+            fail("Error not thrown!");
+        } catch (Error e) {
+            assertEquals("Wrong error", err, e);
+        }
+    }
+
+    /**
+     * Tests extractCauseUnchecked() if the cause is an unchecked exception.
+     */
+    @Test
+    public void testExtractCauseUncheckedUncheckedException() {
+        RuntimeException rex = new RuntimeException("Test");
+        try {
+            ConcurrentUtils.extractCauseUnchecked(new ExecutionException(rex));
+            fail("Runtime exception not thrown!");
+        } catch (RuntimeException r) {
+            assertEquals("Wrong exception", rex, r);
+        }
+    }
+
+    /**
+     * Tests extractCauseUnchecked() if the cause is a checked exception.
+     */
+    @Test
+    public void testExtractCauseUncheckedChecked() {
+        Exception ex = new Exception("Test");
+        ConcurrentRuntimeException cex = ConcurrentUtils
+                .extractCauseUnchecked(new ExecutionException(ex));
+        assertSame("Wrong cause", ex, cex.getCause());
+    }
+
     /**
      * Tests handleCause() if the cause is an error.
      */
@@ -131,7 +211,7 @@ public void testHandleCauseError() throws ConcurrentException {
      * Tests handleCause() if the cause is an unchecked exception.
      */
     @Test
-    public void testHandleCauseUnchecked() throws ConcurrentException {
+    public void testHandleCauseUncheckedException() throws ConcurrentException {
         RuntimeException rex = new RuntimeException("Test");
         try {
             ConcurrentUtils.handleCause(new ExecutionException(rex));
@@ -166,6 +246,61 @@ public void testHandleCauseNull() throws ConcurrentException {
         ConcurrentUtils.handleCause(new ExecutionException("Test", null));
     }
 
+    /**
+     * Tests handleCauseUnchecked() if the cause is an error.
+     */
+    @Test
+    public void testHandleCauseUncheckedError() throws ConcurrentException {
+        Error err = new AssertionError("Test");
+        try {
+            ConcurrentUtils.handleCauseUnchecked(new ExecutionException(err));
+            fail("Error not thrown!");
+        } catch (Error e) {
+            assertEquals("Wrong error", err, e);
+        }
+    }
+
+    /**
+     * Tests handleCauseUnchecked() if the cause is an unchecked exception.
+     */
+    @Test
+    public void testHandleCauseUncheckedUncheckedException()
+            throws ConcurrentException {
+        RuntimeException rex = new RuntimeException("Test");
+        try {
+            ConcurrentUtils.handleCauseUnchecked(new ExecutionException(rex));
+            fail("Runtime exception not thrown!");
+        } catch (RuntimeException r) {
+            assertEquals("Wrong exception", rex, r);
+        }
+    }
+
+    /**
+     * Tests handleCauseUnchecked() if the cause is a checked exception.
+     */
+    @Test
+    public void testHandleCauseUncheckedChecked() {
+        Exception ex = new Exception("Test");
+        try {
+            ConcurrentUtils.handleCauseUnchecked(new ExecutionException(ex));
+            fail("ConcurrentRuntimeException not thrown!");
+        } catch (ConcurrentRuntimeException crex) {
+            assertEquals("Wrong cause", ex, crex.getCause());
+        }
+    }
+
+    /**
+     * Tests handleCauseUnchecked() for a null parameter or a null cause. In
+     * this case the method should do nothing. We can only test that no
+     * exception is thrown.
+     */
+    @Test
+    public void testHandleCauseUncheckedNull() throws ConcurrentException {
+        ConcurrentUtils.handleCauseUnchecked(null);
+        ConcurrentUtils.handleCauseUnchecked(new ExecutionException("Test",
+                null));
+    }
+
     //-----------------------------------------------------------------------
     /**
      * Tests constant future.