Package tech.guilhermekaua.spigotboot.inventoryapi.internal.pagination

Class PaginationBinding

java.lang.Object
tech.guilhermekaua.spigotboot.inventoryapi.internal.pagination.PaginationBinding
All Implemented Interfaces:
PaginationHost
@Internal public final class PaginationBinding extends Object implements PaginationHost
Per-(session, token) pagination runtime: records pre-init navigation, builds the per-context page source and geometry engine at open time, owns the page-element components of the current frame and implements the PaginationHost seam the relocated engine paints and settles through.

The binding deliberately does not reference PaginationImpl — the dependency points the other way (the token resolves its binding from the session's state store); the binding works on the immutable PaginationSpec and its token id alone. The spec's T and the paginator's T originate from the same paginate* declaration, so the binding pairs them internally on Object through a documented unchecked cast. Renderer, fallback, loading and lazy-source functions are evaluated against one PlainViewContextImpl the binding creates at initialize time.

Renderer, fallback and loading failures are swallowed and logged at most once per minute per binding (§9 error table); the affected slot keeps its previous content, or shows the fallback item (or clears) when it never held content.

  • Constructor Details

    • PaginationBinding

      public PaginationBinding(@NotNull @NotNull PaginationSpec<?> spec, int tokenId, @NotNull @NotNull ViewSession session, @NotNull @NotNull ViewEngine engine)
      Creates the binding for one pagination token of one session.
      Parameters:
      spec - the immutable pagination declaration of the token
      tokenId - the token id assigned by the owning view's token table
      session - the session this binding belongs to
      engine - the engine providing the painter, the settle entry point and the plugin

  • Method Details

    • pendingTarget

      public int pendingTarget()
      Returns the page navigation will land on once the binding initializes.
      Returns:
      the pending 1-indexed target page; 1 until a navigation was recorded

    • recordSwitchTo

      public void recordSwitchTo(int target)
      Records a pre-init navigation target; consumed once by initialize(tech.guilhermekaua.spigotboot.inventoryapi.internal.layout.ResolvedLayout, tech.guilhermekaua.spigotboot.inventoryapi.config.ViewConfig).
      Parameters:
      target - the requested 1-indexed page; clamped to at least 1

    • hasPendingNavigation

      public boolean hasPendingNavigation()
      Returns whether a pre-init navigation was recorded.
      Returns:
      true once recordSwitchTo(int) ran before initialize(tech.guilhermekaua.spigotboot.inventoryapi.internal.layout.ResolvedLayout, tech.guilhermekaua.spigotboot.inventoryapi.config.ViewConfig)

    • initialize

      public void initialize(@NotNull @NotNull ResolvedLayout viewLayout, @NotNull @NotNull ViewConfig effectiveConfig)
      Builds the per-context runtime: resolves and validates the fill target, creates the per-context page source and the geometry engine, replays any pending navigation on the still-unbound paginator (the preserved 2.x record-only branch) and binds the engine to this host — which dispatches the initial page load. Eager sources settle inline here so their items are ready before the open's first paint; async sources stay loading so the first paint shows the loading frame.
      Parameters:
      viewLayout - the session's resolved config layout
      effectiveConfig - the session's effective config
      Throws:
      ViewConfigurationException - when the layout char resolves to no slots, the explicit layout is empty, or an explicit layout or pattern slot lies outside the container

    • isInitialized

      public boolean isInitialized()
      Returns whether initialize(tech.guilhermekaua.spigotboot.inventoryapi.internal.layout.ResolvedLayout, tech.guilhermekaua.spigotboot.inventoryapi.config.ViewConfig) completed and the geometry engine is bound.
      Returns:
      true once the paginator exists

    • paginator

      @Nullable public @Nullable Paginator<?> paginator()
      Returns the bound geometry engine.
      Returns:
      the paginator, or null before initialize(tech.guilhermekaua.spigotboot.inventoryapi.internal.layout.ResolvedLayout, tech.guilhermekaua.spigotboot.inventoryapi.config.ViewConfig) completed

    • targetSlots

      @NotNull public @org.jetbrains.annotations.NotNull int[] targetSlots()
      Returns the slots this binding paints into: the fill layout's slots for normal and scroll geometry, the union of all pattern slots for pattern geometry.
      Returns:
      a defensive copy of the resolved fill slots; empty before initialize(tech.guilhermekaua.spigotboot.inventoryapi.internal.layout.ResolvedLayout, tech.guilhermekaua.spigotboot.inventoryapi.config.ViewConfig)

    • frameSlots

      @NotNull public @org.jetbrains.annotations.NotNull int[] frameSlots()
      Returns the empty-state and loading frame slots this binding paints into, de-duplicated.
      Returns:
      a defensive copy of the frame slots; empty before initialize(tech.guilhermekaua.spigotboot.inventoryapi.internal.layout.ResolvedLayout, tech.guilhermekaua.spigotboot.inventoryapi.config.ViewConfig) or when no frame slots are declared

    • componentAt

      @Nullable public @Nullable ComponentInstance componentAt(int slot)
      Returns the page-element component currently occupying a slot.
      Parameters:
      slot - the raw container slot
      Returns:
      the element component, or null when the slot holds none

    • repaint

      public void repaint()
      Repaints the whole pagination area from the engine's current frame.

    • elementWatchersOf

      @NotNull public @NotNull List<ComponentInstance> elementWatchersOf(@NotNull @NotNull Set<Integer> dirtyTokenIds)
      Returns the current page-element components watching any of the given token ids.
      Parameters:
      dirtyTokenIds - the dirty token ids of a state flush
      Returns:
      the matching element components, each at most once, in fill order

    • tokenId

      public int tokenId()
      Returns the id of the pagination token this binding belongs to.
      Returns:
      the token id

    • refreshLazy

      public void refreshLazy(@NotNull @NotNull ViewContext context)
      Re-invokes a lazy eager source's function against the given context, replaces the paginator's source with a fresh eager source over the result and re-requests the current page (forced).
      Parameters:
      context - the context the lazy source function is evaluated against
      Throws:
      IllegalStateException - when the binding's source is not a lazy eager source

    • isActive

      public boolean isActive()
      Description copied from interface: PaginationHost
      Returns whether the bound session is currently paintable.
      Specified by:
      isActive in interface PaginationHost
      Returns:
      true while the session status is ACTIVE or TRANSITIONING

    • fillPage

      public void fillPage(@NotNull @NotNull List<RenderedItem> items, @NotNull @NotNull Layout layout)
      Description copied from interface: PaginationHost
      Applies one engine frame: item i is mapped onto layout.slots().get(i).
      Specified by:
      fillPage in interface PaginationHost
      Parameters:
      items - the rendered slot contents, one per layout slot
      layout - the fill order the items map onto

    • requestRender

      public void requestRender()
      Description copied from interface: PaginationHost
      Requests a reactive settle pass for the owning token: the engine repaints the token's pagination area and every component watching the token.
      Specified by:
      requestRender in interface PaginationHost

    • playerId

      @Nullable public @Nullable UUID playerId()
      Description copied from interface: PaginationHost
      Returns the player pages are being loaded for; populates the slim PageRequest.
      Specified by:
      playerId in interface PaginationHost
      Returns:
      the viewing player's id; production hosts never return null (test fixtures may)

    • player

      @NotNull public @NotNull org.bukkit.entity.Player player()
      Description copied from interface: PaginationHost
      Returns the live viewer the settle dispatcher uses to route the settle to the correct region thread. Production hosts always return the session's player; test fixtures may return null to trigger the inline-settle path.
      Specified by:
      player in interface PaginationHost
      Returns:
      the viewing player, or null for test fixtures

    • plugin

      @NotNull public @NotNull org.bukkit.plugin.Plugin plugin()
      Description copied from interface: PaginationHost
      Returns the plugin that owns the view; asynchronously completed settles are scheduled through it.
      Specified by:
      plugin in interface PaginationHost
      Returns:
      the owning plugin