com.googlecode.catchexception.throwable

Class CatchThrowable

java.lang.Object

com.googlecode.catchexception.throwable.CatchThrowable

public class CatchThrowable
extends Object

Since:

1.2.0

Author:

rwoo

Constructor Summary

Constructors

Constructor and Description
CatchThrowable()

Method Summary

Methods

Modifier and Type	Method and Description
static <T> T	catchThrowable(T obj) Use it to catch an throwable and to get access to the thrown throwable (for further verifications).
static <T,E extends Throwable> T	catchThrowable(T obj, Class<E> clazz) Use it to catch an throwable of a specific type and to get access to the thrown throwable (for further verifications).
static <E extends Throwable> E	caughtThrowable() Returns the throwable caught during the last call on the proxied object in the current thread.
static <T> T	interfaces(T obj) Returns a proxy that implements all interfaces of the underlying object.
private static <T,E extends Throwable> T	processThrowable(T obj, Class<E> throwableClazz, boolean assertThrowable) Creates a proxy that processes throwables thrown by the underlying object.
static void	resetCaughtThrowable() Sets the caught throwable to null.
static <T> T	verifyThrowable(T obj) Use it to verify that an throwable is thrown and to get access to the thrown throwable (for further verifications).
static <T,E extends Throwable> T	verifyThrowable(T obj, Class<E> clazz) Use it to verify that an throwable of specific type is thrown and to get access to the thrown throwable (for further verifications).

Methods inherited from class java.lang.Object

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

Constructor Detail

CatchThrowable

public CatchThrowable()

Method Detail

caughtThrowable

public static <E extends Throwable> E caughtThrowable()

Returns the throwable caught during the last call on the proxied object in the current thread.

Type Parameters:

E - This type parameter makes some type casts redundant.

Returns:

Returns the throwable caught during the last call on the proxied object in the current thread - if the call was made through a proxy that has been created via verifyThrowable() or catchThrowable(). Returns null the proxy has not caught an throwable. Returns null if the caught throwable belongs to a class that is no longer loaded.

verifyThrowable

public static <T> T verifyThrowable(T obj)

Use it to verify that an throwable is thrown and to get access to the thrown throwable (for further verifications).

The following example verifies that obj.doX() throws a Throwable:

verifyThrowable(obj).doX(); // catch and verify
assert "foobar".equals(caughtThrowable().getMessage()); // further analysis

If doX() does not throw a Throwable, then a ThrowableNotThrownAssertionError is thrown. Otherwise the thrown throwable can be retrieved via caughtThrowable().

Type Parameters:

T - The type of the given obj.

Parameters:

obj - The instance that shall be proxied. Must not be null.

Returns:

Returns an object that verifies that each invocation on the underlying object throws an throwable.

verifyThrowable

public static <T,E extends Throwable> T verifyThrowable(T obj,
                                        Class<E> clazz)

Use it to verify that an throwable of specific type is thrown and to get access to the thrown throwable (for further verifications).

The following example verifies that obj.doX() throws a MyThrowable:

verifyThrowable(obj, MyThrowable.class).doX(); // catch and verify
assert "foobar".equals(caughtThrowable().getMessage()); // further analysis

If doX() does not throw a MyThrowable, then a ThrowableNotThrownAssertionError is thrown. Otherwise the thrown throwable can be retrieved via caughtThrowable().

Type Parameters:

T - The type of the given obj.

E - The type of the throwable that shall be caught.

Parameters:

obj - The instance that shall be proxied. Must not be null.

clazz - The type of the throwable that shall be thrown by the underlying object. Must not be null .

Returns:

Returns an object that verifies that each invocation on the underlying object throws an throwable of the given type.

catchThrowable

public static <T> T catchThrowable(T obj)

Use it to catch an throwable and to get access to the thrown throwable (for further verifications).

In the following example you catch throwables that are thrown by obj.doX():

catchThrowable(obj).doX(); // catch
if (caughtThrowable() != null) {
    assert "foobar".equals(caughtThrowable().getMessage()); // further analysis
}

If doX() throws a throwable, then caughtThrowable() will return the caught throwable. If doX() does not throw a throwable, then caughtThrowable() will return null.

Type Parameters:

T - The type of the given obj.

Parameters:

obj - The instance that shall be proxied. Must not be null.

Returns:

Returns a proxy for the given object. The proxy catches throwables of the given type when a method on the proxy is called.

catchThrowable

public static <T,E extends Throwable> T catchThrowable(T obj,
                                       Class<E> clazz)

Use it to catch an throwable of a specific type and to get access to the thrown throwable (for further verifications).

In the following example you catch throwables of type MyThrowable that are thrown by obj.doX():

catchThrowable(obj, MyThrowable.class).doX(); // catch
if (caughtThrowable() != null) {
    assert "foobar".equals(caughtThrowable().getMessage()); // further analysis
}

If doX() throws a MyThrowable, then caughtThrowable() will return the caught throwable. If doX() does not throw a MyThrowable, then caughtThrowable() will return null. If doX() throws an throwable of another type, i.e. not a subclass but another class, then this throwable is not thrown and caughtThrowable() will return null.

Type Parameters:

T - The type of the given obj.

E - The type of the throwable that shall be caught.

Parameters:

obj - The instance that shall be proxied. Must not be null.

clazz - The type of the throwable that shall be caught. Must not be null.

Returns:

Returns a proxy for the given object. The proxy catches throwables of the given type when a method on the proxy is called.

processThrowable

private static <T,E extends Throwable> T processThrowable(T obj,
                                         Class<E> throwableClazz,
                                         boolean assertThrowable)

Creates a proxy that processes throwables thrown by the underlying object.

Delegates to SubclassProxyFactory.createProxy(Class, MethodInterceptor) which itself might delegate to InterfaceOnlyProxyFactory.createProxy(Class, MethodInterceptor).

interfaces

public static <T> T interfaces(T obj)

Returns a proxy that implements all interfaces of the underlying object.

Type Parameters:

T - must be an interface the object implements

Parameters:

obj - the object that created proxy will delegate all calls to

Returns:

Returns a proxy that implements all interfaces of the underlying object and delegates all calls to that underlying object.

resetCaughtThrowable

public static void resetCaughtThrowable()

Sets the caught throwable to null. This does not affect throwables saved at threads other than the current one.

Actually you probably never need to call this method because each method call on a proxied object in the current thread resets the caught throwable. But if you want to improve test isolation or if you want to 'clean up' after testing (to avoid memory leaks), call the method before or after testing.