de.team33.patterns.exceptional.dione

Class Revision<T extends Throwable>

java.lang.Object

de.team33.patterns.exceptional.dione.Revision<T>

public final class Revision<T extends Throwable>
extends Object

A tool that supports a revision and handling of an exception.

In general, there is little need for a special tool for differentiated handling of exceptions. The possibilities of Java’s own language elements (try-catch) are compact, expressive and efficient.

The situation is different if the cause of an exception is to be handled in a differentiated manner. This often results in extensive and sometimes difficult to read code. In any case, the regular code takes a back seat.

For example, in order not to have to deal with it all the time, we would like to temporarily wrap checked exceptions into unchecked exceptions. However, we would then like to bring the checked exceptions back to the fore in order to enforce a structured approach. A Revision supports the latter, as the following code example shows:

         try {
             return somethingThatMayCauseAWrappedException();
         } catch (final WrappedException caught) {
             throw Revision.of(caught.getCause())
                           .reThrow(IOException.class)
                           .reThrow(SQLException.class)
                           .reThrow(URISyntaxException.class)
                           .close(ExpectationException::new);
         }
 

See Also:

of(Throwable), reThrow(Class), close(Function)

Method Summary

Modifier and Type	Method and Description
T	close() Completes this revision and returns the associated exception unchanged.
<R> R	close(Function<? super T,R> mapping) Completes this revision, applies a given mapping to the associated exception, and returns its result.
static <T extends Throwable> Revision<T>	of(T subject) Returns a new instance to review and handle a given exception.
<X extends Throwable> Revision<T>	reThrow(Class<X> xClass) Rethrows the associated exception if it matches the given exception type.
<R,X extends Throwable> R	reThrow(Class<X> xClass, R result) Rethrows the associated exception if it matches the given exception type, otherwise a given result will be returned.
<X extends Throwable> Revision<T>	throwIf(Predicate<? super T> condition, Function<? super T,X> mapping) Applies a given mapping to the associated exception if the given condition applies and throws the result, otherwise this Revision will be returned.
<R,X extends Throwable> R	throwIf(Predicate<? super T> condition, Function<? super T,X> mapping, R result) Applies a given mapping to the associated exception if the given condition applies and throws the result, otherwise a given result will be returned.

Methods inherited from class java.lang.Object

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

Method Detail

of

public static <T extends Throwable> Revision<T> of(T subject)

Returns a new instance to review and handle a given exception.

Type Parameters:

T - the type of the given exception

Parameters:

subject - the exception to be handled

throwIf

public final <X extends Throwable> Revision<T> throwIf(Predicate<? super T> condition,
                                                       Function<? super T,X> mapping)
                                                throws X extends Throwable

Applies a given mapping to the associated exception if the given condition applies and throws the result, otherwise this Revision will be returned.

Type Parameters:

X - The exception type that is intended as a result of the given mapping and that is thrown by this method, if applicable.

Parameters:

condition - A Predicate that is used to check the associated exception for applicability.

mapping - A Function that converts the associated exception to a specific type of exception to be thrown at that point.

Returns:

This Revision, which can be continued if no exception has been thrown.

Throws:

X - The converted exception, if present.

X extends Throwable

throwIf

public final <R,X extends Throwable> R throwIf(Predicate<? super T> condition,
                                               Function<? super T,X> mapping,
                                               R result)
                                        throws X extends Throwable

Applies a given mapping to the associated exception if the given condition applies and throws the result, otherwise a given result will be returned.

Type Parameters:

R - The result type in case of a regular result.

X - The exception type that is intended as a result of the given mapping and that is thrown by this method, if applicable.

Parameters:

condition - A Predicate that is used to check the associated exception for applicability.

mapping - A Function that converts the associated exception to a specific type of exception to be thrown at that point.

result - A predefined regular result in case the condition is not true.

Returns:

The predefined result.

Throws:

X - The converted exception, if present.

X extends Throwable

reThrow

public final <X extends Throwable> Revision<T> reThrow(Class<X> xClass)
                                                throws X extends Throwable

Rethrows the associated exception if it matches the given exception type. Otherwise, this Revision will be returned. Example:

         try {
             return somethingThatMayCauseAWrappedException();
         } catch (final WrappedException caught) {
             throw Revision.of(caught.getCause())
                           .reThrow(IOException.class)
                           .reThrow(SQLException.class)
                           .reThrow(URISyntaxException.class)
                           .close(ExpectationException::new);
         }
 

Type Parameters:

X - The type of exception that is expected and, if applicable, thrown by this method.

Parameters:

xClass - The Class that represents the type of exception that is expected.

Returns:

This Revision, which can be continued if no exception has been thrown.

Throws:

X - the associated exception, cast to the expected type, if applicable.

X extends Throwable

See Also:

of(Throwable), close(Function)

reThrow

public final <R,X extends Throwable> R reThrow(Class<X> xClass,
                                               R result)
                                        throws X extends Throwable

Rethrows the associated exception if it matches the given exception type, otherwise a given result will be returned.

Type Parameters:

R - The result type in case of a regular result.

X - The type of exception that is expected and, if applicable, thrown by this method.

Parameters:

xClass - The Class that represents the type of exception that is expected.

result - A predefined regular result in case the exception is not of that type.

Returns:

The predefined result.

Throws:

X - the associated exception, cast to the expected type, if applicable.

X extends Throwable

close

public final <R> R close(Function<? super T,R> mapping)

Completes this revision, applies a given mapping to the associated exception, and returns its result.

close

public final T close()

Completes this revision and returns the associated exception unchanged.