Package org.incendo.cloud.exception.handling

Class ExceptionController<C>

java.lang.Object
org.incendo.cloud.exception.handling.ExceptionController<C>
Type Parameters:
C - the command sender type
@API(status=STABLE) public final class ExceptionController<C> extends Object
The controller handles registrations of exception handlers, as well as the routing of incoming exceptions to the handlers.

  • Constructor Details

    • ExceptionController

      public ExceptionController()
      Creates a new exception controller.

  • Method Details

    • unwrapCompletionException

      public static @NonNull Throwable unwrapCompletionException(@NonNull Throwable throwable)
      Unwraps a CompletionException recursively until a cause is encountered that is not a completion exception.
      Parameters:
      throwable - the throwable
      Returns:
      the original cause

    • handleException

      public <T extends Throwable> void handleException(@NonNull CommandContext<C> commandContext, @NonNull T exception) throws Throwable
      Attempts to handle the given exception gracefully.

      The controller will attempt to find exception handlers for the exception type, and any of its supertypes. Only one exception handler will get to fully handle the exception.

      If no exception handler was able to handle the exception, the exception will be re-thrown. The thrown exception might be different from the initial exception in the case that any of the exception handlers throws a new exception.

      Type Parameters:
      T - the exception type
      Parameters:
      commandContext - the command context
      exception - the exception
      Throws:
      Throwable - any exception left unhandled is re-thrown and should be handled by the caller

    • register

      public <T extends Throwable> @NonNull ExceptionController<C> register(@NonNull ExceptionHandlerRegistration<C,? extends T> registration)
      Registers the given registration.

      The ordering matters when multiple handlers are registered for the same exception type. The last registered handler will get priority.

      Type Parameters:
      T - the exception type handled by the exception handler
      Parameters:
      registration - the exception handler registration
      Returns:
      this exception controller

    • register

      public <T extends Throwable> @NonNull ExceptionController<C> register(@NonNull TypeToken<T> exceptionType, @NonNull ExceptionHandlerRegistration.BuilderDecorator<C,T> decorator)
      Decorates a registration builder and registers the result.

      The ordering matters when multiple handlers are registered for the same exception type. The last registered handler will get priority.

      Type Parameters:
      T - the exception type handled by the exception handler
      Parameters:
      exceptionType - the exception type handled by the exception handler
      decorator - the builder decorator
      Returns:
      this exception controller

    • register

      public <T extends Throwable> @NonNull ExceptionController<C> register(@NonNull Class<T> exceptionType, @NonNull ExceptionHandlerRegistration.BuilderDecorator<C,T> decorator)
      Decorates a registration builder and registers the result.

      The ordering matters when multiple handlers are registered for the same exception type. The last registered handler will get priority.

      Type Parameters:
      T - the exception type handled by the exception handler
      Parameters:
      exceptionType - the exception type handled by the exception handler
      decorator - the builder decorator
      Returns:
      this exception controller

    • registerHandler

      public <T extends Throwable> @NonNull ExceptionController<C> registerHandler(@NonNull TypeToken<T> exceptionType, @NonNull ExceptionHandler<C,? extends T> exceptionHandler)
      Registers the given exceptionHandler.

      The ordering matters when multiple handlers are registered for the same exception type. The last registered handler will get priority.

      Type Parameters:
      T - the exception type handled by the exception handler
      Parameters:
      exceptionType - the exception type handled by the exception handler
      exceptionHandler - the exception handler
      Returns:
      this exception controller

    • registerHandler

      public <T extends Throwable> @NonNull ExceptionController<C> registerHandler(@NonNull Class<T> exceptionType, @NonNull ExceptionHandler<C,? extends T> exceptionHandler)
      Registers the given exceptionHandler.

      The ordering matters when multiple handlers are registered for the same exception type. The last registered handler will get priority.

      Type Parameters:
      T - the exception type handled by the exception handler
      Parameters:
      exceptionType - the exception type handled by the exception handler
      exceptionHandler - the exception handler
      Returns:
      this exception controller

    • clearHandlers

      public void clearHandlers()
      Removes all registered handlers.

      This can be used to make sure that no default handlers of higher precision are invoked before your handler.

      It is recommended that you register a handler for Throwable if you use this, to make sure that no uncaught errors leak out of the controller.