Package dev.sympho.modular_commands.api.command.handler

Interface InvocationHandler<C extends @NonNull CommandContext>

Type Parameters:
C - The context type.
All Superinterfaces:
Function<C,Mono<CommandResult>>
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface InvocationHandler<C extends @NonNull CommandContext> extends Function<C,Mono<CommandResult>>
A function that handles the execution of a command.
Since:
1.0
Version:
1.0

  • Method Details

    • handle

      Mono<CommandResult> handle(C context) throws ResultException, Exception
      Handles an invocation of the command.
      Parameters:
      context - The invocation context.
      Returns:
      The invocation result. It may result in an error (exception) if an error occured during handling (same as if this handler threw the exception directly). This includes ResultException.

      The returned Mono may also finish empty, in which case handling continues with the next handler in the execution chain. Care should be taken that this only occurs if there is a next handler; an empty result from the last handler in the chain will cause an error.

      Throws:
      ResultException - if execution finishes early. This is equivalent to returning the result, but should only be used when returning directly is impractical.
      Exception - if an error occurred during handling.
      API Note:
      A handler is allowed to throw checked exceptions in order to simplify error handling. If an exception occurs, the usual course of action would be to return it as an exception result. Thus, it makes more sense to allow it to propagate up, then have the centralized handler automatically wrap the exception into an error, rather than clutter every handler with similar exception handling just for that purpose.

      If an exception requires handling to avoid leaving the system in an inconsistent or dangerous state, it may be implemented either in the handler itself, or in a ResultHandler that detects and handles the resulting error.

      The same logic applies to the returned Mono being allowed to result in an error. Of course, in that case there is no way to allow checked exceptions, so those would still need to be wrapped into an unchecked exception or manually returned as an exception result.

    • handleWrapped

      default Mono<CommandResult> handleWrapped(C context)
      Handles an invocation of the command using handle(CommandContext), automatically converting any exception thrown in that method or issued in the resulting mono to an exception result (with the exception of a ResultException, which is unpacked into the contained result).
      Parameters:
      context - The invocation context.
      Returns:
      The invocation result. The returned Mono is guaranteed to not contain an error.
      Implementation Requirements:
      Do not override this.

    • apply

      default Mono<CommandResult> apply(C context)
      Specified by:
      apply in interface Function<C extends @NonNull CommandContext,Mono<CommandResult>>
      Implementation Requirements:
      Delegates to handleWrapped(CommandContext). Do not override.