org.swblocks.jbl.eh

Class EhSupport

java.lang.Object

org.swblocks.jbl.eh.EhSupport

public final class EhSupport
extends java.lang.Object

A static class for EH support helpers.

Field Summary

Fields

Modifier and Type	Field and Description
static java.util.function.Consumer<java.lang.Throwable>	defaultAbortHandler
protected static java.util.function.Consumer<java.lang.Throwable>	throwHandler This is the rethrow handler to be used by the catch blocks below.

Method Summary

Modifier and Type	Method and Description
static void	abort(java.lang.String message) Method that takes a message that will be used by the fatal exception handler wrapped in a IllegalStateException.
static void	abort(java.lang.String message, java.lang.Exception cause) Method that takes a message that will be used by the fatal exception handler wrapped in a IllegalStateException and an Exception to be added as the Cause.
static <E> E	checkResult(Result<E> result) Checks if Result object is successful and returns the actual result value.
static void	closeQuietlyOrException(java.lang.Throwable throwable, java.io.Closeable closeable) Convenience wrapper for closeQuietlyOrFatal(Throwable, Object, ThrowsConsumer) for objects which implement Closeable interface
static <T> void	closeQuietlyOrFatal(java.lang.Throwable throwable, T closeable, ThrowsConsumer<T> closeCallback) Convenience wrapper for tryCloseQuietly(Throwable, Object, ThrowsConsumer)
static java.lang.Throwable	enhance(java.lang.Throwable exception) Enhance an exception if it is not already enhanced and return it.
static java.lang.Throwable	enhance(java.lang.Throwable exception, java.lang.String name, java.lang.Object value) Enhance an exception if it is not already enhanced, add a new property and then return it.
static void	enhanceAndRethrow(ThrowsRunnable callback, java.util.function.Consumer<BaseException> enhanceCallback) If an exception if thrown from a simple callback it gets enhanced by the specified callback and then rethrown.
static void	enhanceAndRethrow(ThrowsRunnable callback, java.lang.String name, java.lang.Object value) If an exception if thrown from a simple callback it gets enhanced with the specified property and rethrown.
static <R> R	enhanceAndRethrowFn(ThrowsSupplier<R> callback, java.util.function.Consumer<BaseException> enhanceCallback) If an exception if thrown from a functional callback it gets enhanced by the specified callback and then rethrown.
static <R> R	enhanceAndRethrowFn(ThrowsSupplier<R> callback, java.lang.String name, java.lang.Object value) If an exception if thrown from a functional callback it gets enhanced with the specified property and rethrown.
static void	enhancedFinally(ThrowsRunnable callback, java.util.function.Consumer<java.lang.Throwable> handler) Same as a normal finally block except that the handler will receive the current exception info if one has been thrown.
static <R> R	enhancedFinallyFn(ThrowsSupplier<R> callback, java.util.function.Consumer<java.lang.Throwable> handler) Same functionality as enhancedFinally(ThrowsRunnable, Consumer) except that it takes a supplier callback which returns value and then this helper returns the same value.
static void	ensure(boolean expectedCondition, java.lang.String message, java.lang.Object... args) Checks that the expected condition is satisfied otherwise will throw IllegalStateException.
static void	ensureArg(boolean expectedCondition, java.lang.String message, java.lang.Object... args) Checks that the expected parameter condition is satisfied or will throw IllegalArgumentException.
static void	ensureOrFatal(boolean expectedCondition, java.lang.Exception cause, java.lang.String message, java.lang.Object... args) Checks that the expected condition is satisfied otherwise will ultimately execute a fatal exception handler.
static void	ensureOrFatal(boolean expectedCondition, java.lang.String message, java.lang.Object... args) Checks that the expected condition is satisfied otherwise will ultimately execute a fatal exception handler.
static void	fatalOnException(ThrowsRunnable callback) Executes a callback that is expected to not throw an exception and if exception is thrown a fatal handler is invoked (which by default will throw a non-recoverable exception).
static <R> R	fatalOnExceptionFn(ThrowsSupplier<R> callback) Executes a supplier callback that is expected to not throw an exception and if exception is thrown a fatal handler is invoked (which by default will throw a non-recoverable exception).
static java.util.function.Consumer<java.lang.Throwable>	getAbortHandler() Returns the current fatal no-throw exception handler for the EH library.
static <R> R	getExceptionDetails(java.lang.Throwable exception, java.util.function.Function<java.lang.StringBuffer,R> callback) Obtains the exception details dump, including all properties, for an exception.
static java.lang.String	getExceptionDetailsAsString(java.lang.Throwable exception) Obtains the exception details dump, including all properties, for an exception as string.
static BaseException	getPropertiesException(java.lang.Throwable exception) Obtains a properties exception associated with this exception.
static java.time.Instant	getTimeThrown(java.lang.Throwable exception) Obtains the time thrown / enhanced property of an exception.
static void	printExceptionDetails(java.lang.Throwable exception, java.io.PrintStream printStream) Obtains the exception details dump, including all properties, for an exception into a print stream.
static void	printExceptionDetails(java.lang.Throwable exception, java.io.PrintWriter printWriter) Obtains the exception details dump, including all properties, for an exception into a print writer.
static void	propagate(ThrowsRunnable callback) Executes a callback that throws exceptions and if exceptions are raised they get propagated as is, but all exceptions are propagated as unchecked exceptions.
static <R> R	propagateFn(ThrowsSupplier<R> callback) Executes a supplier callback that throws exceptions and if exceptions are raised they get propagated as is, but all exceptions are propagated as unchecked exceptions.
static void	putProperty(java.lang.Throwable exception, java.lang.String name, java.lang.Object value) Associate a property to an exception.
static void	rethrow(java.lang.Throwable throwable) Rethrow an Throwable as is, but making it unchecked.
protected static <T extends java.lang.Throwable> void	rethrowInternal(java.lang.Throwable throwable)
static void	setAbortHandler(java.util.function.Consumer<java.lang.Throwable> abortHandler) Sets a new fatal no-throw exception handler for the EH library code
static void	suppressExceptionsOrFatal(java.lang.Throwable throwable, ThrowsRunnable callback) Convenience wrapper for trySuppressExceptions(Throwable, ThrowsRunnable)
static void	throwEnhanced(java.lang.Throwable exception) Enhance an exception if it is not already enhanced and rethrow it.
static void	throwEnhanced(java.lang.Throwable exception, java.lang.String name, java.lang.Object value) Enhance an exception if it is not already enhanced, add a new property and then rethrow it.
static void	tryCloseQuietly(java.lang.Throwable throwable, java.io.Closeable closeable) Convenience wrapper for tryCloseQuietly(Throwable, Object, ThrowsConsumer) for objects which implement Closeable interface
static <T> void	tryCloseQuietly(java.lang.Throwable throwable, T closeable, ThrowsConsumer<T> closeCallback) Tries to close quietly a closable object of type T and throws if the exception thrown by close cannot be suppressed (i.e.
static <E> E	tryGetProperty(java.lang.Throwable exception, java.lang.String name) Tries to obtain the value of a property from an exception (if already associated).
static java.lang.String	tryGetPropertyAsString(java.lang.Throwable exception, java.lang.String name) Tries to obtain the value of a property as string from an exception (if already associated).
static void	trySuppressExceptions(java.lang.Throwable throwable, ThrowsRunnable callback) Executes a callback that throws and suppresses all exceptions if possible (i.e.

Methods inherited from class java.lang.Object

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

Field Detail

defaultAbortHandler

public static final java.util.function.Consumer<java.lang.Throwable> defaultAbortHandler

throwHandler

protected static java.util.function.Consumer<java.lang.Throwable> throwHandler

This is the rethrow handler to be used by the catch blocks below.

The derived class EhSupport can change it to something different which can allow more enhanced behavior to be provided there (e.g. invoking throwEnhanced)

Method Detail

getPropertiesException

public static BaseException getPropertiesException(java.lang.Throwable exception)

Obtains a properties exception associated with this exception.

Parameters:

exception - The exception to get the properties exception for

Returns:

The properties exception

enhance

public static java.lang.Throwable enhance(java.lang.Throwable exception)

Enhance an exception if it is not already enhanced and return it.

Parameters:

exception - The exception to be enhanced

Returns:

Same as the input exception

enhance

public static java.lang.Throwable enhance(java.lang.Throwable exception,
                                          java.lang.String name,
                                          java.lang.Object value)

Enhance an exception if it is not already enhanced, add a new property and then return it.

Parameters:

exception - The exception to be enhanced

name - The name of the property

value - The value of the property

Returns:

Same as the input exception

throwEnhanced

public static void throwEnhanced(java.lang.Throwable exception)

Enhance an exception if it is not already enhanced and rethrow it.

Parameters:

exception - The exception to be enhanced

throwEnhanced

public static void throwEnhanced(java.lang.Throwable exception,
                                 java.lang.String name,
                                 java.lang.Object value)

Enhance an exception if it is not already enhanced, add a new property and then rethrow it.

Parameters:

exception - The exception to be enhanced

name - The name of the property

value - The value of the property

enhanceAndRethrow

public static void enhanceAndRethrow(ThrowsRunnable callback,
                                     java.util.function.Consumer<BaseException> enhanceCallback)

If an exception if thrown from a simple callback it gets enhanced by the specified callback and then rethrown.

Parameters:

callback - The simple callback to guard

enhanceCallback - The callback to be called to enhance the exception (if thrown)

enhanceAndRethrow

public static void enhanceAndRethrow(ThrowsRunnable callback,
                                     java.lang.String name,
                                     java.lang.Object value)

If an exception if thrown from a simple callback it gets enhanced with the specified property and rethrown.

Parameters:

callback - The simple callback to guard

name - The name of the property

value - The value of the property

enhanceAndRethrowFn

public static <R> R enhanceAndRethrowFn(ThrowsSupplier<R> callback,
                                        java.util.function.Consumer<BaseException> enhanceCallback)

If an exception if thrown from a functional callback it gets enhanced by the specified callback and then rethrown.

Type Parameters:

R - The return type of the functional callback

Parameters:

callback - The functional callback to guard

enhanceCallback - The callback to be called to enhance the exception (if thrown)

Returns:

The value returned from the functional callback

enhanceAndRethrowFn

public static <R> R enhanceAndRethrowFn(ThrowsSupplier<R> callback,
                                        java.lang.String name,
                                        java.lang.Object value)

If an exception if thrown from a functional callback it gets enhanced with the specified property and rethrown.

Type Parameters:

R - The return type of the functional callback

Parameters:

callback - The functional callback to guard

name - The name of the property

value - The value of the property

Returns:

The value returned from the functional callback

getTimeThrown

public static java.time.Instant getTimeThrown(java.lang.Throwable exception)

Obtains the time thrown / enhanced property of an exception.

Parameters:

exception - The exception to obtain the time thrown / enhanced property

Returns:

The time thrown / enhanced

putProperty

public static void putProperty(java.lang.Throwable exception,
                               java.lang.String name,
                               java.lang.Object value)

Associate a property to an exception.

Parameters:

exception - The exception to associate a property with

name - The name of the property

value - The value of the property

tryGetProperty

public static <E> E tryGetProperty(java.lang.Throwable exception,
                                   java.lang.String name)

Tries to obtain the value of a property from an exception (if already associated).

Type Parameters:

E - The expected type of the value of the property

Parameters:

exception - The exception to obtain the property value from

name - The name of the property

Returns:

The value of the property or null if property with such name was not found

tryGetPropertyAsString

public static java.lang.String tryGetPropertyAsString(java.lang.Throwable exception,
                                                      java.lang.String name)

Tries to obtain the value of a property as string from an exception (if already associated).

Parameters:

exception - The exception to obtain the property value from

name - The name of the property

Returns:

The value of the property as string or null if property with such name was not found

getExceptionDetails

public static <R> R getExceptionDetails(java.lang.Throwable exception,
                                        java.util.function.Function<java.lang.StringBuffer,R> callback)

Obtains the exception details dump, including all properties, for an exception.

Type Parameters:

R - The return type of the callback (if any)

Parameters:

exception - The exception to obtain the exception details dump for

callback - The callback invoked with the string buffer

Returns:

The same as the return value from the callback

getExceptionDetailsAsString

public static java.lang.String getExceptionDetailsAsString(java.lang.Throwable exception)

Obtains the exception details dump, including all properties, for an exception as string.

Parameters:

exception - The exception to obtain the exception details dump for

Returns:

The exception details as string

printExceptionDetails

public static void printExceptionDetails(java.lang.Throwable exception,
                                         java.io.PrintWriter printWriter)

Obtains the exception details dump, including all properties, for an exception into a print writer.

Parameters:

exception - The exception to obtain the exception details dump for

printWriter - The print writer where to store them

printExceptionDetails

public static void printExceptionDetails(java.lang.Throwable exception,
                                         java.io.PrintStream printStream)

Obtains the exception details dump, including all properties, for an exception into a print stream.

Parameters:

exception - The exception to obtain the exception details dump for

printStream - The print stream where to store them

checkResult

public static <E> E checkResult(Result<E> result)

Checks if Result object is successful and returns the actual result value. Otherwise it throws the exception held in the Result object.

Type Parameters:

E - The type of the actual return value

Parameters:

result - The Result object to be checked

Returns:

The actual value from the Result object if the result parameter is successful

rethrowInternal

protected static <T extends java.lang.Throwable> void rethrowInternal(java.lang.Throwable throwable)
                                                               throws T extends java.lang.Throwable

Throws:

T extends java.lang.Throwable

rethrow

public static void rethrow(java.lang.Throwable throwable)

Rethrow an Throwable as is, but making it unchecked.

Implements the 'sneaky throw' pattern to allow us to deal sensibly with checked exceptions.

For more details see here: https://www.google.com/#q=java+sneaky+throw

Parameters:

throwable - to be rethrown and unchecked.

propagate

public static void propagate(ThrowsRunnable callback)

Executes a callback that throws exceptions and if exceptions are raised they get propagated as is, but all exceptions are propagated as unchecked exceptions.

Parameters:

callback - The callback to execute

propagateFn

public static <R> R propagateFn(ThrowsSupplier<R> callback)

Executes a supplier callback that throws exceptions and if exceptions are raised they get propagated as is, but all exceptions are propagated as unchecked exceptions.

Type Parameters:

R - The return type

Parameters:

callback - The supplier callback to execute

Returns:

The value returned by the callback

fatalOnException

public static void fatalOnException(ThrowsRunnable callback)

Executes a callback that is expected to not throw an exception and if exception is thrown a fatal handler is invoked (which by default will throw a non-recoverable exception).

Parameters:

callback - The callback to execute

fatalOnExceptionFn

public static <R> R fatalOnExceptionFn(ThrowsSupplier<R> callback)

Executes a supplier callback that is expected to not throw an exception and if exception is thrown a fatal handler is invoked (which by default will throw a non-recoverable exception).

Type Parameters:

R - The return type

Parameters:

callback - The supplier callback to execute

Returns:

The value returned by the callback

ensure

public static void ensure(boolean expectedCondition,
                          java.lang.String message,
                          java.lang.Object... args)

Checks that the expected condition is satisfied otherwise will throw IllegalStateException.

Parameters:

expectedCondition - the provided parameter condition

message - the error message to display id the parameter condition is not satisfied

args - list of args provided for formatting the message

ensureArg

public static void ensureArg(boolean expectedCondition,
                             java.lang.String message,
                             java.lang.Object... args)

Checks that the expected parameter condition is satisfied or will throw IllegalArgumentException.

Parameters:

expectedCondition - the provided parameter condition

message - the error message to display id the parameter condition is not satisfied

args - list of args provided for formatting the message

ensureOrFatal

public static void ensureOrFatal(boolean expectedCondition,
                                 java.lang.String message,
                                 java.lang.Object... args)

Checks that the expected condition is satisfied otherwise will ultimately execute a fatal exception handler.

Parameters:

expectedCondition - the condition that must be satisfied

message - the message that will be passed to the exception handler

args - list of args that are being checked

ensureOrFatal

public static void ensureOrFatal(boolean expectedCondition,
                                 java.lang.Exception cause,
                                 java.lang.String message,
                                 java.lang.Object... args)

Checks that the expected condition is satisfied otherwise will ultimately execute a fatal exception handler.

Parameters:

expectedCondition - the condition that must be satisfied

cause - the exception to add as the cause.

message - the message that will be passed to the exception handler

args - list of args that are being checked

abort

public static void abort(java.lang.String message,
                         java.lang.Exception cause)

Method that takes a message that will be used by the fatal exception handler wrapped in a IllegalStateException and an Exception to be added as the Cause.

Parameters:

message - the message that will be used in the fatal exception

cause - the exception to add as the cause.

abort

public static void abort(java.lang.String message)

Method that takes a message that will be used by the fatal exception handler wrapped in a IllegalStateException.

Parameters:

message - the message that will be used in the fatal exception

getAbortHandler

public static java.util.function.Consumer<java.lang.Throwable> getAbortHandler()

Returns the current fatal no-throw exception handler for the EH library.

Returns:

The current fatal no-throw exception handler for the EH library

setAbortHandler

public static void setAbortHandler(java.util.function.Consumer<java.lang.Throwable> abortHandler)

Sets a new fatal no-throw exception handler for the EH library code

Parameters:

abortHandler - The new fatal no-throw exception handler for the EH library code or null. If null is provided then the default handler is used.

enhancedFinally

public static void enhancedFinally(ThrowsRunnable callback,
                                   java.util.function.Consumer<java.lang.Throwable> handler)

Same as a normal finally block except that the handler will receive the current exception info if one has been thrown. The throwable parameter in the handler is non-null if an exception was thrown and its value will be is null if this was normal / non-exceptional finally execution.

Parameters:

callback - The callback to execute

handler - The finally handler to execute (with extra exception info provided)

enhancedFinallyFn

public static <R> R enhancedFinallyFn(ThrowsSupplier<R> callback,
                                      java.util.function.Consumer<java.lang.Throwable> handler)

Same functionality as enhancedFinally(ThrowsRunnable, Consumer) except that it takes a supplier callback which returns value and then this helper returns the same value.

Type Parameters:

R - The return type of the supplier callback

Parameters:

callback - The supplier callback to execute

handler - The try/finally handler to execute

Returns:

The value returned by the callback

trySuppressExceptions

public static void trySuppressExceptions(java.lang.Throwable throwable,
                                         ThrowsRunnable callback)

Executes a callback that throws and suppresses all exceptions if possible (i.e. throwable parameter has exception suppression enabled)

Parameters:

throwable - The throwable to capture the suppressed exception. It can be null (see above).

callback - The callback to execute

suppressExceptionsOrFatal

public static void suppressExceptionsOrFatal(java.lang.Throwable throwable,
                                             ThrowsRunnable callback)

Convenience wrapper for trySuppressExceptions(Throwable, ThrowsRunnable)

Parameters:

throwable - The throwable to capture the suppressed exception. It can be null (see above).

callback - The callback to execute

tryCloseQuietly

public static <T> void tryCloseQuietly(java.lang.Throwable throwable,
                                       T closeable,
                                       ThrowsConsumer<T> closeCallback)

Tries to close quietly a closable object of type T and throws if the exception thrown by close cannot be suppressed (i.e. throwable is null or it does not support suppression of exceptions)

Type Parameters:

T - The type of the closeable object (typically object that implements Closeable)

Parameters:

throwable - The throwable to capture the suppressed exception. It can be null (see above).

closeable - The closeable object to be closed

closeCallback - The callback that is responsible for closing the object

tryCloseQuietly

public static void tryCloseQuietly(java.lang.Throwable throwable,
                                   java.io.Closeable closeable)

Convenience wrapper for tryCloseQuietly(Throwable, Object, ThrowsConsumer) for objects which implement Closeable interface

Parameters:

throwable - The throwable to capture the suppressed exception. It can be null (see above).

closeable - The closeable object to be closed

closeQuietlyOrFatal

public static <T> void closeQuietlyOrFatal(java.lang.Throwable throwable,
                                           T closeable,
                                           ThrowsConsumer<T> closeCallback)

Convenience wrapper for tryCloseQuietly(Throwable, Object, ThrowsConsumer)

Tries to close quietly a closable object of type T and aborts if the exception thrown by close cannot be suppressed (i.e. throwable is null or it does not support suppression of exceptions)

Type Parameters:

T - The type of the closeable object (typically object that implements Closeable)

Parameters:

throwable - The throwable to capture the suppressed exception. It can be null (see above).

closeable - The closeable object to be closed

closeCallback - The callback that is responsible for closing the object

closeQuietlyOrException

public static void closeQuietlyOrException(java.lang.Throwable throwable,
                                           java.io.Closeable closeable)

Convenience wrapper for closeQuietlyOrFatal(Throwable, Object, ThrowsConsumer) for objects which implement Closeable interface

Parameters:

throwable - The throwable to capture the suppressed exception. It can be null (see above).

closeable - The closeable object to be closed