Interface MazeOperation

public interface MazeOperation
Tracks exactly one accepted world-editing operation.

The handle's UUID identifies the operation independently of its maze name. It retains its terminal state even if that name is later deleted or used by another operation. Identity, kind, and completion can be retained; progress and cancellation must be accessed on the server thread.

Use completion() to observe the final result without blocking the server thread. Cancelling a CompletableFuture obtained from that stage does not stop world work; use cancel(CommandSender) to request cancellation.

A failure or cancellation may leave partially changed blocks and a recoverable failed record. A successful result means the world operation and final persistence finished; it does not mean the actor was teleported.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    cancel(org.bukkit.command.CommandSender actor)
    Requests cancellation of this exact operation on the server thread.
    CompletionStage<OperationResult>
    completion()
    Returns a read-only stage representing this operation's final outcome.
    UUID
    id()
    Returns the unique identity assigned to this accepted operation.
    OperationKind
    kind()
    Returns the action this operation was submitted to perform.
    MazeId
    mazeId()
    Returns the normalized maze name targeted by this operation.
    OperationProgress
    progress()
    Captures the current progress of this operation on the server thread.

  • Method Details

    • id

      UUID id()
      Returns the unique identity assigned to this accepted operation.

      The identity remains unchanged after completion. Another operation targeting the same maze name receives a different UUID.

      Returns:
      this operation's UUID

    • mazeId

      MazeId mazeId()
      Returns the normalized maze name targeted by this operation.

      During creation planning, a handle can target a name for which the registry does not yet contain a maze record.

      Returns:
      the target maze identifier

    • kind

      OperationKind kind()
      Returns the action this operation was submitted to perform.

      The kind distinguishes creation, full regeneration, structural repair, and removal. It does not change as the operation advances through stages.

      Returns:
      the submitted operation kind

    • progress

      OperationProgress progress()
      Captures the current progress of this operation on the server thread.

      The returned value is immutable and does not update itself. Once terminal, the handle returns its retained final state even after the name is reused. Use state for lifecycle decisions; stage text is intended for diagnostics.

      Returns:
      a point-in-time progress sample
      Throws:
      IllegalStateException - if called off the server thread

    • completion

      CompletionStage<OperationResult> completion()
      Returns a read-only stage representing this operation's final outcome.

      Success completes with the final maze description after persistence and reservation release. Failure completes exceptionally with its underlying cause; cancellation uses CancellationException. Never call blocking join() or get() on the server thread.

      Completion is published on the server thread. A callback attached after completion may run on the attaching thread, and asynchronous callbacks use their executor. Schedule Bukkit work explicitly whenever needed.

      Changing or cancelling a future derived from this stage does not cancel the operation itself. Use cancel(CommandSender) for world-work cancellation.

      Returns:
      the operation's read-only completion stage

    • cancel

      boolean cancel(org.bukkit.command.CommandSender actor)
      Requests cancellation of this exact operation on the server thread.

      The actor must satisfy the plugin's cancellation permission and ownership rules. A handle for an ended operation returns false and cannot cancel a newer operation using the same maze name.

      Cancellation is not a rollback guarantee. A maze whose blocks have already changed may remain as a failed record requiring recovery or removal.

      Parameters:
      actor - the sender requesting cancellation
      Returns:
      true when cancellation was requested, or false when this operation has ended
      Throws:
      IllegalArgumentException - if the actor lacks cancellation permission or ownership rights
      IllegalStateException - if called off the server thread or the plugin is disabled