Package tech.guilhermekaua.spigotboot.inventoryapi.internal.engine

Class ViewEngine

java.lang.Object
tech.guilhermekaua.spigotboot.inventoryapi.internal.engine.ViewEngine
@Internal public final class ViewEngine extends Object
Orchestrator of the view lifecycle: composes the fixed-order phase handlers and is the sole mutator of sessions. All entry points assert that the calling thread owns the viewer's region.

  • Constructor Summary

    Constructors
    Constructor
    Description
    ViewEngine(@NotNull org.bukkit.plugin.Plugin plugin, @NotNull ViewRegistry views, @NotNull SessionRegistry sessions, @NotNull SlotPainter painter, @NotNull TitleUpdater titleUpdater, @NotNull PlatformScheduler scheduler)
    Creates the engine and its phase handlers.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    bukkitClose(@NotNull ViewSession session, @NotNull org.bukkit.event.inventory.InventoryCloseEvent event)
    Handles a Bukkit close event for a session, guarded by container identity: a close event for a previous container (fired synchronously while opening a new view) must not tear down the session of the view that is being opened.
    void
    click(@NotNull ViewSession session, @NotNull org.bukkit.event.inventory.InventoryClickEvent event)
    Routes a Bukkit click event into the session per the click policy.
    void
    clickDispatch(boolean active)
    Marks the engine as inside or outside click dispatch; toggled by click(tech.guilhermekaua.spigotboot.inventoryapi.internal.session.ViewSession, org.bukkit.event.inventory.InventoryClickEvent) around routing.
    void
    close(@NotNull ViewSession session, @NotNull CloseReason reason)
    Closes a session with the given reason; idempotent on already closed sessions.
    void
    defer(@NotNull ViewSession session, @NotNull Runnable op)
    Defers an operation to the end of the current tick.
    void
    drag(@NotNull ViewSession session, @NotNull org.bukkit.event.inventory.InventoryDragEvent event)
    Applies the drag policy of a session: when cancelOnDrag is enabled, any drag touching the top container is cancelled (mirrors the 2.x listener behavior).
    void
    flushDirty(@NotNull ViewSession session)
    Flushes dirty state tokens of a session: each pass drains the dirty set and runs a STATE_CHANGE update over the watchers; passes repeat while handlers re-dirty tokens, capped at 8 cascades per flush, after which the remaining dirty tokens are dropped with a WARNING.
    void
    flushShared(@NotNull View owner)
    Runs a full STATE_CHANGE repaint pass on every active session of the given view; full-pass fallback — the wired hooks use the watcher-scoped overload.
    boolean
    isInClickDispatch()
    Returns whether a click event is currently being dispatched (drives operation deferral).
    void
    open(@NotNull org.bukkit.entity.Player player, @NotNull Class<? extends View> viewType, @NotNull ViewArguments arguments)
    Opens a registered view for a player, replacing any previous session at the commit point (spec §7).
    void
    paginationSettle(@NotNull ViewSession session, int tokenId)
    Runs a pagination-settle update pass scoped to the settled token, then flushes any state the handlers dirtied.
    @NotNull SlotPainter
    painter()
    Returns the slot painter used by the rendering phases; pagination bindings paint their page frames through it.
    @NotNull org.bukkit.plugin.Plugin
    plugin()
    Returns the plugin owning the inventory-api runtime.
    @NotNull PlatformScheduler
    scheduler()
    Returns the platform scheduler used by this engine.
    @NotNull TitleUpdater
    titleUpdater()
    Returns the in-place title update strategy.
    void
    update(@NotNull ViewSession session, @NotNull UpdateTrigger trigger)
    Runs an update pass on a session, then flushes any state the handlers dirtied.
    void
    updateTitle(@NotNull ViewSession session, @NotNull String title)
    Updates the container title of a session in place: placeholders are applied for the session's player when the effective config enables them, then legacy & color codes are translated, and the result is handed to the TitleUpdater.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • ViewEngine

      public ViewEngine(@NotNull @NotNull org.bukkit.plugin.Plugin plugin, @NotNull @NotNull ViewRegistry views, @NotNull @NotNull SessionRegistry sessions, @NotNull @NotNull SlotPainter painter, @NotNull @NotNull TitleUpdater titleUpdater, @NotNull @NotNull PlatformScheduler scheduler)
      Creates the engine and its phase handlers.
      Parameters:
      plugin - the plugin owning the inventory-api runtime
      views - the view registry
      sessions - the per-player session registry
      painter - the slot painter used by the rendering phases
      titleUpdater - the in-place title update strategy
      scheduler - the platform scheduler

  • Method Details

    • open

      public void open(@NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull Class<? extends View> viewType, @NotNull @NotNull ViewArguments arguments)
      Opens a registered view for a player, replacing any previous session at the commit point (spec §7). Self-defers to end of tick during click dispatch, so service-path opens made from a click handler never tear down the clicked session mid-dispatch; the registration check then runs when the deferred open executes.
      Parameters:
      player - the viewer
      viewType - the registered view class
      arguments - the open arguments
      Throws:
      UnknownViewException - when the view class is not registered
      IllegalArgumentException - when an initialState argument has a mismatching type
      IllegalStateException - when called off the thread owning the viewer's region

    • close

      public void close(@NotNull @NotNull ViewSession session, @NotNull @NotNull CloseReason reason)
      Closes a session with the given reason; idempotent on already closed sessions. Self-defers to end of tick during click dispatch, so service-path closes made from a click handler never tear down the clicked session mid-dispatch.
      Parameters:
      session - the session to close
      reason - the close reason

    • updateTitle

      public void updateTitle(@NotNull @NotNull ViewSession session, @NotNull @NotNull String title)
      Updates the container title of a session in place: placeholders are applied for the session's player when the effective config enables them, then legacy & color codes are translated, and the result is handed to the TitleUpdater.
      Parameters:
      session - the session whose container title is updated
      title - the new title, legacy color codes supported
      Throws:
      IllegalStateException - when called off the thread owning the viewer's region

    • update

      public void update(@NotNull @NotNull ViewSession session, @NotNull @NotNull UpdateTrigger trigger)
      Runs an update pass on a session, then flushes any state the handlers dirtied.
      Parameters:
      session - the session to update
      trigger - the cause of the update

    • paginationSettle

      public void paginationSettle(@NotNull @NotNull ViewSession session, int tokenId)
      Runs a pagination-settle update pass scoped to the settled token, then flushes any state the handlers dirtied. ACTIVE and TRANSITIONING sessions receive the settle; CLOSED and OPENING sessions drop it entirely — no paint, no watcher marking, no onUpdate (§7).
      Parameters:
      session - the session whose pagination token settled
      tokenId - the token id of the settled pagination declaration
      Throws:
      IllegalStateException - when called off the thread owning the viewer's region

    • click

      public void click(@NotNull @NotNull ViewSession session, @NotNull @NotNull org.bukkit.event.inventory.InventoryClickEvent event)
      Routes a Bukkit click event into the session per the click policy. Context close()/openView() calls and component post-actions made while this method runs are deferred to end of tick; dirty state written by handlers is flushed after dispatch completes.
      Parameters:
      session - the clicked session
      event - the Bukkit event

    • drag

      public void drag(@NotNull @NotNull ViewSession session, @NotNull @NotNull org.bukkit.event.inventory.InventoryDragEvent event)
      Applies the drag policy of a session: when cancelOnDrag is enabled, any drag touching the top container is cancelled (mirrors the 2.x listener behavior).
      Parameters:
      session - the affected session
      event - the Bukkit event

    • bukkitClose

      public void bukkitClose(@NotNull @NotNull ViewSession session, @NotNull @NotNull org.bukkit.event.inventory.InventoryCloseEvent event)
      Handles a Bukkit close event for a session, guarded by container identity: a close event for a previous container (fired synchronously while opening a new view) must not tear down the session of the view that is being opened.
      Parameters:
      session - the player's session
      event - the Bukkit event

    • flushDirty

      public void flushDirty(@NotNull @NotNull ViewSession session)
      Flushes dirty state tokens of a session: each pass drains the dirty set and runs a STATE_CHANGE update over the watchers; passes repeat while handlers re-dirty tokens, capped at 8 cascades per flush, after which the remaining dirty tokens are dropped with a WARNING.
      Parameters:
      session - the session to flush

    • flushShared

      public void flushShared(@NotNull @NotNull View owner)
      Runs a full STATE_CHANGE repaint pass on every active session of the given view; full-pass fallback — the wired hooks use the watcher-scoped overload.
      Parameters:
      owner - the view singleton whose sessions should flush

    • defer

      public void defer(@NotNull @NotNull ViewSession session, @NotNull @NotNull Runnable op)
      Defers an operation to the end of the current tick. The session leaves ACTIVE immediately (TRANSITIONING) so further clicks are swallowed until the operation runs; sessions still TRANSITIONING after the drain return to ACTIVE. Every queued operation is guarded so it no-ops when the session was closed before the tick ran (manual close, disconnect, plugin disable, or an earlier deferred operation queued by the same click).
      Parameters:
      session - the session the operation belongs to
      op - the operation to run at end of tick

    • isInClickDispatch

      public boolean isInClickDispatch()
      Returns whether a click event is currently being dispatched (drives operation deferral).
      Returns:
      true while a click is being dispatched

    • clickDispatch

      @Internal public void clickDispatch(boolean active)
      Marks the engine as inside or outside click dispatch; toggled by click(tech.guilhermekaua.spigotboot.inventoryapi.internal.session.ViewSession, org.bukkit.event.inventory.InventoryClickEvent) around routing.
      Parameters:
      active - true while a click is being dispatched

    • painter

      @NotNull public @NotNull SlotPainter painter()
      Returns the slot painter used by the rendering phases; pagination bindings paint their page frames through it.
      Returns:
      the slot painter

    • plugin

      @NotNull public @NotNull org.bukkit.plugin.Plugin plugin()
      Returns the plugin owning the inventory-api runtime.
      Returns:
      the owning plugin

    • scheduler

      @NotNull public @NotNull PlatformScheduler scheduler()
      Returns the platform scheduler used by this engine.
      Returns:
      the platform scheduler

    • titleUpdater

      @NotNull public @NotNull TitleUpdater titleUpdater()
      Returns the in-place title update strategy.
      Returns:
      the title updater