Module storm.foundation
Package st.orm

Record Class Scrollable<T extends Data>

java.lang.Object
java.lang.Record
st.orm.Scrollable<T>
Record Components:
key - the unique key field used for cursor positioning and ordering.
keyCursor - the cursor value for the key field, or null for the first page.
sort - the non-unique sort field, or null for single-key scrolling.
sortCursor - the cursor value for the sort field, or null for single-key scrolling.
size - the maximum number of results per window (must be positive).
isForward - true for forward scrolling (ascending key order), false for backward scrolling (descending key order).
public record Scrollable<T extends Data>(@Nonnull Metamodel.Key<T extends Data,?> key, @Nullable Object keyCursor, @Nullable Metamodel<T extends Data,?> sort, @Nullable Object sortCursor, int size, boolean isForward) extends Record
Represents a scroll request that captures the cursor state needed to fetch a window of results.

A Scrollable is the scrolling counterpart of Pageable. While a Pageable navigates by page number, a Scrollable navigates by cursor position. Scrollable instances are typically obtained from Window.next() or Window.previous(), but can also be created directly using the factory methods.

The serialized cursor is opaque and URL-safe, but it is not tamper-proof. If the cursor is exposed to untrusted clients, sign or wrap it at a higher layer.

Since:
1.11

  • Constructor Details

    • Scrollable

      public Scrollable(@Nonnull Metamodel.Key<T,?> key, @Nullable Object keyCursor, @Nullable Metamodel<T,?> sort, @Nullable Object sortCursor, int size, boolean isForward)
      Creates an instance of a Scrollable record class.
      Parameters:
      key - the value for the key record component
      keyCursor - the value for the keyCursor record component
      sort - the value for the sort record component
      sortCursor - the value for the sortCursor record component
      size - the value for the size record component
      isForward - the value for the isForward record component

  • Method Details

    • of

      public static <T extends Data, E> Scrollable<T> of(@Nonnull Metamodel.Key<T,E> key, int size)
      Creates a scrollable request for the first page in ascending key order.
      Type Parameters:
      T - the entity type.
      E - the key field type.
      Parameters:
      key - the unique key field.
      size - the maximum number of results per window.
      Returns:
      a scrollable for the first page.

    • of

      public static <T extends Data, E> Scrollable<T> of(@Nonnull Metamodel.Key<T,E> key, @Nonnull E keyCursor, int size)
      Creates a scrollable request starting after the given cursor value, in ascending key order.
      Type Parameters:
      T - the entity type.
      E - the key field type.
      Parameters:
      key - the unique key field.
      keyCursor - the cursor value to start after.
      size - the maximum number of results per window.
      Returns:
      a scrollable starting after the cursor.

    • of

      public static <T extends Data, E, S> Scrollable<T> of(@Nonnull Metamodel.Key<T,E> key, @Nonnull Metamodel<T,S> sort, int size)
      Creates a scrollable request for the first page in ascending key order, sorted by the given field.
      Type Parameters:
      T - the entity type.
      E - the key field type.
      S - the sort field type.
      Parameters:
      key - the unique key field (tiebreaker).
      sort - the non-unique sort field.
      size - the maximum number of results per window.
      Returns:
      a scrollable for the first page.

    • of

      public static <T extends Data, E, S> Scrollable<T> of(@Nonnull Metamodel.Key<T,E> key, @Nonnull E keyCursor, @Nonnull Metamodel<T,S> sort, @Nonnull S sortCursor, int size)
      Creates a scrollable request starting after the given cursor values, in ascending key order, sorted by the given field.
      Type Parameters:
      T - the entity type.
      E - the key field type.
      S - the sort field type.
      Parameters:
      key - the unique key field (tiebreaker).
      keyCursor - the cursor value for the key field.
      sort - the non-unique sort field.
      sortCursor - the cursor value for the sort field.
      size - the maximum number of results per window.
      Returns:
      a scrollable starting after the cursor values.

    • forward

      public Scrollable<T> forward()
      Returns a new scrollable with forward direction. Returns this if already forward.
      Returns:
      a scrollable with forward direction.

    • backward

      public Scrollable<T> backward()
      Returns a new scrollable with backward direction. Returns this if already backward. 
      
 // First page from the end (descending)
 var window = repo.scroll(Scrollable.of(User_.id, 20).backward());
      Returns:
      a scrollable with backward direction.

    • reverse

      public Scrollable<T> reverse()
      Returns a new scrollable with the direction reversed.
      Returns:
      a new scrollable with the opposite direction.

    • hasCursor

      public boolean hasCursor()
      Returns true if this scrollable has a cursor position (i.e., is not a first-page request).
      Returns:
      true if a cursor is set.

    • isComposite

      public boolean isComposite()
      Returns true if this scrollable uses a composite cursor with a separate sort field.
      Returns:
      true if a sort field is set.

    • toCursor

      public String toCursor()
      Serializes the cursor state of this scrollable into an opaque, URL-safe string. The cursor encodes the cursor values, size, direction, a metamodel fingerprint, and a registry fingerprint.

      This is useful for REST APIs where the cursor is passed as a query parameter:

      
 // Server: include cursor in response
 String cursor = window.nextCursor();

 // Client sends cursor back as query parameter
 // Server: reconstruct scrollable
 var scrollable = Scrollable.fromCursor(User_.id, cursor);
 var next = repo.scroll(scrollable);
      Returns:
      a URL-safe Base64-encoded cursor string.
      Throws:
      IllegalStateException - if a cursor value type is unsupported or serialization fails.
      Since:
      1.11

    • fromCursor

      public static <T extends Data, E> Scrollable<T> fromCursor(@Nonnull Metamodel.Key<T,E> key, @Nonnull String cursor)
      Deserializes a cursor string (produced by toCursor()) into a Scrollable for single-key scrolling.
      Type Parameters:
      T - the entity type.
      E - the key field type.
      Parameters:
      key - the unique key field (must match the key used when the cursor was created).
      cursor - the cursor string.
      Returns:
      a scrollable reconstructed from the cursor.
      Throws:
      IllegalArgumentException - if the cursor string is invalid.
      Since:
      1.11

    • fromCursor

      public static <T extends Data, E, S> Scrollable<T> fromCursor(@Nonnull Metamodel.Key<T,E> key, @Nullable Metamodel<T,S> sort, @Nonnull String cursor)
      Deserializes a cursor string (produced by toCursor()) into a Scrollable for composite scrolling with a sort field.
      Type Parameters:
      T - the entity type.
      E - the key field type.
      S - the sort field type.
      Parameters:
      key - the unique key field (must match the key used when the cursor was created).
      sort - the sort field, or null for single-key scrolling.
      cursor - the cursor string.
      Returns:
      a scrollable reconstructed from the cursor.
      Throws:
      IllegalArgumentException - if the cursor string is invalid.
      Since:
      1.11

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. Reference components are compared with Objects::equals(Object,Object); primitive components are compared with '=='.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • key

      @Nonnull public Metamodel.Key<T,?> key()
      Returns the value of the key record component.
      Returns:
      the value of the key record component

    • keyCursor

      @Nullable public Object keyCursor()
      Returns the value of the keyCursor record component.
      Returns:
      the value of the keyCursor record component

    • sort

      @Nullable public Metamodel<T,?> sort()
      Returns the value of the sort record component.
      Returns:
      the value of the sort record component

    • sortCursor

      @Nullable public Object sortCursor()
      Returns the value of the sortCursor record component.
      Returns:
      the value of the sortCursor record component

    • size

      public int size()
      Returns the value of the size record component.
      Returns:
      the value of the size record component

    • isForward

      public boolean isForward()
      Returns the value of the isForward record component.
      Returns:
      the value of the isForward record component