Package tech.guilhermekaua.spigotboot.inventoryapi.pagination.source

Class AsyncPageSource<T>

java.lang.Object
tech.guilhermekaua.spigotboot.inventoryapi.pagination.source.AsyncPageSource<T>
All Implemented Interfaces:
PageSource<T>
public final class AsyncPageSource<T> extends Object implements PageSource<T>
Asynchronous PageSource backed by an AsyncPageSupplier. Owns all async machinery: monotonically increasing request ids with at-most-once settle semantics, stale response discarding, optional request timeouts and an optional TTL-bounded page cache.

Thread-safety: every state transition happens inside one internal lock; the id check and the state write are atomic. Asynchronously completed settles are routed through the configured SettleDispatcher; synchronous settles (cache hits, immediate failures) run on the calling thread.

  • Constructor Details

    • AsyncPageSource

      public AsyncPageSource(AsyncPageSupplier<T> supplier, PaginationErrorCallback errorCallback, Duration requestTimeout, Duration cacheTtl, int cacheMaxPages, SettleDispatcher settleDispatcher)
      Creates an async page source.
      Parameters:
      supplier - loads pages, not null
      errorCallback - invoked on failed loads, may be null
      requestTimeout - per-request timeout, may be null to disable
      cacheTtl - cache entry freshness window, may be null to disable caching
      cacheMaxPages - cache LRU bound, must be >= 1
      settleDispatcher - routes asynchronously completed settles, not null
      Throws:
      NullPointerException - if supplier or settleDispatcher is null
      IllegalArgumentException - if cacheMaxPages < 1

  • Method Details

    • request

      public void request(PageRequest request, BiConsumer<PageResult<T>,Throwable> onSettle)
      Description copied from interface: PageSource
      Requests the page described by request.

      Contract for implementations:

      • onSettle is invoked at most once per request, with exactly one of result/error non-null — and possibly never (a superseded request).
      • It MAY be invoked synchronously inside this method and MAY be invoked on any thread.
      • A request superseded by a newer one MUST NOT be settled.
      • PageSource.isLoading() must return false once the latest request settled.
      Specified by:
      request in interface PageSource<T>
      Parameters:
      request - the page to load, never null
      onSettle - receives the result or the failure, never null

    • shutdownSharedTimeoutScheduler

      @Internal public static void shutdownSharedTimeoutScheduler()
      Shuts the shared timeout scheduler down and clears it so the next timeout-bearing request lazily recreates a fresh one. Called from the inventory-api module disable hook; before 3.0.0 the shared daemon thread outlived the plugin and pinned its classloader across reloads. Safe to call repeatedly and when no scheduler was ever created.

    • totalElements

      public int totalElements()
      Specified by:
      totalElements in interface PageSource<T>
      Returns:
      the total number of elements in the backing store; 0 until known for async sources

    • totalsKnown

      public boolean totalsKnown()
      Specified by:
      totalsKnown in interface PageSource<T>
      Returns:
      true once PageSource.totalElements() reflects the real store size — always for eager sources, after the first successful settle for async sources

    • isLoading

      public boolean isLoading()
      Specified by:
      isLoading in interface PageSource<T>
      Returns:
      true while the latest request has not settled

    • lastError

      public Throwable lastError()
      Specified by:
      lastError in interface PageSource<T>
      Returns:
      the failure of the most recently settled request, or null; cleared when a new request is dispatched

    • elements

      public List<T> elements()
      Specified by:
      elements in interface PageSource<T>
      Returns:
      the elements currently held locally — the full backing list for eager sources, the items of the most recently applied page for async sources

    • invalidate

      public void invalidate()
      Description copied from interface: PageSource
      Clears any cached pages. No-op by default.
      Specified by:
      invalidate in interface PageSource<T>