Package tech.guilhermekaua.spigotboot.inventoryapi

Class View

java.lang.Object
tech.guilhermekaua.spigotboot.inventoryapi.View
public abstract class View extends Object
Base class for inventory views. Views are DI singletons discovered via @RegisterView and opened through ViewService; subclasses override only the lifecycle handlers they need. All handlers run on the main thread, invoked by the engine.

Contract: view fields hold only state tokens, injected collaborators and immutable configuration — every per-player value lives in per-context state and is dropped when the context closes. State factories are legal only in field initializers or the constructor; after registration freezes the token table they throw IllegalStateException.

  • Constructor Summary

    Constructors
    Constructor
    Description
    View()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    protected final <T> MutableState<T>
    initialState(@NotNull String key, @NotNull Class<T> type)
    Declares a mutable value bound from ViewArguments at open; the type is validated at the open site.
    protected final <T> State<T>
    lazyState(@NotNull Function<ViewContext,T> computation)
    Declares a read-only value computed once per context on the first read, on the main thread, and stored thereafter.
    protected final <T> MutableState<T>
    mutableState(@NotNull Function<ViewContext,T> initialValue)
    Declares a per-context mutable value whose initial is computed per context on first read, e.g.
    protected final <T> MutableState<T>
    mutableState(T initialValue)
    Declares a per-context mutable value seeded with a shared initial value.
    protected void
    onClick(@NotNull SlotClickContext context)
    View-level click fallback: runs after component handlers for top-container clicks and receives every bottom-inventory click with isPlayerInventory() == true.
    protected void
    onClose(@NotNull CloseContext context)
    Called when the session tears down, with the matching CloseReason.
    protected void
    onFirstRender(@NotNull RenderContext context)
    Declares this session's components; called once per open, after the container is created and before the first paint.
    protected void
    onInit(@NotNull ViewConfigBuilder config)
    Configures this view; called once per class at registration.
    protected void
    onOpen(@NotNull OpenContext context)
    Called once per open, before any container exists.
    protected void
    onUpdate(@NotNull UpdateContext context)
    Called on every update pass; inspect UpdateContext.trigger() for the cause.
    protected final <T> PaginationBuilder<T>
    paginate(@NotNull Function<ViewContext,List<T>> source)
    Declares paginated rendering over a per-context element list: the function runs once per context at pagination initialization, on the main thread, and runs again for that context only when Pagination.refresh(context) is called.
    protected final <T> PaginationBuilder<T>
    paginate(@NotNull List<T> source)
    Declares paginated rendering over a fixed element list.
    protected final <T> PaginationBuilder<T>
    paginateAsync(@NotNull AsyncPageSupplier<T> source)
    Declares paginated rendering over an asynchronously loaded source: every context gets its own fresh AsyncPageSource at pagination initialization, so request ids, page caches, loading state and errors are never shared between viewers.
    protected final <T> PaginationBuilder<T>
    paginateSource(@NotNull Function<ViewContext,PageSource<T>> factory)
    Escape hatch declaring paginated rendering over a custom PageSource: the factory runs once per context at pagination initialization and must return the source instance serving exactly that context.
    protected final <T> SharedState<T>
    sharedState(T initialValue)
    Declares one atomic value per view singleton, shared by all viewers and writable from any thread.
    final @NotNull TokenTable
    tokenTable()
    Returns this view's token table; used by the engine to size per-session state storage and to freeze token registration.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • View

      public View()

  • Method Details

    • onInit

      protected void onInit(@NotNull @NotNull ViewConfigBuilder config)
      Configures this view; called once per class at registration. The resulting config is validated and frozen afterwards.
      Parameters:
      config - the mutable config builder

    • onOpen

      protected void onOpen(@NotNull @NotNull OpenContext context)
      Called once per open, before any container exists. May cancel the open (zero side effects) or override title/rows for this open only.
      Parameters:
      context - the open context

    • onFirstRender

      protected void onFirstRender(@NotNull @NotNull RenderContext context)
      Declares this session's components; called once per open, after the container is created and before the first paint.
      Parameters:
      context - the render context

    • onUpdate

      protected void onUpdate(@NotNull @NotNull UpdateContext context)
      Called on every update pass; inspect UpdateContext.trigger() for the cause.
      Parameters:
      context - the update context

    • onClick

      protected void onClick(@NotNull @NotNull SlotClickContext context)
      View-level click fallback: runs after component handlers for top-container clicks and receives every bottom-inventory click with isPlayerInventory() == true.
      Parameters:
      context - the click context

    • onClose

      protected void onClose(@NotNull @NotNull CloseContext context)
      Called when the session tears down, with the matching CloseReason. Throwing here is caught and logged; teardown always completes.
      Parameters:
      context - the close context

    • mutableState

      protected final <T> MutableState<T> mutableState(@Nullable T initialValue)
      Declares a per-context mutable value seeded with a shared initial value. The initial object is shared by every context and must be immutable; use mutableState(Function) for mutable initials such as collections.
      Type Parameters:
      T - the value type
      Parameters:
      initialValue - the shared initial value, possibly null
      Returns:
      the state token
      Throws:
      IllegalStateException - when called after registration froze the token table

    • mutableState

      protected final <T> MutableState<T> mutableState(@NotNull @NotNull Function<ViewContext,T> initialValue)
      Declares a per-context mutable value whose initial is computed per context on first read, e.g. mutableState(ctx -> new ArrayList<>()).
      Type Parameters:
      T - the value type
      Parameters:
      initialValue - the per-context initial value factory
      Returns:
      the state token
      Throws:
      IllegalStateException - when called after registration froze the token table

    • lazyState

      protected final <T> State<T> lazyState(@NotNull @NotNull Function<ViewContext,T> computation)
      Declares a read-only value computed once per context on the first read, on the main thread, and stored thereafter.
      Type Parameters:
      T - the value type
      Parameters:
      computation - the once-per-context computation
      Returns:
      the state token
      Throws:
      IllegalStateException - when called after registration froze the token table

    • initialState

      protected final <T> MutableState<T> initialState(@NotNull @NotNull String key, @NotNull @NotNull Class<T> type)
      Declares a mutable value bound from ViewArguments at open; the type is validated at the open site. An absent key reads as null until set.
      Type Parameters:
      T - the value type
      Parameters:
      key - the argument key bound at open
      type - the expected argument type
      Returns:
      the state token
      Throws:
      IllegalStateException - when called after registration froze the token table

    • sharedState

      protected final <T> SharedState<T> sharedState(@Nullable T initialValue)
      Declares one atomic value per view singleton, shared by all viewers and writable from any thread.
      Type Parameters:
      T - the value type
      Parameters:
      initialValue - the initial shared value, possibly null
      Returns:
      the shared state token
      Throws:
      IllegalStateException - when called after registration froze the token table

    • paginate

      protected final <T> PaginationBuilder<T> paginate(@NotNull @NotNull List<T> source)
      Declares paginated rendering over a fixed element list. The list is copied defensively when this factory runs and becomes one immutable page source shared by every context; later mutations of the original list are never observed. Use paginate(Function) when elements differ per viewer or must be refreshable.

      Like the state factories, pagination declarations are legal only in field initializers or the constructor: the returned builder's PaginationBuilder.build() registers the token and throws IllegalStateException once registration froze the token table.

      Type Parameters:
      T - the element type
      Parameters:
      source - the elements to paginate, copied defensively
      Returns:
      the pagination declaration builder

    • paginate

      protected final <T> PaginationBuilder<T> paginate(@NotNull @NotNull Function<ViewContext,List<T>> source)
      Declares paginated rendering over a per-context element list: the function runs once per context at pagination initialization, on the main thread, and runs again for that context only when Pagination.refresh(context) is called.

      Like the state factories, pagination declarations are legal only in field initializers or the constructor: the returned builder's PaginationBuilder.build() registers the token and throws IllegalStateException once registration froze the token table.

      Type Parameters:
      T - the element type
      Parameters:
      source - the per-context element list factory; must not return null
      Returns:
      the pagination declaration builder

    • paginateAsync

      protected final <T> PaginationBuilder<T> paginateAsync(@NotNull @NotNull AsyncPageSupplier<T> source)
      Declares paginated rendering over an asynchronously loaded source: every context gets its own fresh AsyncPageSource at pagination initialization, so request ids, page caches, loading state and errors are never shared between viewers. The async-only builder options (loadingItem, onError, requestTimeout, cacheTtl, cacheMaxPages) are legal only on the builder returned here.

      Like the state factories, pagination declarations are legal only in field initializers or the constructor: the returned builder's PaginationBuilder.build() registers the token and throws IllegalStateException once registration froze the token table.

      Type Parameters:
      T - the element type
      Parameters:
      source - the page loader invoked per page request
      Returns:
      the pagination declaration builder

    • paginateSource

      protected final <T> PaginationBuilder<T> paginateSource(@NotNull @NotNull Function<ViewContext,PageSource<T>> factory)
      Escape hatch declaring paginated rendering over a custom PageSource: the factory runs once per context at pagination initialization and must return the source instance serving exactly that context.

      Like the state factories, pagination declarations are legal only in field initializers or the constructor: the returned builder's PaginationBuilder.build() registers the token and throws IllegalStateException once registration froze the token table.

      Type Parameters:
      T - the element type
      Parameters:
      factory - the per-context page source factory; must not return null
      Returns:
      the pagination declaration builder

    • tokenTable

      @Internal @NotNull public final @NotNull TokenTable tokenTable()
      Returns this view's token table; used by the engine to size per-session state storage and to freeze token registration. Plugin code must not call this method; it is reserved for the engine registration phase.
      Returns:
      the token registry of this view instance