Package studio.mevera.imperat.context

Class ExecutionResult<S extends Source>

java.lang.Object
studio.mevera.imperat.context.ExecutionResult<S>
Type Parameters:
S - the type of command source that extends Source, representing the entity that initiated the command execution (e.g., Player, Console)
public final class ExecutionResult<S extends Source> extends Object
Represents the result of a command execution operation in the Imperat framework.

This class follows a Result/Either pattern, encapsulating either a successful command execution with its associated context and search results, or a failure state with error information. This design allows for safe error handling without throwing exceptions during command processing.

Usage Examples:


 // Creating a successful result
 ExecutionResult<MySource> success = ExecutionResult.of(context, search);

 // Creating a failure result with specific error
 ExecutionResult<MySource> failure = ExecutionResult.failure(new IllegalArgumentException("Invalid command"));

 // Creating a generic failure result
 ExecutionResult<MySource> genericFailure = ExecutionResult.failure();

 // Checking and handling results
 if (result.hasFailed()) {
     Throwable error = result.getError(); // May be null for generic failures
     // Handle error case
 } else {
     ExecutionContext<MySource> context = result.getContext();
     CommandPathSearch<MySource> search = result.getSearch();
     // Process successful execution
 }

Thread Safety: This class is immutable and thread-safe once constructed.

Since:
1.0.0
See Also:

  • Method Details

    • of

      public static <S extends Source> ExecutionResult<S> of(ExecutionContext<S> executionContext, CommandPathSearch<S> search, Context<S> context)
      Creates a successful execution result with the provided context and search results.

      This factory method should be used when a command has been successfully parsed and executed without errors. The resulting ExecutionResult will contain the execution context and command path search information.

      Type Parameters:
      S - the type of command source
      Parameters:
      context - the execution context containing command execution data
      search - the command path search result containing parsing and matching information
      Returns:
      a new ExecutionResult instance representing successful execution
      Throws:
      IllegalArgumentException - if either context or search is null
      See Also:

    • failure

      public static <S extends Source> ExecutionResult<S> failure(@Nullable @Nullable Throwable error, Context<S> context)
      Creates a failed execution result with the provided error information.

      This factory method should be used when a command execution has failed due to parsing errors, validation failures, runtime exceptions, or other error conditions. The resulting ExecutionResult will contain only the error information, with context and search fields being null.

      Type Parameters:
      S - the type of command source
      Parameters:
      error - the exception or error that caused the execution failure, may be null to represent a generic failure without specific error details
      Returns:
      a new ExecutionResult instance representing failed execution
      See Also:

    • failure

      public static <S extends Source> ExecutionResult<S> failure(Context<S> context)
      Creates a failed execution result without specific error information.

      This is a convenience factory method that creates a generic failure result when no specific error details are available or needed. This is equivalent to calling failure(null) but provides cleaner, more readable code for cases where the failure is expected or the specific error is not relevant.

      Use Cases:

      • Command validation failures where the error message is handled elsewhere
      • Permission checks that simply succeed or fail without detailed error info
      • Generic failure states where the context provides sufficient information

      Example:

      
 // Instead of writing:
 return ExecutionResult.failure(null);

 // You can write:
 return ExecutionResult.failure();

 // Usage in conditional logic:
 if (!hasPermission(source)) {
     return ExecutionResult.failure(); // Clean, readable failure
 }
      Type Parameters:
      S - the type of command source
      Returns:
      a new ExecutionResult instance representing a generic failed execution
      See Also:

    • hasFailed

      public boolean hasFailed()
      Determines whether this execution result represents a failed command execution.

      An execution is considered failed if either the execution context or command path search is null, which occurs when the result was created using the failure(Throwable, Context) factory method.

      Note: A failed result may or may not have associated error information accessible via getError().

      Returns:
      true if the command execution failed, false if it succeeded
      See Also:

    • getError

      @Nullable public @Nullable Throwable getError()
      Returns the error that caused the command execution to fail, if any.

      This method returns the exception or error information associated with a failed execution. For successful executions (where hasFailed() returns false), this method will return null.

      Note: Even for failed executions, the error may be null if the failure was created without specific error details.

      Returns:
      the error that caused execution failure, or null if no specific error information is available or if the execution succeeded
      See Also:

    • getContext

      public Context<S> getContext()

    • getSearch

      public CommandPathSearch<S> getSearch()
      Returns the command path search result containing parsing and matching information.

      This method provides access to the CommandPathSearch instance that contains information about how the command was parsed, which command path was matched, and any argument parsing results.

      Important: This method should only be called on successful execution results. For failed executions (where hasFailed() returns true), this method will return null.

      Returns:
      the command path search result for successful executions, or null for failed executions
      Throws:
      IllegalStateException - if called on a failed execution result (optional runtime check, implementation-dependent)
      See Also:

    • getExecutionContext

      public ExecutionContext<S> getExecutionContext()
      Returns the execution context containing command execution data and environment.

      This method provides access to the ExecutionContext instance that contains the command source, parsed arguments, execution environment, and other contextual information needed for command processing.

      Important: This method should only be called on successful execution results. For failed executions (where hasFailed() returns true), this method will return null.

      Returns:
      the execution context for successful executions, or null for failed executions
      Throws:
      IllegalStateException - if called on a failed execution result (optional runtime check, implementation-dependent)
      See Also: