Package tech.guilhermekaua.spigotboot.inventoryapi.pagination

Interface Pagination<T>

Type Parameters:
T - the element type served by the backing page source
All Superinterfaces:
StateToken
All Known Implementing Classes:
PaginationImpl
@NonExtendable public interface Pagination<T> extends StateToken
Reactive pagination token, declared once per view through the View.paginate* factories and built by PaginationBuilder.build(). The token itself holds no paging state: every method reads or mutates the state of the session behind the given ViewContext, so a single declaration serves every viewer with fully isolated per-context paging.

As a StateToken the token can be watched via ItemComponentBuilder.updateOnStateChange(StateToken...): watching components re-render whenever a page load settles or a navigation repaints the pagination area.

Pre-init window. Between onOpen and the engine's pagination initialization (which runs before onFirstRender) the token is not yet backed by a paging engine. In that window reads return defaults — totalPages(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) is 1, totalElements(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) is 0, isLoading(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) is false and lastError(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) is null — and advance(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext), back(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) and switchTo(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext, int) record a pending target page (never below 1) that is replayed once initialization completes; currentPage(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) reports that pending target.

Threading. advance(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext), back(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext), switchTo(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext, int) and refresh(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) are main-thread only and throw IllegalStateException when invoked off the main server thread. Reads are unsynchronized and only coherent on the main thread.

Every method first validates the context: a context belonging to a different view class or to an already closed session fails with StaleContextException.

  • Method Details

    • currentPage

      int currentPage(@NotNull @NotNull ViewContext context)
      Returns the current page, 1-indexed. Before initialization this is the pending navigation target.
      Parameters:
      context - the context of the session to read
      Returns:
      the current 1-indexed page
      Throws:
      StaleContextException - if context belongs to another view or is closed

    • totalPages

      int totalPages(@NotNull @NotNull ViewContext context)
      Returns the total page count, always at least 1. Before initialization — and, for async sources, before the first successful load reveals the totals — this is 1.
      Parameters:
      context - the context of the session to read
      Returns:
      the total page count, >= 1
      Throws:
      StaleContextException - if context belongs to another view or is closed

    • totalElements

      int totalElements(@NotNull @NotNull ViewContext context)
      Returns the total element count of the backing source. Before initialization — and, for async sources, before totals are known — this is 0.
      Parameters:
      context - the context of the session to read
      Returns:
      the total element count
      Throws:
      StaleContextException - if context belongs to another view or is closed

    • canAdvance

      boolean canAdvance(@NotNull @NotNull ViewContext context)
      Returns whether a next page exists, i.e. currentPage + 1 <= totalPages. Always false before initialization.
      Parameters:
      context - the context of the session to read
      Returns:
      true when advance(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) would move forward
      Throws:
      StaleContextException - if context belongs to another view or is closed

    • canBack

      boolean canBack(@NotNull @NotNull ViewContext context)
      Returns whether a previous page exists, i.e. currentPage > 1. Before initialization this reports whether the pending target is above page 1.
      Parameters:
      context - the context of the session to read
      Returns:
      true when back(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) would move backward
      Throws:
      StaleContextException - if context belongs to another view or is closed

    • advance

      void advance(@NotNull @NotNull ViewContext context)
      Navigates one page forward, clamped exactly like switchTo(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext, int). Before initialization the pending target is incremented instead. Main thread only.
      Parameters:
      context - the context of the session to navigate
      Throws:
      StaleContextException - if context belongs to another view or is closed
      IllegalStateException - when invoked off the main server thread

    • back

      void back(@NotNull @NotNull ViewContext context)
      Navigates one page backward, clamped exactly like switchTo(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext, int). Before initialization the pending target is decremented instead (never below 1). Main thread only.
      Parameters:
      context - the context of the session to navigate
      Throws:
      StaleContextException - if context belongs to another view or is closed
      IllegalStateException - when invoked off the main server thread

    • switchTo

      void switchTo(@NotNull @NotNull ViewContext context, int page)
      Switches to the given page. The target is clamped exactly as the 2.x changePage: lower-clamped to page 1 always, upper-clamped to totalPages(tech.guilhermekaua.spigotboot.inventoryapi.context.ViewContext) only once the source's totals are known (always for eager sources; after the first successful load for async sources — an overshooting target is re-clamped downward when that load settles). Re-requesting the page already shown is a no-op while that page is still loading. Before initialization the lower-clamped target is recorded and replayed at initialization. Main thread only.
      Parameters:
      context - the context of the session to navigate
      page - the 1-indexed target page; out-of-range values are clamped, not rejected
      Throws:
      StaleContextException - if context belongs to another view or is closed
      IllegalStateException - when invoked off the main server thread

    • isLoading

      boolean isLoading(@NotNull @NotNull ViewContext context)
      Returns whether the latest page request has not settled yet. Always false for eager sources and before initialization.
      Parameters:
      context - the context of the session to read
      Returns:
      true while a page load is in flight
      Throws:
      StaleContextException - if context belongs to another view or is closed

    • lastError

      @Nullable @Nullable Throwable lastError(@NotNull @NotNull ViewContext context)
      Returns the failure of the most recently settled page load, or null; cleared when a new request is dispatched. Always null for eager sources and before initialization.
      Parameters:
      context - the context of the session to read
      Returns:
      the last page-load failure, or null
      Throws:
      StaleContextException - if context belongs to another view or is closed

    • refresh

      void refresh(@NotNull @NotNull ViewContext context)
      Forces a reload of the current page. Before initialization this is a no-op. After initialization the behavior depends on the source kind: lazy sources (View.paginate(Function)) re-invoke the source function against this context and swap the fresh result in; async sources invalidate their page cache; every kind then re-requests the current page, forced — the same-page dedupe is bypassed. Main thread only.
      Parameters:
      context - the context of the session to refresh
      Throws:
      StaleContextException - if context belongs to another view or is closed
      IllegalStateException - when invoked off the main server thread