de.unkrig.commons.lang

Class ExceptionUtil

java.lang.Object

de.unkrig.commons.lang.ExceptionUtil

public final class ExceptionUtil
extends java.lang.Object

Various Exception-related utility methods.

Method Summary

Modifier and Type	Method and Description
static <T,EX extends java.lang.Throwable> T	throW(EX throwable) Identical with "throw throwable", but has a return type T, so it can be used in an expression.
static <T> T	throwAssertionError(java.lang.Object object) Identical with "throw new AssertionError(object)", but has a return type T, so it can be used in an expression.
static void	throwUndeclared(java.lang.Exception e) Throws the given Exception, although it does not declare any exceptions.
static <T extends java.lang.Throwable> T	wrap(java.lang.String prefix, T cause) Wraps a given 'cause' in another throwable of the same type, with a detail message composed from prefix, a colon, a space, and the cause.
static <T extends java.lang.Throwable> T	wrap(java.lang.String prefix, java.lang.Throwable cause, java.lang.Class<T> wrapperClass) Wraps a given 'cause' in another throwable of the given wrapper class type, with a detail message composed from prefix, a colon, a space, and the cause.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

wrap

public static <T extends java.lang.Throwable> T wrap(@Nullable
                                                     java.lang.String prefix,
                                                     T cause)

Wraps a given 'cause' in another throwable of the same type, with a detail message composed from prefix, a colon, a space, and the cause.

This is useful for adding context information to a throwable, e.g. which file is currently being processed, the current line number, etc.

Parameters:

prefix - The text to prepend to the cause throwable's detail message

cause - The throwable to wrap

Returns:

The wrapping throwable

wrap

public static <T extends java.lang.Throwable> T wrap(@Nullable
                                                     java.lang.String prefix,
                                                     java.lang.Throwable cause,
                                                     java.lang.Class<T> wrapperClass)

Wraps a given 'cause' in another throwable of the given wrapper class type, with a detail message composed from prefix, a colon, a space, and the cause.

Parameters:

prefix - The text to prepend to the cause throwable's detail message

cause - The throwable to wrap

wrapperClass - The type of the wrapping throwable

Returns:

The wrapping throwable

throwUndeclared

public static void throwUndeclared(java.lang.Exception e)

Throws the given Exception, although it does not declare any exceptions.

This feature exploits the fact that the per-method declaration of thrown exceptions (the THROWS clause) is a compiler feature and not a runtime feature, and can be circumvented with some trickery.

This is useful e.g. for implementations of Iterator, Runnable and other "service classes" that want to throw checked exceptions. (Wrapping these in RuntimeExceptions is sometimes not an option.)

Notice that the only way to catch such undeclared checked exceptions is "try { ... } catch (Exception e) { ... }".

Notice that this method breaks Java's concept of exception checking entirely. It also renders the exception-type-parametrized interfaces *WhichThrows (e.g. RunnableWhichThrows) useless. One should use one or the other, but never both.

Usage example:

 import static de.unkrig.commons.lang.ExceptionUtil.throwUndeclared;

 class MyIterator<E> implements Iterator<E> {

     public E next() {
         // ...
         throwUndeclared(new IOException());
     }

     // ...
 }

Parameters:

e - The exception to be thrown

throW

public static <T,EX extends java.lang.Throwable> T throW(EX throwable)
                                                  throws EX extends java.lang.Throwable

Identical with "throw throwable", but has a return type T, so it can be used in an expression.

Throws:

EX extends java.lang.Throwable

throwAssertionError

public static <T> T throwAssertionError(java.lang.Object object)

Identical with "throw new AssertionError(object)", but has a return type T, so it can be used in an expression.