Evaluating Software Design Patterns
— the "Gang of Four" patterns implemented in Java 6

dk.rode.thesis.meta.util
Class Throwables

java.lang.Object
  extended by dk.rode.thesis.meta.util.Throwables

public class Throwables
extends Object

Utilities to manipulate throwable types and objects.

Author:
Gunni Rode / rode.dk

Constructor Summary
private Throwables()
          Private off-limit constructor.
 
Method Summary
static List<Throwable> getCauses(Throwable throwable)
          Returns a list containing the throwable cause chain acquired from throwable.
static List<Exception> getCheckedExceptions(Collection<?> objects)
          Returns a list containing the checked exceptions from objects.
static List<Exception> getCheckedExceptions(Object... objects)
          Returns a list containing the checked exceptions from objects.
static List<Class<? extends Exception>> getCheckedExceptionTypes(Class<?>... types)
          Returns a list containing the checked exception types from types.
static List<Class<? extends Exception>> getCheckedExceptionTypes(Collection<Class<?>> types)
          Returns a list containing the checked exception types from types.
static int getIndex(StackTraceElement[] trace, CharSequence... tokens)
          Returns the last index + 1 in the supplied stack trace where one of the supplied tokens is found.
static List<Throwable> getUncheckedThrowables(Collection<?> objects)
          Returns a list containing the unchecked throwables from objects.
static List<Throwable> getUncheckedThrowables(Object... objects)
          Returns a list containing the unchecked throwables from objects.
static List<Class<? extends Throwable>> getUncheckedThrowableTypes(Class<?>... types)
          Returns a list containing the unchecked throwable types from types.
static List<Class<? extends Throwable>> getUncheckedThrowableTypes(Collection<Class<?>> types)
          Returns a list containing the unchecked throwable types from types.
static boolean isChecked(Throwable throwable)
          Returns true if throwable is a checked exception, false if not.
static Exception toCheckedException(Throwable throwable)
          Returns a checked exception based on throwable.
static Exception toCheckedException(Throwable throwable, boolean unwind)
          Returns a checked exception based on throwable.
static
<T extends Exception>
T
toCheckedException(Throwable throwable, Class<T> type)
          Returns a checked exception of the type supplied as type based on throwable.
static
<T extends Exception>
T
toCheckedException(Throwable throwable, Class<T> type, boolean unwind)
          Returns a checked exception of the type supplied as type based on throwable.
static RuntimeException toRuntimeException(Throwable throwable)
          Returns a runtime exception based on throwable.
static RuntimeException toRuntimeException(Throwable throwable, boolean unwind)
          Returns a runtime exception based on throwable.
static
<T extends RuntimeException>
T
toRuntimeException(Throwable throwable, Class<T> type)
          Returns a runtime exception of the type supplied as type based on throwable.
static
<T extends RuntimeException>
T
toRuntimeException(Throwable throwable, Class<T> type, boolean unwind)
          Returns a runtime exception of the type supplied as type based on throwable.
static CharSequence toStackTrace(Throwable throwable)
          Serializes the stack trace from throwable into the returned char sequence.
static
<T extends Throwable>
T
toThrowableType(Throwable throwable, Class<T> type)
          Returns a throwable of the type supplied as type based on throwable.
static
<T extends Throwable>
T
toThrowableType(Throwable throwable, Class<T> type, boolean unwind)
          Returns a throwable of the type supplied as type based on throwable.
static
<T extends Throwable>
T
unwind(Throwable throwable, Class<T> type)
          Returns the first throwable assignable to type in the cause chain acquired from throwable, if any.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Throwables

private Throwables()
Private off-limit constructor.

Method Detail

getCauses

public static final List<Throwable> getCauses(Throwable throwable)
Returns a list containing the throwable cause chain acquired from throwable.

The first index contains throwable, the second index the cause A of throwable, the third the cause B of A, etc.

Parameters:
throwable - The throwable to supply the cause chain; cannot be null.
Returns:
The list containing the cause chain; never null, and never empty.
Throws:
NullPointerException - If throwable is null.

getCheckedExceptions

public static final List<Exception> getCheckedExceptions(Collection<?> objects)
Returns a list containing the checked exceptions from objects.

The returned list may contain duplicates.

Parameters:
objects - The objects; cannot be null, but may contain null entries.
Returns:
A list containing the checked exceptions from objects; never null.
Throws:
NullPointerException - If objects is null.

getCheckedExceptions

