Package io.engineblock.activityapi.errorhandling

Class HashedErrorHandler<T extends java.lang.Throwable,​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 java.lang.Throwable,​R>
extends java.lang.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.

    • Method Summary

      Modifier and Type Method Description
      void addValidClasses​(java.lang.Class<? extends T>... validClasses)
      Add to the set of valid classes that will be used when searching for a class by name.
      java.util.Set<java.lang.Class<? extends T>> getGroup​(java.lang.String groupName)  
      java.util.List<java.lang.String> getGroupNames()  
      java.util.Map<java.lang.Class<? extends T>,​CycleErrorHandler<T,​R>> getHandlers()
      Return the current list of active handler assignments.
      java.util.Set<java.lang.Class<? extends T>> getValidClasses()  
      R handleError​(long cycle, T throwable, java.lang.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​(java.lang.String groupName, java.lang.Class<? extends T>... exceptions)
      Set a group name for a set of classes.
      void setHandlerForClasses​(CycleErrorHandler<T,​R> errorHandler, java.lang.Class<? extends T>... errorClasses)
      Set the error handler for the specified class, and any subclasses of it.
      void setHandlerForGroup​(java.lang.String groupName, CycleErrorHandler<T,​R> errorHandler)
      Set the error handler for a named group of exception classes.
      void setHandlerForPattern​(java.lang.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​(java.lang.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

    • Constructor Detail

      • HashedErrorHandler

        public HashedErrorHandler()

    • Method Detail

      • setGroup

        @SafeVarargs
public final void setGroup​(java.lang.String groupName,
                           java.lang.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 java.util.Set<java.lang.Class<? extends T>> getGroup​(java.lang.String groupName)

      • setHandlerForClasses

        @SafeVarargs
public final void setHandlerForClasses​(CycleErrorHandler<T,​R> errorHandler,
                                       java.lang.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​(java.lang.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:
        java.lang.RuntimeException - if the group name is not found

      • setHandlerForPattern

        public final void setHandlerForPattern​(java.lang.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 java.util.Map<java.lang.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​(java.lang.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 java.util.Set<java.lang.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​(java.lang.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 onAfterOpStop
        Returns:
        this, for method chaining.

      • handleError

        public R handleError​(long cycle,
                     T throwable,
                     java.lang.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 onAfterOpStop 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 java.lang.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 java.util.List<java.lang.String> getGroupNames()