Class MazeOperationFailedEvent

java.lang.Object
org.bukkit.event.Event
dev.despical.mazeengine.api.event.MazeOperationFailedEvent
public final class MazeOperationFailedEvent extends org.bukkit.event.Event
Called when an accepted maze operation ends with failure or cancellation.

This event is fired synchronously on the server thread after the operation's reservation has been released. It is not cancellable and does not indicate that world changes were rolled back. Blocks may already have been modified, and a failed record may remain for recovery.

The last known maze description can be absent when creation failed during topology planning, before a record existed. A description may also refer to a failed preparation record that has already been removed from the registry. Use maze() to inspect the retained description when available.

Typical use cases:

  • Logging the operation identity and underlying failure
  • Distinguishing cancellation from a generation or persistence error
  • Offering recovery actions for a retained failed maze
Requests rejected synchronously before submission do not fire this event. Their validation exception is delivered directly to the API caller.

  • Nested Class Summary

    Nested classes/interfaces inherited from class org.bukkit.event.Event

    org.bukkit.event.Event.Result

  • Constructor Summary

    Constructors
    Constructor
    Description
    MazeOperationFailedEvent(UUID operationId, MazeId mazeId, OperationKind kind, MazeSnapshot maze, Throwable cause)
    Constructs a terminal event using the last known maze directly.

  • Method Summary

    Modifier and Type
    Method
    Description
    Throwable
    cause()
    Returns the underlying error that ended the operation.
    static org.bukkit.event.HandlerList
    getHandlerList()
    Returns the static registry required for Bukkit listener registration.
    @NotNull org.bukkit.event.HandlerList
    getHandlers()
    Returns the listener registry used to dispatch this event.
    OperationKind
    kind()
    Returns the action that was being attempted.
    Optional<MazeSnapshot>
    maze()
    Returns the last known maze description, when available.
    MazeId
    mazeId()
    Returns the name the operation targeted.
    UUID
    operationId()
    Returns the identity of the operation that ended.

    Methods inherited from class org.bukkit.event.Event

    callEvent, getEventName, isAsynchronous

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • MazeOperationFailedEvent

      public MazeOperationFailedEvent(UUID operationId, MazeId mazeId, OperationKind kind, MazeSnapshot maze, Throwable cause)
      Constructs a terminal event using the last known maze directly.

      Pass null for the maze when no record was produced. Callers do not need to wrap constructor arguments in Optional; maze() exposes absence to event consumers. Constructing the event does not dispatch it.

      Parameters:
      operationId - the identity of the failed operation
      mazeId - the target maze name
      kind - the requested operation kind
      maze - the last known description, or null when no record existed
      cause - the underlying failure or cancellation
      Throws:
      NullPointerException - if any required identity, kind, or cause is null

  • Method Details

    • operationId

      public UUID operationId()
      Returns the identity of the operation that ended.

      Use this UUID to correlate failure with a handle or earlier progress sample, even if the target name is reused.

      Returns:
      the failed operation UUID

    • mazeId

      public MazeId mazeId()
      Returns the name the operation targeted.

      This identifier is present even when creation planning produced no record. It does not indicate whether a maze currently exists under that name.

      Returns:
      the normalized target maze identifier

    • kind

      public OperationKind kind()
      Returns the action that was being attempted.

      The kind remains the originally submitted action after failure or cancellation; it does not identify the internal stage that failed.

      Returns:
      the requested operation kind

    • maze

      public Optional<MazeSnapshot> maze()
      Returns the last known maze description, when available.

      The description may belong to a removed preparation record. An empty result means the operation ended before it had a record to describe.

      Returns:
      the retained description, or empty when no record existed

    • cause

      public Throwable cause()
      Returns the underlying error that ended the operation.

      Completion and execution wrapper exceptions are unwrapped by the provider. Cancellation and shutdown use CancellationException; other causes may indicate planning, protection, storage, or block-work failures.

      Returns:
      the terminal failure or cancellation cause

    • getHandlers

      @NotNull public @NotNull org.bukkit.event.HandlerList getHandlers()
      Returns the listener registry used to dispatch this event.

      The same registry is shared by all instances of this event class.

      Specified by:
      getHandlers in class org.bukkit.event.Event
      Returns:
      the Bukkit handler list for this event type

    • getHandlerList

      public static org.bukkit.event.HandlerList getHandlerList()
      Returns the static registry required for Bukkit listener registration.

      Bukkit uses this method to associate registered listeners with this event type before any event instance is dispatched.

      Returns:
      the Bukkit handler list shared by this event class