public static final List<Exception> getCheckedExceptions(Object... objects)
Returns a list containing the checked exceptions from objects.

The returned list may contain duplicates.

Parameters:
objects - The objects; cannot be null, but may contain null entries.
Returns:
A list containing the checked exceptions from objects; never null.
Throws:
NullPointerException - If objects is null.

getCheckedExceptionTypes

public static final List<Class<? extends Exception>> getCheckedExceptionTypes(Class<?>... types)
Returns a list containing the checked exception types from types.

The returned list may contain duplicates.

Parameters:
types - The types; cannot be null, but may contain null entries.
Returns:
A list containing the checked exception types from types; never null.
Throws:
NullPointerException - If types is null.

getCheckedExceptionTypes

public static final List<Class<? extends Exception>> getCheckedExceptionTypes(Collection<Class<?>> types)
Returns a list containing the checked exception types from types.

The returned list may contain duplicates.

Parameters:
types - The types; cannot be null, but may contain null entries.
Returns:
A list containing the checked exception types from types; never null.
Throws:
NullPointerException - If types is null.

getIndex

public static final int getIndex(StackTraceElement[] trace,
                                 CharSequence... tokens)
Returns the last index + 1 in the supplied stack trace where one of the supplied tokens is found.

The search for a token is done in the class name available via a stack trace element using Strings.indexOfIgnoreCase(CharSequence, CharSequence). Hence, the search is case-insensitive, and the search for tokens is done in the order the tokens are supplied.

Parameters:
trace - The stack trace; cannot be null.
tokens - The list of tokens to search for.
Returns:
The index of the first token found, or trace.length if no token could be found.
Throws:
NullPointerException - If trace is null.

getUncheckedThrowables

public static final List<Throwable> getUncheckedThrowables(Collection<?> objects)
Returns a list containing the unchecked throwables from objects.

The returned list may contain duplicates.

Parameters:
objects - The objects; cannot be null, but may contain null entries.
Returns:
A list containing the unchecked throwable types from objects; never null.
Throws:
NullPointerException - If objects is null.

getUncheckedThrowables

public static final List<Throwable> getUncheckedThrowables(Object... objects)
Returns a list containing the unchecked throwables from objects.

The returned list may contain duplicates.

Parameters:
objects - The objects; cannot be null, but may contain null entries.
Returns:
A list containing the unchecked throwable types from objects; never null.
Throws:
NullPointerException - If objects is null.

getUncheckedThrowableTypes

public static final List<Class<? extends Throwable>> getUncheckedThrowableTypes(Class<?>... types)
Returns a list containing the unchecked throwable types from types.

The returned list may contain duplicates.

Parameters:
types - The types; cannot be null, but may contain null entries.
Returns:
A list containing the unchecked throwable types from types; never null.
Throws:
NullPointerException - If types is null.

getUncheckedThrowableTypes

public static final List<Class<? extends Throwable>> getUncheckedThrowableTypes(Collection<Class<?>> types)
Returns a list containing the unchecked throwable types from types.

The returned list may contain duplicates.

Parameters:
types - The types; cannot be null, but may contain null entries.
Returns:
A list containing the unchecked throwable types from types; never null.
Throws:
NullPointerException - If types is null.

isChecked

public static final boolean isChecked(Throwable throwable)
Returns true if throwable is a checked exception, false if not.

Parameters:
throwable - The throwable to test; can be null, in which case false is returned.
Returns:
True if throwable is a checked exception, false if not.

toCheckedException

public static final Exception toCheckedException(Throwable throwable)
Returns a checked exception based on throwable.

If throwable is already a checked exception, it will simply be returned. Otherwise a new checked exception is created, throwable is set as the cause, and the created checked exception is returned.

Parameters:
throwable - The throwable; cannot be null.
Returns:
A checked exception; never null.
Throws:
NullPointerException - If throwable is null.

toCheckedException

public static final Exception toCheckedException(Throwable throwable,
                                                 boolean unwind)
Returns a checked exception based on throwable.

If throwable is already a checked exception, it will simply be returned. If not and if unwind is true, a checked exception is tried unwound from the cause chain acquired from throwable and if found returned. Otherwise a new checked exception is created, throwable is set as the cause, and the created checked exception is returned.

Parameters:
throwable - The throwable; cannot be null.
unwind - True to try and unwind a checked exception from cause chain, false to create a new checked exception if needed (a new instance will also be created if no checked exception can be found in the cause chain).
Returns:
A checked exception; never null.
Throws:
NullPointerException - If throwable is null.

