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

Interface Paginator<T>

Type Parameters:
T - the source element type
All Known Implementing Classes:
NormalPagination, PatternPagination, ScrollPagination
@Internal public interface Paginator<T>
Internal page-source geometry engine: navigation, page-load dispatch and frame painting over a PaginationHost. This is the relocated 2.x Pagination interface, renamed because the public pagination.Pagination name now belongs to the reactive token.

  • Method Details

    • bind

      void bind(@NotNull @NotNull PaginationHost host)
      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 isLoading() true so the first paint shows the loading frame.

      Parameters:
      host - the world-facing seam the engine paints and renders through

    • insertPageItems

      void insertPageItems()
      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).

    • isCurrentPageEmpty

      boolean isCurrentPageEmpty()
      Reports whether the most recently settled page rendered no elements. Used by the host to decide whether to paint the empty-state frame.
      Returns:
      true when the current page has no elements

    • changePage

      void changePage(int page)
      Navigates directly to the given 1-indexed page.

      The target is clamped to at least 1, and to 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 refresh() to force a reload. Before bind(PaginationHost) the call only records the target page; bind dispatches the load for it.

      Parameters:
      page - the 1-indexed page to navigate to

    • nextPage

      void nextPage()
      Advances to the next page if one exists.

    • hasNextPage

      boolean hasNextPage()
      Returns whether forward navigation is possible.
      Returns:
      true if there is at least one page after the current one

    • previousPage

      void previousPage()
      Returns to the previous page if one exists.

    • hasPreviousPage

      boolean hasPreviousPage()
      Returns whether backward navigation is possible.
      Returns:
      true if there is at least one page before the current one

    • getTotalPages

      int getTotalPages()
      Returns the page count of the current source.

      Results are undefined before 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

    • getCurrentPage

      int getCurrentPage()
      Returns the current page.
      Returns:
      the 1-indexed current page number

    • getTotalElements

      int getTotalElements()
      Returns the element count of the current source.
      Returns:
      the total number of elements in the backing source, independent of how many are loaded locally

    • getItemPageLimit

      int getItemPageLimit()
      Returns the page capacity.

      Results are undefined before 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 maximum number of items rendered per page

    • getPageOfIndex

      int getPageOfIndex(int index)
      Maps a global source index onto the page it appears on.

      Results are undefined before 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())

    • isLoading

      boolean isLoading()
      Returns the in-flight state of the source.
      Returns:
      true while an async page load for this paginator is in flight; always false for eager sources

    • lastError

      @Nullable @Nullable Throwable lastError()
      Returns the most recent load failure.
      Returns:
      the failure of the most recent async page load, or null; cleared when a new load is dispatched. Always null for eager sources.

    • refresh

      void refresh()
      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.

    • replaceSource

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