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 that breaks ties and addresses a row; it orders last.
keyDescending - true to order the key descending.
sort - the sort fields that order before the key, in precedence order; each carries its own direction.
size - the maximum number of results per window (must be positive).
position - the row to continue after or before, or null to start at the beginning.
public record Scrollable<T extends Data>(Metamodel.Key<T extends Data,?> key, boolean keyDescending, List<Order> sort, int size, @Nullable Position position) extends Record
A scroll request: an ordering, a window size, and the position to continue from.

A Scrollable is the scrolling counterpart of Pageable. Where a Pageable navigates by page number, a Scrollable navigates by keyset: it names the sort fields, a unique key that breaks ties and makes every row addressable, and optionally the row to continue after or before. The ordering and the size belong to the request; the position is what a Window hands back as Window.next() and Window.previous(), and what a cursor string carries across a network boundary.


 // Newest first, tiebreak on id, twenty per window
 var latest = Scrollable.of(Post_.id, 20).sortByDescending(Post_.createdAt);

 // Last name, then first name, then id
 var byName = Scrollable.of(User_.id, 20).sortBy(User_.lastName).sortBy(User_.firstName);

 // The next request from a client's cursor string, with the size the client asks for
 var next = Scrollable.of(User_.id, size).sortBy(User_.lastName).from(cursor);

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(Metamodel.Key<T,?> key, boolean keyDescending, List<Order> sort, int size, @Nullable Position position)
      Creates an instance of a Scrollable record class.
      Parameters:
      key - the value for the key record component
      keyDescending - the value for the keyDescending record component
      sort - the value for the sort record component
      size - the value for the size record component
      position - the value for the position record component

  • Method Details

    • of

      public static <T extends Data> Scrollable<T> of(Metamodel.Key<T,?> key, int size)
      Creates a request for the first window, ordered by the key ascending.
      Type Parameters:
      T - the entity type.
      Parameters:
      key - the unique key field.
      size - the maximum number of results per window.
      Returns:
      the request.

    • descending

      public Scrollable<T> descending()
      Returns this request with the key ordered descending. Sort fields keep their own direction. 
      
 // Newest ids first
 var latest = users.scroll(Scrollable.of(User_.id, 20).descending());
      Returns:
      the request with the key descending.
      Since:
      1.14

    • sortBy

      public Scrollable<T> sortBy(Metamodel<T,?> field)
      Returns this request with an ascending sort field appended before the key.
      Parameters:
      field - the field to sort by; must not allow NULL values.
      Returns:
      the request with the sort field added.
      Since:
      1.14

    • sortByDescending

      public Scrollable<T> sortByDescending(Metamodel<T,?> field)
      Returns this request with a descending sort field appended before the key.
      Parameters:
      field - the field to sort by; must not allow NULL values.
      Returns:
      the request with the sort field added.
      Since:
      1.14

    • size

      public Scrollable<T> size(int size)
      Returns this request with a different window size.
      Parameters:
      size - the maximum number of results per window.
      Returns:
      the request with the size.
      Since:
      1.14

    • after

      public Scrollable<T> after(Object... values)
      Returns this request continuing after the row with the given values.
      Parameters:
      values - one value per sort field in sort order, then the key value.
      Returns:
      the request positioned after that row.
      Since:
      1.14

    • before

      public Scrollable<T> before(Object... values)
      Returns this request continuing before the row with the given values. The window comes back in sort order, the same as a window reached by after(Object...).
      Parameters:
      values - one value per sort field in sort order, then the key value.
      Returns:
      the request positioned before that row.
      Since:
      1.14

    • from

      public Scrollable<T> from(String cursor)
      Returns this request at the position a cursor string carries, as produced by toCursor(), Window.nextCursor() or Window.previousCursor().

      The cursor was issued for one ordering, and this request must state the same key, sort fields and directions; a cursor from another ordering is refused.

      Parameters:
      cursor - the cursor string.
      Returns:
      the request at the cursor's position.
      Throws:
      InvalidCursorException - if the cursor is malformed, from an earlier format, issued for another ordering or codec registry, or carries a value of the wrong type.
      Since:
      1.14

    • orders

      public List<Order> orders()
      Returns the complete ordering: the sort fields, then the key with its direction.
      Returns:
      the orders, in precedence.
      Since:
      1.14

    • toCursor

      public String toCursor()
      Serializes the position of this request into an opaque, URL-safe string. The cursor carries the position only: a fingerprint of the ordering, whether to continue after or before the row, and the row's values. The size stays with the request, so a client may ask for another size on the next request.
      Returns:
      a URL-safe Base64-encoded cursor string.
      Throws:
      IllegalStateException - if this request has no position, or a value type is unsupported.
      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

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

    • keyDescending

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

    • sort

      public List<Order> sort()
      Returns the value of the sort record component.
      Returns:
      the value of the sort record component

    • size

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

    • position

      public @Nullable Position position()
      Returns the value of the position record component.
      Returns:
      the value of the position record component