toCheckedException

public static final <T extends Exception> T toCheckedException(Throwable throwable,
                                                               Class<T> type)
Returns a checked exception of the type supplied as type based on throwable.

If throwable is already a checked exception of the desired type, it will simply be returned. Otherwise a new checked exception of the desired type is created, throwable is set as the cause, and the created checked exception is returned.

Type Parameters:
T - The type of throwable.
Parameters:
throwable - The throwable; cannot be null.
type - The specific checked exception type as a class token; cannot be null.
Returns:
A checked exception having the desired type; never null.
Throws:
NullPointerException - If either parameter is null.
RuntimeException - If the current context to does have access to create a checked exception of the desired type; or if the desired type does not have a default constructor, or the construction fails.

toCheckedException

public static final <T extends Exception> T toCheckedException(Throwable throwable,
                                                               Class<T> type,
                                                               boolean unwind)
Returns a checked exception of the type supplied as type based on throwable.

If throwable is already a checked exception of the desired type, it will simply be returned. If not and if unwind is true, a checked exception of the desired type is tried unwound from the cause chain acquired from throwable and if found returned. Otherwise a new checked exception of the desired type is created, throwable is set as the cause, and the created checked exception is returned.

Type Parameters:
T - The type of throwable.
Parameters:
throwable - The throwable; cannot be null.
type - The specific runtime exception type as a class token; cannot be null.
unwind - True to try and unwind a checked exception of the desired type from cause chain, false to create such a new checked exception if needed (a new instance will also be created if no such checked exception can be found in the cause chain).
Returns:
A checked exception having the desired type; never null.
Throws:
NullPointerException - If either parameter is null.
RuntimeException - If the current context to does have access to create a checked exception of the desired type; or if the desired type does not have a default constructor, or the construction fails.

toRuntimeException

public static final RuntimeException toRuntimeException(Throwable throwable)
Returns a runtime exception based on throwable.

If throwable is already a runtime exception, it will simply be returned. Otherwise a new runtime exception is created, throwable is set as the cause, and the created runtime exception is returned.

Parameters:
throwable - The throwable; cannot be null.
Returns:
A runtime exception; never null.
Throws:
NullPointerException - If throwable is null.

toRuntimeException

public static final RuntimeException toRuntimeException(Throwable throwable,
                                                        boolean unwind)
Returns a runtime exception based on throwable.

If throwable is already a runtime exception, it will simply be returned. If not and if unwind is true, a runtime exception is tried unwound from the cause chain acquired from throwable and if found returned. Otherwise a new runtime exception is created, throwable is set as the cause, and the created runtime exception is returned.

Parameters:
throwable - The throwable; cannot be null.
unwind - True to try and unwind a runtime exception from cause chain, false to create a new runtime exception if needed (a new instance will also be created if no runtime exception can be found in the cause chain).
Returns:
A runtime exception; never null.
Throws:
NullPointerException - If throwable is null.

toRuntimeException

public static final <T extends RuntimeException> T toRuntimeException(Throwable throwable,
                                                                      Class<T> type)
Returns a runtime exception of the type supplied as type based on throwable.

If throwable is already a runtime exception of the desired type, it will simply be returned. Otherwise a new runtime exception of the desired type is created, throwable is set as the cause, and the created runtime exception is returned.

Type Parameters:
T - The type of throwable.
Parameters:
throwable - The throwable; cannot be null.
type - The specific runtime exception type as a class token; cannot be null.
Returns:
A runtime exception having the desired type; never null.
Throws:
NullPointerException - If either parameter is null.
RuntimeException - If the current context to does have access to create a runtime exception of the desired type; or if the desired type does not have a default constructor, or the construction fails.

toRuntimeException

public static final <T extends RuntimeException> T toRuntimeException(Throwable throwable,
                                                                      Class<T> type,
                                                                      boolean unwind)
Returns a runtime exception of the type supplied as type based on throwable.

If throwable is already a runtime exception of the desired type, it will simply be returned. If not and if unwind is true, a runtime exception of the desired type is tried unwound from the cause chain acquired from throwable and if found returned. Otherwise a new runtime exception of the desired type is created, throwable is set as the cause, and the created runtime exception is returned.

