Package de.bsommerfeld.pathetic.api.pathing

Interface PathfindingSearch

public interface PathfindingSearch
Represents a pathfinding operation that can be configured with callbacks for different outcomes. This interface provides methods to handle successful results, failures, and exceptions, as well as the ability to abort the operation.
Since:
5.4.4

  • Method Details

    • ifPresent

      PathfindingSearch ifPresent(Consumer<PathfinderResult> callback)
      Executes the given callback if the pathfinding operation results in a successful path or a fallback.
      Parameters:
      callback - the callback to execute if the pathfinding operation is successful or results in a fallback
      Returns:
      this PathfindingSearch instance for method chaining

    • orElse

      PathfindingSearch orElse(Consumer<PathfinderResult> callback)
      Executes the given callback if the pathfinding operation results in a failure, abortion, length limitation, or reaching maximum iterations.
      Parameters:
      callback - the callback to execute if the pathfinding operation fails, is aborted, reaches length limitation, or maximum iterations
      Returns:
      this PathfindingSearch instance for method chaining

    • exceptionally

      PathfindingSearch exceptionally(Consumer<Throwable> callback)
      Executes the given callback if the pathfinding operation results in an exception.

      The callback is purely observational. The search stays in its exceptional state afterwards - resultBlocking() will still throw and result() will still return Optional.empty().

      Parameters:
      callback - the callback to execute if the pathfinding operation results in an exception
      Returns:
      this PathfindingSearch instance for method chaining

    • resultBlocking

      PathfinderResult resultBlocking()
      Blocks until the pathfinding operation completes and returns the result.

      If the operation completed exceptionally, this method throws a CompletionException whose cause is the original error. External cancellation surfaces as a CancellationException. Use result() if you prefer an empty Optional over a thrown exception.

      Returns:
      the PathfinderResult representing the outcome of the pathfinding operation, including success, failure, or fallback states, along with the generated path.
      Since:
      5.4.6

    • result

      Optional<PathfinderResult> result()
      Retrieves the result of the pathfinding operation if it has completed normally.

      Returns Optional.empty() when the operation has not yet completed, was cancelled, or completed exceptionally. Use resultBlocking() if you want the exception to propagate instead of being swallowed.

      Returns:
      an Optional containing the PathfinderResult on normal completion, empty otherwise.
      Since:
      5.4.6

    • done

      boolean done()
      Checks if the pathfinding operation has completed.

      This method returns a boolean indicating whether the pathfinding process has finished. Completion could mean success, failure, or the operation being aborted. It allows determining if the operation's result can be retrieved or further actions should be performed based on its state.

      Returns:
      true if the pathfinding operation is complete; false otherwise.
      Since:
      5.4.6

    • abort

      void abort()
      Aborts the pathfinding operation if it is still in progress.

      This method uses cooperative cancellation. Instead of abruptly terminating the execution thread, it signals the pathfinder to gracefully stop at the next available opportunity (usually the start of the next iteration). This ensures that internal resources are released and cleanup logic is executed correctly.