Package su.onno.query

Record Class Cursor

java.lang.Object
java.lang.Record
su.onno.query.Cursor
Record Components:
column - the sort column this cursor was minted for (validated against the entity)
descending - the sort direction it was minted for
value - the sort column's value on the cursor row, or null (NULLS-LAST tail)
id - the _id tiebreaker of the cursor row
public record Cursor(String column, boolean descending, Object value, UUID id) extends Record
An opaque, self-describing position in a keyset-paginated list — the "where I left off" token a client echoes back to fetch the next window. It captures the last row of a page as the pair the seek predicate needs: the value of the sort column and the _id tiebreaker, plus the sort column + direction it was minted for so a stale cursor (the client changed the sort) can be detected and ignored rather than silently returning a wrong window.

The wire form is URL-safe Base64 of a tagged, unit-separated record: v1␟{column}␟{a|d}␟{typeTag}␟{value}␟{uuid}. The value is typed (string, long, decimal, boolean, timestamp-as-epoch-millis, uuid, or null) so it round-trips back to a JDBI-bindable object that compares correctly against its column — a date cursor binds as a Timestamp, not a string. The token is a position, not a credential: every field is re-validated and the value is always bound as a parameter, so a tampered token can only point at a different row, never inject SQL.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Cursor(String column, boolean descending, Object value, UUID id)
    Creates an instance of a Cursor record class.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    column()
    Returns the value of the column record component.
    static Cursor
    decode(String token)
    Decode a token to a cursor, or null if it is blank or not a well-formed v1 token.
    static Cursor
    decodeFor(String token, String column, boolean descending)
    Decode a token, but only if it still matches the active sort — a cursor minted for a different column or direction (the client re-sorted) is treated as absent so paging restarts cleanly from the first window.
    boolean
    descending()
    Returns the value of the descending record component.
    String
    encode()
    The URL-safe token to hand back to the client as nextCursor.
    final boolean
    equals(Object o)
    Indicates whether some other object is "equal to" this one.
    static Cursor
    from(String column, boolean descending, Map<String,Object> row)
    Build the cursor that points at row as the last row of the current page.
    final int
    hashCode()
    Returns a hash code value for this object.
    UUID
    id()
    Returns the value of the id record component.
    final String
    toString()
    Returns a string representation of this record class.
    Object
    value()
    Returns the value of the value record component.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Cursor

      public Cursor(String column, boolean descending, Object value, UUID id)
      Creates an instance of a Cursor record class.
      Parameters:
      column - the value for the column record component
      descending - the value for the descending record component
      value - the value for the value record component
      id - the value for the id record component

  • Method Details

    • from

      public static Cursor from(String column, boolean descending, Map<String,Object> row)
      Build the cursor that points at row as the last row of the current page.

    • decodeFor

      public static Cursor decodeFor(String token, String column, boolean descending)
      Decode a token, but only if it still matches the active sort — a cursor minted for a different column or direction (the client re-sorted) is treated as absent so paging restarts cleanly from the first window. A blank or malformed token likewise yields null.

    • decode

      public static Cursor decode(String token)
      Decode a token to a cursor, or null if it is blank or not a well-formed v1 token.

    • encode

      public String encode()
      The URL-safe token to hand back to the client as nextCursor.

    • 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.

    • column

      public String column()
      Returns the value of the column record component.
      Returns:
      the value of the column record component

    • descending

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

    • value

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

    • id

      public UUID id()
      Returns the value of the id record component.
      Returns:
      the value of the id record component