Type Parameters:
T - The type of throwable.
Parameters:
throwable - The throwable; cannot be null.
type - The specific runtime exception type as a class token; cannot be null.
unwind - True to try and unwind a runtime exception of the desired type from cause chain, false to create such a new runtime exception if needed (a new instance will also be created if no such runtime exception can be found in the cause chain).
Returns:
A runtime exception having the desired type; never null.
Throws:
NullPointerException - If either parameter is null.
RuntimeException - If the current context to does have access to create a runtime exception of the desired type; or if the desired type does not have a default constructor, or the construction fails.

toStackTrace

public static final CharSequence toStackTrace(Throwable throwable)
Serializes the stack trace from throwable into the returned char sequence.

Instead of writing to, for example, System.err, the same output is simply written to the returned char sequence, including newlines.

Parameters:
throwable - The throwable; cannot be null.
Returns:
A char sequence containing the serialized stack trace from throwable; never null.
Throws:
NullPointerException - If throwable is null.

toThrowableType

public static final <T extends Throwable> T toThrowableType(Throwable throwable,
                                                            Class<T> type)
Returns a throwable of the type supplied as type based on throwable.

If throwable is already an instance of the desired type, it will simply be returned. Otherwise a new throwable of the desired type is created, throwable is set as the cause, and the created throwable is returned.

This method can be used as a simple idiom for re-throwing the correct type of exception if the exception cannot be handled, without having to use several different catch-blocks to avoid hiding the actual exception type.

Consider:

 public foo() throws FooException {
   try {
     ..
 
   } catch (FooException fe) {
     throw fe;
   } catch (Exception e) {
     throw new FooException(e);
   }
 }
 
Using this method instead:
 public foo() throws FooException {
   try {
     ..
 
   } catch (Exception e) {
     throw toThrowableType(e, FooException.class);
   }
 }
 

Type Parameters:
T - The type of throwable.
Parameters:
throwable - The throwable; cannot be null.
type - The specific type as a class token; cannot be null.
Returns:
A throwable having the desired type; never null.
Throws:
NullPointerException - If either parameter is null.
RuntimeException - If the current context does not have access to create a throwable exception of the desired type; or if the desired type does not have a no-arg constructor, or the construction fails.
See Also:
toThrowableType(Throwable, Class, boolean)

toThrowableType

public static final <T extends Throwable> T toThrowableType(Throwable throwable,
                                                            Class<T> type,
                                                            boolean unwind)
Returns a throwable of the type supplied as type based on throwable.

If throwable is already an instance of the desired type, it will simply be returned. If not and if unwind is true, a throwable of the desired type is tried unwound from the cause chain acquired from throwable and if found returned. Otherwise a new throwable of the desired type is created, throwable is set as the cause, and the created throwable is returned.

This method can be used as a simple idiom for re-throwing the correct type of exception if the exception cannot be handled, without having to use several different catch-blocks to avoid hiding the actual exception type.

Consider:

 public foo() throws FooException {
   try {
     ..
 
   } catch (FooException fe) {
     throw fe;
   } catch (Exception e) {
     throw new FooException(e);
   }
 }
 
Using this method instead:
 public foo() throws FooException {
   try {
     ..
 
   } catch (Exception e) {
     throw toThrowableType(e, FooException.class, true); // true = try and unwind
   }
 }
 

Type Parameters:
T - The type of throwable.
Parameters:
throwable - The throwable; cannot be null.
type - The specific type as a class token; cannot be null.
unwind - True to try and unwind a throwable of type T from cause chain, false to create a new throwable if needed (a new instance will also be created if no such type can be found in the cause chain).
Returns:
A throwable having the desired type; never null.
Throws:
NullPointerException - If throwable or type are null.
RuntimeException - If a throwable must be created and the current context does not have access to create a throwable exception of the desired type; or if the desired type does not have a no-arg constructor, or the construction fails.
See Also:
toThrowableType(Throwable, Class)

unwind

public static final <T extends Throwable> T unwind(Throwable throwable,
                                                   Class<T> type)
Returns the first throwable assignable to type in the cause chain acquired from throwable, if any.

The returned throwable may be throwable it self.

Type Parameters:
T - The type of throwable to find in the cause stack.
Parameters:
throwable - The throwable to supply the cause chain; cannot be null.
type - The type as a class token; cannot be null.
Returns:
The first throwable assignable to type, or null if no such throwable is found.
Throws:
NullPointerException - If either argument is null.

Gunni Rode / rode.dk

Feel free to use and/or modify the Java 6 source code developed for this thesis AT YOUR OWN RISK, but note that the source code comes WITHOUT ANY — and I do mean WITHOUT ANY — form of warranty WHAT SO EVER!

The original thesis and source code are available at rode.dk/thesis.