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

Class PaginationBuilderImpl<T>

java.lang.Object

tech.guilhermekaua.spigotboot.inventoryapi.internal.pagination.PaginationBuilderImpl<T>

Type Parameters:

T - the element type

All Implemented Interfaces:

PaginationBuilder<T>

@Internal
public final class PaginationBuilderImpl<T>
extends Object
implements PaginationBuilder<T>

PaginationBuilder implementation behind View.paginate*: collects the declaration fluently (value errors rejected at setter time), validates the combination at build(), resolves geometry and target, and constructs the registered PaginationImpl token. One builder produces at most one token.

Constructor Summary

Constructors

Constructor	Description
PaginationBuilderImpl(@NotNull View owner, @NotNull TokenTable table, @NotNull PaginationSourceSpec<T> source)	Creates a builder for one pagination declaration of a view.

Method Summary

Modifier and Type	Method	Description
@NotNull Pagination<T>	build()	Validates the declaration, constructs the token and registers it with the owning view.
@NotNull PaginationBuilder<T>	cacheMaxPages(int maxPages)	Bounds the page cache (least-recently-used eviction).
@NotNull PaginationBuilder<T>	cacheTtl(@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.
@NotNull PaginationBuilder<T>	emptyStateItem(@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.
@NotNull PaginationBuilder<T>	fallbackItem(@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.
@NotNull PaginationBuilder<T>	itemRenderer(@NotNull PaginationItemRenderer<T> renderer)	Sets the per-element renderer.
@NotNull PaginationBuilder<T>	layout(@NotNull Layout layout)	Sets an explicit fill order, silently overriding PaginationBuilder.layoutChar(char).
@NotNull PaginationBuilder<T>	layoutChar(char character)	Targets every slot of the given character in the view's layout, in row-major order.
@NotNull PaginationBuilder<T>	loadingItem(@NotNull Function<ViewContext,org.bukkit.inventory.ItemStack> item)	Sets the item painted into every page slot while an async load is in flight.
@NotNull PaginationBuilder<T>	loadingItem(@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.
@NotNull PaginationBuilder<T>	onError(@NotNull PaginationErrorCallback callback)	Sets the callback invoked when an async page load fails.
@NotNull PaginationBuilder<T>	patterns(@NotNull Layout... patterns)	Switches to pattern geometry: page p paints into the slots of pattern (p - 1) % patterns.length, cycling through the given patterns.
@NotNull PaginationBuilder<T>	requestTimeout(@NotNull Duration timeout)	Enables a per-request timeout: a load exceeding it fails with a TimeoutException and follows the normal error path.
@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.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

PaginationBuilderImpl

public PaginationBuilderImpl(@NotNull
 @NotNull View owner,
 @NotNull
 @NotNull TokenTable table,
 @NotNull
 @NotNull PaginationSourceSpec<T> source)

Creates a builder for one pagination declaration of a view.

Parameters:

owner - the view declaring the pagination

table - the owner's token table; build() registers into it

source - the source declaration produced by the View.paginate* factory

Method Details

layoutChar

@NotNull
public @NotNull PaginationBuilder<T> layoutChar(char character)

Description copied from interface: PaginationBuilder

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 PaginationBuilder.layout(Layout) silently overrides this value; combining an explicit call with PaginationBuilder.patterns(Layout...) fails at PaginationBuilder.build().

Specified by:

layoutChar in interface PaginationBuilder<T>

Parameters:

character - the layout character whose slots receive the page items

Returns:

this builder

layout

@NotNull
public @NotNull PaginationBuilder<T> layout(@NotNull
 @NotNull Layout layout)

Description copied from interface: PaginationBuilder

Sets an explicit fill order, silently overriding PaginationBuilder.layoutChar(char). An empty layout, or combining with PaginationBuilder.patterns(Layout...), fails at PaginationBuilder.build() with ViewConfigurationException.

Specified by:

layout in interface PaginationBuilder<T>

Parameters:

layout - the explicit fill order for the page items

Returns:

this builder

scroll

@NotNull
public @NotNull PaginationBuilder<T> scroll()

Description copied from interface: PaginationBuilder

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 PaginationBuilder.patterns(Layout...) — that fails at PaginationBuilder.build().

Specified by:

scroll in interface PaginationBuilder<T>

Returns:

this builder

patterns

@NotNull
public @NotNull PaginationBuilder<T> patterns(@NotNull
 @NotNull Layout... patterns)

Description copied from interface: PaginationBuilder

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 PaginationBuilder.layoutChar(char) call, PaginationBuilder.layout(Layout) or PaginationBuilder.scroll(); an empty array or any empty pattern also fails — all at PaginationBuilder.build() with ViewConfigurationException.

Specified by:

patterns in interface PaginationBuilder<T>

Parameters:

patterns - the per-page slot patterns, cycled in order

Returns:

this builder

itemRenderer

@NotNull
public @NotNull PaginationBuilder<T> itemRenderer(@NotNull
 @NotNull PaginationItemRenderer<T> renderer)

Description copied from interface: PaginationBuilder

Sets the per-element renderer. Required — a declaration without a renderer fails at PaginationBuilder.build() with ViewConfigurationException.

Specified by:

itemRenderer in interface PaginationBuilder<T>

Parameters:

renderer - renders one element of the current page into its component builder

Returns:

this builder

fallbackItem

@NotNull
public @NotNull PaginationBuilder<T> fallbackItem(@NotNull
 @NotNull Function<ViewContext,org.bukkit.inventory.ItemStack> item)

Description copied from interface: PaginationBuilder

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.

Specified by:

fallbackItem in interface PaginationBuilder<T>

Parameters:

item - the fallback item factory

Returns:

this builder

loadingItem

@NotNull
public @NotNull PaginationBuilder<T> loadingItem(@NotNull
 @NotNull Function<ViewContext,org.bukkit.inventory.ItemStack> item)

Description copied from interface: PaginationBuilder

Sets the item painted into every page slot while an async load is in flight. Async-only: on a non-async builder PaginationBuilder.build() throws ViewConfigurationException.

Specified by:

loadingItem in interface PaginationBuilder<T>

Parameters:

item - the loading placeholder factory

Returns:

this builder

emptyStateItem

@NotNull
public @NotNull PaginationBuilder<T> emptyStateItem(@NotNull
 @NotNull Function<ViewContext,org.bukkit.inventory.ItemStack> item,
 int... slots)

Description copied from interface: PaginationBuilder

Sets an item painted into the given slots when the current page settled with no elements, leaving every other layout slot empty. Unlike PaginationBuilder.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.

Specified by:

emptyStateItem in interface PaginationBuilder<T>

Parameters:

item - the empty-state item factory

slots - the absolute container slots to paint, at least one, each non-negative

Returns:

this builder

loadingItem

@NotNull
public @NotNull PaginationBuilder<T> loadingItem(@NotNull
 @NotNull Function<ViewContext,org.bukkit.inventory.ItemStack> item,
 int... slots)

Description copied from interface: PaginationBuilder

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 PaginationBuilder.loadingItem(Function); it has the same trigger (shown while loading) and only restricts where the item paints. Async-only: on a non-async builder PaginationBuilder.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.

Specified by:

loadingItem in interface PaginationBuilder<T>

Parameters:

item - the loading item factory

slots - the absolute container slots to paint, at least one, each non-negative

Returns:

this builder

onError

@NotNull
public @NotNull PaginationBuilder<T> onError(@NotNull
 @NotNull PaginationErrorCallback callback)

Description copied from interface: PaginationBuilder

Sets the callback invoked when an async page load fails. Async-only: on a non-async builder PaginationBuilder.build() throws ViewConfigurationException.

Specified by:

onError in interface PaginationBuilder<T>

Parameters:

callback - the failure callback

Returns:

this builder

requestTimeout

@NotNull
public @NotNull PaginationBuilder<T> requestTimeout(@NotNull
 @NotNull Duration timeout)

Description copied from interface: PaginationBuilder

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 PaginationBuilder.build() throws ViewConfigurationException.

Specified by:

requestTimeout in interface PaginationBuilder<T>

Parameters:

timeout - the timeout, must be positive

Returns:

this builder

cacheTtl

@NotNull
public @NotNull PaginationBuilder<T> cacheTtl(@NotNull
 @NotNull Duration ttl)

Description copied from interface: PaginationBuilder

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 PaginationBuilder.build() throws ViewConfigurationException.

Specified by:

cacheTtl in interface PaginationBuilder<T>

Parameters:

ttl - the cache entry freshness window, must be positive

Returns:

this builder

cacheMaxPages

@NotNull
public @NotNull PaginationBuilder<T> cacheMaxPages(int maxPages)

Description copied from interface: PaginationBuilder

Bounds the page cache (least-recently-used eviction). Defaults to 128. Requires PaginationBuilder.cacheTtl(Duration) — setting it without a TTL fails at PaginationBuilder.build() with ViewConfigurationException. Async-only: on a non-async builder PaginationBuilder.build() throws ViewConfigurationException.

Specified by:

cacheMaxPages in interface PaginationBuilder<T>

Parameters:

maxPages - the maximum number of cached pages, at least 1

Returns:

this builder

build

@NotNull
public @NotNull Pagination<T> build()

Description copied from interface: PaginationBuilder

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.

Specified by:

build in interface PaginationBuilder<T>

Returns:

the registered pagination token