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

Class PatternPagination<T>

java.lang.Object
tech.guilhermekaua.spigotboot.inventoryapi.internal.pagination.engine.PatternPagination<T>
Type Parameters:
T - the source element type
All Implemented Interfaces:
Paginator<T>
@Internal public class PatternPagination<T> extends Object
Paginates a source list across one or more Layout patterns, cycling through the patterns as the player pages forward. Each page renders a contiguous slice of the source whose length equals the slot count of that page's pattern, so every source item appears exactly once across the pages with no gaps or overlap.

The pattern controls only where and in what order items are placed: slots are filled in the order of the layout's Layout.slots() list, which lets a pattern lay items out horizontally, vertically, or in any custom order. Grid-based layouts derive that order from their letters; ordered-slots layouts state it explicitly.

Paginator.changePage(int) records the previous layout in lastPattern and clears its slots before rendering the new page, so cycling between patterns of different sizes leaves no residual items behind. Pages come from a PageSource: an in-memory list by default, or an async supplier configured by the declaring view.

  • Field Details

    • logger

      protected final Logger logger
      Named after the concrete class so warnings point at the actual pagination type.

    • fallbackItem

      protected final Supplier<RenderedItem> fallbackItem

    • itemFactory

      protected final PageItemFactory<T> itemFactory

    • loadingItem

      protected final Supplier<RenderedItem> loadingItem

    • pageSource

      protected PageSource<T> pageSource

    • host

      protected PaginationHost host

    • currentPage

      protected int currentPage

    • itemPageLimit

      protected int itemPageLimit

  • Constructor Details

    • PatternPagination

      public PatternPagination(@Nullable @Nullable Supplier<RenderedItem> fallbackItem, @NotNull @NotNull PageItemFactory<T> itemFactory, @NotNull @NotNull List<Layout> patterns)
      Creates an eager paginator over an initially empty source.
      Parameters:
      fallbackItem - item used for empty slots, may be null
      itemFactory - renders one source element, not null
      patterns - the layout patterns cycled across pages, not null or empty

    • PatternPagination

      public PatternPagination(@Nullable @Nullable Supplier<RenderedItem> fallbackItem, @NotNull @NotNull PageItemFactory<T> itemFactory, @NotNull @NotNull List<Layout> patterns, @Nullable @Nullable Supplier<RenderedItem> loadingItem, @NotNull @NotNull PageSource<T> pageSource)
      Creates a paginator over the given page source.
      Parameters:
      fallbackItem - item used for empty slots, may be null
      itemFactory - renders one source element, not null
      patterns - the layout patterns cycled across pages, not null or empty
      loadingItem - item rendered while an async load is in flight, may be null
      pageSource - where page items come from, not null
      Throws:
      NullPointerException - if pageSource is null

  • Method Details

    • initNavigationState

      protected void initNavigationState()
      Derives the layout state (page limit, pattern, ...) for the current page. Invoked by Paginator.bind(PaginationHost) after the host is bound and before the initial request dispatch.

    • requestOffset

      protected int requestOffset()
      Returns:
      the global element offset of the first item of the current page

    • restoreNavigation

      protected void restoreNavigation(tech.guilhermekaua.spigotboot.inventoryapi.internal.pagination.engine.PatternPagination.PatternState snapshot)
      Restores the navigation state captured by navigationSnapshot() after a failed load, including clearing anything the failed navigation already painted.
      Parameters:
      snapshot - the pre-dispatch navigation state

    • commitNavigation

      protected void commitNavigation(int target)
      Commits navigation to the already-clamped target page: updates the current page and any per-type layout state. Only invoked with a host bound.
      Parameters:
      target - the 1-indexed page to commit

    • renderLayout

      protected Layout renderLayout()
      Returns:
      the layout the current page renders into

    • getTotalPages

      public int getTotalPages()
      Description copied from interface: Paginator
      Returns the page count of the current source.

      Results are undefined before Paginator.bind(tech.guilhermekaua.spigotboot.inventoryapi.internal.pagination.PaginationHost): the page limit is derived from the layout at bind time (pre-init reads are answered by the binding, never by the engine).

      Returns:
      the total number of pages backing the current source, at least 1

    • getPageOfIndex

      public int getPageOfIndex(int index)
      Description copied from interface: Paginator
      Maps a global source index onto the page it appears on.

      Results are undefined before Paginator.bind(tech.guilhermekaua.spigotboot.inventoryapi.internal.pagination.PaginationHost): the page limit is derived from the layout at bind time (pre-init reads are answered by the binding, never by the engine).

      Parameters:
      index - the global element index
      Returns:
      the 1-indexed page containing the given index (for scroll paginators: the first page on which the index becomes visible), or -1 if the index is outside [0, getTotalElements())

    • bind

      public void bind(@NotNull @NotNull PaginationHost host)
      Description copied from interface: Paginator
      Binds the engine against a freshly opened host: sets the host, derives the navigation state for the current (possibly pre-recorded) page and dispatches the initial load without requesting a render — the open's initial paint covers it.

      Must be called once before any painting method is invoked. Eager sources settle inline during bind, so their items are ready before the first paint; async sources leave Paginator.isLoading() true so the first paint shows the loading frame.

      Specified by:
      bind in interface Paginator<T>
      Parameters:
      host - the world-facing seam the engine paints and renders through

    • nextPage

      public void nextPage()
      Description copied from interface: Paginator
      Advances to the next page if one exists.
      Specified by:
      nextPage in interface Paginator<T>

    • hasNextPage

      public boolean hasNextPage()
      Description copied from interface: Paginator
      Returns whether forward navigation is possible.
      Specified by:
      hasNextPage in interface Paginator<T>
      Returns:
      true if there is at least one page after the current one

    • previousPage

      public void previousPage()
      Description copied from interface: Paginator
      Returns to the previous page if one exists.
      Specified by:
      previousPage in interface Paginator<T>

    • hasPreviousPage

      public boolean hasPreviousPage()
      Description copied from interface: Paginator
      Returns whether backward navigation is possible.
      Specified by:
      hasPreviousPage in interface Paginator<T>
      Returns:
      true if there is at least one page before the current one

    • insertPageItems

      public void insertPageItems()
      Description copied from interface: Paginator
      Paints the items of the current page through PaginationHost.fillPage(java.util.List<tech.guilhermekaua.spigotboot.inventoryapi.internal.pagination.RenderedItem>, tech.guilhermekaua.spigotboot.inventoryapi.layout.Layout).
      Specified by:
      insertPageItems in interface Paginator<T>

    • isCurrentPageEmpty

      public boolean isCurrentPageEmpty()
      Description copied from interface: Paginator
      Reports whether the most recently settled page rendered no elements. Used by the host to decide whether to paint the empty-state frame.
      Specified by:
      isCurrentPageEmpty in interface Paginator<T>
      Returns:
      true when the current page has no elements

    • changePage

      public void changePage(int page)
      Description copied from interface: Paginator
      Navigates directly to the given 1-indexed page.

      The target is clamped to at least 1, and to Paginator.getTotalPages() once the backing source's totals are known. For async sources, navigation issued before the first load completes is honored optimistically and re-clamped downward when totals arrive. A call that targets the current page while a request for it is already in flight is ignored; use Paginator.refresh() to force a reload. Before Paginator.bind(PaginationHost) the call only records the target page; bind dispatches the load for it.

      Specified by:
      changePage in interface Paginator<T>
      Parameters:
      page - the 1-indexed page to navigate to

    • replaceSource

      public void replaceSource(@NotNull @NotNull PageSource<T> source)
      Description copied from interface: Paginator
      Swaps the backing source and clears the locally held items. Dispatches nothing and renders nothing — callers drive the re-request; a swap before Paginator.bind(PaginationHost) is picked up by the bind-time dispatch.
      Specified by:
      replaceSource in interface Paginator<T>
      Parameters:
      source - the new page source, not null

    • isLoading

      public boolean isLoading()
      Description copied from interface: Paginator
      Returns the in-flight state of the source.
      Specified by:
      isLoading in interface Paginator<T>
      Returns:
      true while an async page load for this paginator is in flight; always false for eager sources

    • lastError

      @Nullable public @Nullable Throwable lastError()
      Description copied from interface: Paginator
      Returns the most recent load failure.
      Specified by:
      lastError in interface Paginator<T>
      Returns:
      the failure of the most recent async page load, or null; cleared when a new load is dispatched. Always null for eager sources.

    • getTotalElements

      public int getTotalElements()
      Description copied from interface: Paginator
      Returns the element count of the current source.
      Specified by:
      getTotalElements in interface Paginator<T>
      Returns:
      the total number of elements in the backing source, independent of how many are loaded locally

    • refresh

      public void refresh()
      Description copied from interface: Paginator
      Re-requests the current page, invalidating any cached copy first. For async sources this is the supported idiom to re-query after the backing store changed; for eager sources it re-renders the current page.
      Specified by:
      refresh in interface Paginator<T>

    • emptyOrFallback

      @NotNull protected final @NotNull RenderedItem emptyOrFallback()
      Returns:
      the configured fallback item, or a slot clear when none was set

    • loadingOrFallback

      @NotNull protected final @NotNull RenderedItem loadingOrFallback()
      Returns:
      the configured loading item, falling back to emptyOrFallback()