Package tech.guilhermekaua.spigotboot.inventoryapi.pagination

Interface PaginationBuilder<T>

Type Parameters:
T - the element type served by the source
All Known Implementing Classes:
PaginationBuilderImpl
@NonExtendable public interface PaginationBuilder<T>
Fluent declaration of one pagination token, returned by the View.paginate* factories. Builder methods only record the declaration; nothing is registered or validated as a whole until build(), which validates the combination, registers the token with the owning view and returns it.

Defaults. When neither layoutChar(char), layout(Layout) nor patterns(Layout...) is called, the pagination targets layout char 'O'. The default geometry is normal (page-by-page); scroll() switches to a sliding window, patterns(Layout...) to cycled per-page patterns.

Async-only options. loadingItem(Function), onError(PaginationErrorCallback), requestTimeout(Duration), cacheTtl(Duration) and cacheMaxPages(int) are only legal on a builder created by View.paginateAsync; calling any of them on another builder makes build() throw ViewConfigurationException.

All methods return this builder for chaining and reject null arguments with NullPointerException. Value errors fail at setter time with IllegalArgumentException; combination errors fail at build() with ViewConfigurationException.

  • Method Details

    • layoutChar

      @NotNull @NotNull PaginationBuilder<T> layoutChar(char character)
      Targets every slot of the given character in the view's layout, in row-major order. Defaults to 'O' when never called. The character must exist in the view's layout; both "no layout at all" and "char absent from the layout" are validated at view registration time. An explicit layout(Layout) silently overrides this value; combining an explicit call with patterns(Layout...) fails at build().
      Parameters:
      character - the layout character whose slots receive the page items
      Returns:
      this builder

    • layout

      @NotNull @NotNull PaginationBuilder<T> layout(@NotNull @NotNull Layout layout)
      Sets an explicit fill order, silently overriding layoutChar(char). An empty layout, or combining with patterns(Layout...), fails at build() with ViewConfigurationException.
      Parameters:
      layout - the explicit fill order for the page items
      Returns:
      this builder

    • scroll

      @NotNull @NotNull PaginationBuilder<T> scroll()
      Switches to sliding-window geometry: each page slides the visible window by exactly one element instead of jumping a full page. Cannot be combined with patterns(Layout...) — that fails at build().
      Returns:
      this builder

    • patterns

      @NotNull @NotNull PaginationBuilder<T> patterns(@NotNull @NotNull Layout... patterns)
      Switches to pattern geometry: page p paints into the slots of pattern (p - 1) % patterns.length, cycling through the given patterns. Cannot be combined with an explicit layoutChar(char) call, layout(Layout) or scroll(); an empty array or any empty pattern also fails — all at build() with ViewConfigurationException.
      Parameters:
      patterns - the per-page slot patterns, cycled in order
      Returns:
      this builder

    • itemRenderer

      @NotNull @NotNull PaginationBuilder<T> itemRenderer(@NotNull @NotNull PaginationItemRenderer<T> renderer)
      Sets the per-element renderer. Required — a declaration without a renderer fails at build() with ViewConfigurationException.
      Parameters:
      renderer - renders one element of the current page into its component builder
      Returns:
      this builder

    • fallbackItem

      @NotNull @NotNull PaginationBuilder<T> fallbackItem(@NotNull @NotNull Function<ViewContext,org.bukkit.inventory.ItemStack> item)
      Sets the item painted into page slots not covered by an element (for example the tail of a short last page) and into slots whose element failed on its very first paint. Evaluated against the session's context at paint time. When absent, uncovered slots are cleared instead.
      Parameters:
      item - the fallback item factory
      Returns:
      this builder

    • emptyStateItem

      @NotNull @NotNull PaginationBuilder<T> emptyStateItem(@NotNull @NotNull Function<ViewContext,org.bukkit.inventory.ItemStack> item, int... slots)
      Sets an item painted into the given slots when the current page settled with no elements, leaving every other layout slot empty. Unlike fallbackItem(Function) — which fills every uncovered slot of every page — this renders only while the current page is empty, and only in slots; when the page has any element it renders nothing. When both are set, the empty page shows the empty-state item (the fallback fill is suppressed for that paint).

      Slots are absolute container slots and may lie outside the pagination's layout. Evaluated against the session's context once per slot at paint time. A slot bound to a static component or to another pagination fails at open with ViewConfigurationException.

      Parameters:
      item - the empty-state item factory
      slots - the absolute container slots to paint, at least one, each non-negative
      Returns:
      this builder
      Throws:
      NullPointerException - if item or slots is null
      IllegalArgumentException - if slots is empty or contains a negative slot

    • loadingItem

      @NotNull @NotNull PaginationBuilder<T> loadingItem(@NotNull @NotNull Function<ViewContext,org.bukkit.inventory.ItemStack> item)
      Sets the item painted into every page slot while an async load is in flight. Async-only: on a non-async builder build() throws ViewConfigurationException.
      Parameters:
      item - the loading placeholder factory
      Returns:
      this builder

    • loadingItem

      @NotNull @NotNull PaginationBuilder<T> loadingItem(@NotNull @NotNull Function<ViewContext,org.bukkit.inventory.ItemStack> item, int... slots)
      Sets the loading item painted only into the given slots while an async load is in flight, leaving every other layout slot empty. The slotted form of loadingItem(Function); it has the same trigger (shown while loading) and only restricts where the item paints. Async-only: on a non-async builder build() throws ViewConfigurationException.

      Slots are absolute container slots and may lie outside the pagination's layout. Evaluated against the session's context once per slot at paint time. A slot bound to a static component or to another pagination fails at open with ViewConfigurationException.

      Parameters:
      item - the loading item factory
      slots - the absolute container slots to paint, at least one, each non-negative
      Returns:
      this builder
      Throws:
      NullPointerException - if item or slots is null
      IllegalArgumentException - if slots is empty or contains a negative slot

    • onError

      @NotNull @NotNull PaginationBuilder<T> onError(@NotNull @NotNull PaginationErrorCallback callback)
      Sets the callback invoked when an async page load fails. Async-only: on a non-async builder build() throws ViewConfigurationException.
      Parameters:
      callback - the failure callback
      Returns:
      this builder

    • requestTimeout

      @NotNull @NotNull PaginationBuilder<T> requestTimeout(@NotNull @NotNull Duration timeout)
      Enables a per-request timeout: a load exceeding it fails with a TimeoutException and follows the normal error path. Async-only: on a non-async builder build() throws ViewConfigurationException.
      Parameters:
      timeout - the timeout, must be positive
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if timeout is zero or negative

    • cacheTtl

      @NotNull @NotNull PaginationBuilder<T> cacheTtl(@NotNull @NotNull Duration ttl)
      Enables page caching: revisiting a page within the TTL renders from cache without calling the supplier; Pagination.refresh(ViewContext) invalidates the cache. Async-only: on a non-async builder build() throws ViewConfigurationException.
      Parameters:
      ttl - the cache entry freshness window, must be positive
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if ttl is zero or negative

    • cacheMaxPages

      @NotNull @NotNull PaginationBuilder<T> cacheMaxPages(int maxPages)
      Bounds the page cache (least-recently-used eviction). Defaults to 128. Requires cacheTtl(Duration) — setting it without a TTL fails at build() with ViewConfigurationException. Async-only: on a non-async builder build() throws ViewConfigurationException.
      Parameters:
      maxPages - the maximum number of cached pages, at least 1
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if maxPages is below 1

    • build

      @NotNull @NotNull Pagination<T> build()
      Validates the declaration, constructs the token and registers it with the owning view. Like every token registration this is legal only while the view's tokens are still open for registration — i.e. from field initializers or the view constructor; the builder construction itself (the paginate* call) never registers anything, only this method does.
      Returns:
      the registered pagination token
      Throws:
      ViewConfigurationException - when the renderer is missing; when patterns(Layout...) is combined with an explicit layoutChar(char) call, layout(Layout) or scroll(); when the patterns array or any single pattern, or an explicit layout, is empty; when an async-only option was used on a non-async source; or when cacheMaxPages(int) was set without cacheTtl(Duration)
      IllegalStateException - when called a second time on the same builder ("build() may only be called once per paginate* call") or after the view's token table froze