io.engineblock.activityapi.errorhandling

Class HashedErrorHandler<T extends Throwable,R>

java.lang.Object

io.engineblock.activityapi.errorhandling.HashedErrorHandler<T,R>

Type Parameters:

T - The subtype bound of exception to allow exception handlers for.

R - The result type that will be produced by these error handlers.

All Implemented Interfaces:

CycleErrorHandler<T,R>

public class HashedErrorHandler<T extends Throwable,R>
extends Object
implements CycleErrorHandler<T,R>

Allow error handlers to be registered for any exception type, with an explicit handler that will be called if no specific other handler is matched. This error handler will automatically cascade up the error type hierarchy of the reported error to find any matching handlers. If none are found between the reported error type and the upper type bound, inclusive, then the default error handler is called, which simply rethrows an error indicating that no more suitable error handler was provided. If you need to have the default error handler trigger before a certain supertype of allowable errors is traversed, then set the upper bound with setUpperBound(Class). You may also register named groups of exceptions for which you can set the handler in a single call.

Type Parameters

The type parameter R represents a generic return type that is returned by a handler. This is borrowed directly from the base error handler type CycleErrorHandler from which this aggregating handler is built. R can be any type that makes sense for your particular error handling logic. For example, a Boolean return type can be used to signal whether down-chain handlers should be executed or not.

Patterns

Some of the methods support matching exceptions by substring or regex. The patterns are applied to the Class.getSimpleName() version of the classname. Further, simple substrings consisting only of word characters are considered shortcuts for single Throwable types and thus throw an exception if more than one is matched. Patterns that contain non-word characters allow for bulk management.

Nested Class Summary

Nested classes/interfaces inherited from interface io.engineblock.activityapi.errorhandling.CycleErrorHandler

CycleErrorHandler.Triple<T,R>

Constructor Summary

Constructors

Constructor and Description
HashedErrorHandler()

Method Summary

Modifier and Type	Method and Description
void	addValidClasses(Class<? extends T>... validClasses) Add to the set of valid classes that will be used when searching for a class by name.
Set<Class<? extends T>>	getGroup(String groupName)
List<String>	getGroupNames()
Map<Class<? extends T>,CycleErrorHandler<T,R>>	getHandlers() Return the current list of active handler assignments.
Set<Class<? extends T>>	getValidClasses()
R	handleError(long cycle, T throwable, String errMsg) Handle the error according to the matching error handler for the supplied Throwable subtype.
void	resetAllClassHandlers() Unset all class handlers.
HashedErrorHandler<T,R>	setDefaultHandler(CycleErrorHandler<T,R> errorHandler) Set the default handler that gets called on any exceptions that do not match a class or super-class specific handler.
void	setGroup(String groupName, Class<? extends T>... exceptions) Set a group name for a set of classes.
void	setHandlerForClasses(CycleErrorHandler<T,R> errorHandler, Class<? extends T>... errorClasses) Set the error handler for the specified class, and any subclasses of it.
void	setHandlerForGroup(String groupName, CycleErrorHandler<T,R> errorHandler) Set the error handler for a named group of exception classes.
void	setHandlerForPattern(String pattern, CycleErrorHandler<T,R> errorHandler) Find the matching classes from the recognized classes, and then set the handler for all of them.
HashedErrorHandler<T,R>	setUpperBound(Class<? extends T> upperBound) Sets the uppper bound on the Throwable type that you want to consider when walking up the class hierarchy to find a handled supertype.

Methods inherited from class java.lang.Object

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

Methods inherited from interface io.engineblock.activityapi.errorhandling.CycleErrorHandler

handleError, handleError

Constructor Detail

HashedErrorHandler

public HashedErrorHandler()

Method Detail

setGroup

@SafeVarargs
public final void setGroup(String groupName,
                                        Class<? extends T>... exceptions)

Set a group name for a set of classes. If the classes in the group are not already in the list of recognized classes, then they are added as well.

Parameters:

groupName - the name that the group will be referred to as

exceptions - the set of exceptions to include in the group

getGroup

public Set<Class<? extends T>> getGroup(String groupName)

setHandlerForClasses

@SafeVarargs
public final void setHandlerForClasses(CycleErrorHandler<T,R> errorHandler,
                                                    Class<? extends T>... errorClasses)

Set the error handler for the specified class, and any subclasses of it.

Parameters:

errorHandler - The error handler to be called when this class or any subclasses that do not have their own more specific handler.

errorClasses - The set of classes to set the handler for

setHandlerForGroup

public final void setHandlerForGroup(String groupName,
                                     CycleErrorHandler<T,R> errorHandler)

Set the error handler for a named group of exception classes.

Parameters:

errorHandler - The error handler to be called when this class or any subclasses that do not have their own more specific handler.

groupName - The named group of exception classes

Throws:

RuntimeException - if the group name is not found

setHandlerForPattern

public final void setHandlerForPattern(String pattern,
                                       CycleErrorHandler<T,R> errorHandler)

Find the matching classes from the recognized classes, and then set the handler for all of them. If the pattern includes only word characters, then it is assumed to be a substring, and only one match is allowed. If the pattern includes any non-word characters, then it is presumed to be a regex, for which multiple classes are allowed to be matched.

Parameters:

pattern - A substring or regex for the class names

errorHandler - the error handler to be registered for the classes

resetAllClassHandlers

public final void resetAllClassHandlers()

Unset all class handlers. This does not reset the default handler.

getHandlers

public final Map<Class<? extends T>,CycleErrorHandler<T,R>> getHandlers()

Return the current list of active handler assignments.

Returns:

an unmodifiable Map of Class to CycleErrorHandler.

addValidClasses

@SafeVarargs
public final void addValidClasses(Class<? extends T>... validClasses)

Add to the set of valid classes that will be used when searching for a class by name.

Parameters:

validClasses - The classes that this error handler will search

getValidClasses

public Set<Class<? extends T>> getValidClasses()

setDefaultHandler

public HashedErrorHandler<T,R> setDefaultHandler(CycleErrorHandler<T,R> errorHandler)

Set the default handler that gets called on any exceptions that do not match a class or super-class specific handler.

Parameters:

errorHandler - The error handler to be called as a last resort.

Returns:

this HashedErrorHandler, for method chaining

setUpperBound

public HashedErrorHandler<T,R> setUpperBound(Class<? extends T> upperBound)

Sets the uppper bound on the Throwable type that you want to consider when walking up the class hierarchy to find a handled supertype. By default, this is simply Throwable. If the set of types that should be handled directly are more limited than this, you can cause the default handler to trigger when the upper bound type is found if the traversal gets that far.

Parameters:

upperBound - The Throwable subtype which is the lowest subtype to handle

Returns:

this, for method chaining.

handleError

public R handleError(long cycle,
                     T throwable,
                     String errMsg)

Handle the error according to the matching error handler for the supplied Throwable subtype. Handlers of supertypes are used when a specific handler is not found for the reported error class. This means that you can install a default handler for a throwable that is a common parent to your exceptions and have it handle all reported errors by default.

The return type is contextual to how this handler class is used. If it is important to use error handler implementations to control flow or other optional execution, then the return type can be used as a form of signaling for that. If you have no need for this, then simply use these classes with a Void result type in the R parameter.

Specified by:

handleError in interface CycleErrorHandler<T extends Throwable,R>

Parameters:

cycle - The activity cycle for which the error is being handled

throwable - The exception that was thrown or that needs to be handled

errMsg - A detailed message explaining the error

Returns:

the handler result type, depending on the usage context

getGroupNames

public List<String> getGroupNames()