Package studio.mevera.imperat

Interface BaseThrowableHandler<S extends CommandSource>

Type Parameters:
S - the type of command source that provides context for exception handling, must extend CommandSource
All Superinterfaces:
ThrowableHandler<S>
All Known Subinterfaces:
Command<S>, ImperatConfig<S>
public non-sealed interface BaseThrowableHandler<S extends CommandSource> extends ThrowableHandler<S>
A base implementation of ThrowableHandler that provides intelligent exception chain traversal and resolution logic. This interface serves as a foundation for command execution error handling in the Imperat framework.

This handler implements a comprehensive exception resolution strategy that:

  1. Traverses the entire exception cause chain from the root exception to the deepest cause
  2. Prioritizes SelfHandlingException instances for immediate self-resolution
  3. Falls back to registered CommandExceptionHandler instances for standard exceptions
  4. Provides detailed debugging information throughout the resolution process
  5. Logs unhandled exceptions for debugging purposes

The non-sealed modifier allows for further extension while maintaining the base exception handling contract.

Exception Resolution Priority: 


 1. SelfHandlingException.handle() - immediate self-resolution
 2. Registered CommandExceptionHandler for the specific exception type
 3. Traverse to exception.getCause() and repeat
 4. Log error if no handler found in the entire chain

Example implementation: 


 public class CommandExceptionHandler implements BaseThrowableHandler<CommandSource> {

     @Override
     public CommandExceptionHandler<?, CommandSource> getThrowableResolver(Class<?> exceptionType) {
         return resolvers.get(exceptionType);
     }
 }
Since:
1.0
See Also:

  • Method Details

    • handleExecutionError

      default <E extends Throwable> boolean handleExecutionError(@NotNull E throwable, CommandContext<S> context, Class<?> owning, String methodName)
      Handles exceptions that occur during command execution by traversing the exception cause chain and applying appropriate resolution strategies.

      This method implements a sophisticated exception handling workflow:

      The method terminates early upon successful resolution, ensuring that only the most appropriate handler processes each exception. If no suitable handler is found in the entire cause chain, the original exception is logged as an error.

      Resolution Flow Example: 

      
 try {
     // RootCommand execution
 } catch (CommandPermissionException e) {
     // 1. Check if CommandPermissionException is SelfHandlingException → No
     // 2. Look for CommandExceptionHandler<CommandPermissionException> → Found
     // 3. Call resolver.resolve(e, context) → Success, return
 } catch (WrappedException e) {
     // 1. Check WrappedException → No resolver
     // 2. Check e.getCause() (CommandSyntaxException) → Found resolver
     // 3. Resolve and return
 }

      Thread Safety: This method is thread-safe assuming the underlying ThrowableHandler.getErrorHandlerFor(Class) implementation is thread-safe.

      Specified by:
      handleExecutionError in interface ThrowableHandler<S extends CommandSource>
      Parameters:
      throwable - the root exception that occurred during command execution, may be null (though this typically indicates a logic error)
      context - the execution context containing the command source, configuration, and other relevant state information, never null
      owning - the class where the exception originated, used for debugging and error logging purposes, may be null
      methodName - the name of the method where the exception occurred, used for debugging and error logging, may be null
      Returns:
      the unhandled exception if no handler was found, or null if the exception was handled successfully
      See Also: