Class Cursor

java.lang.Object

ubic.gemma.persistence.util.Cursor

public final class Cursor
extends Object

Opaque cursor for keyset pagination of REST collections.

A cursor encodes:

• version — payload format version, currently 1
• sortSpec — the sort specification this cursor was emitted for, e.g. "+id" or "+lastUpdated,+id". The server must validate this against the endpoint's allowed sorts before using the cursor.
• keyTuple — the last seen key values, one entry per sort component. Must always end in a unique tie-breaker (typically id).
• direction — Cursor.Direction.FORWARD (next page) or Cursor.Direction.BACKWARD (previous page).

The wire format is base64url-encoded JSON of the form:

  {"v":1,"s":"+id","k":[12345],"d":"f"}

with "d":"f" for forward and "d":"b" for backward. "d" is omitted when the direction is forward (the default).

Cursors are not signed; this is acceptable because the sortSpec is server-validated and access control is enforced by the ACL layer.

Author:

phase3

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	Cursor.Direction

Field Summary

Fields

Modifier and Type	Field	Description
static final int	CURRENT_VERSION	Current cursor payload format version.

Constructor Summary

Constructors

Constructor	Description
Cursor(int version, String sortSpec, Object[] keyTuple, Cursor.Direction direction)	Build a cursor with an explicit payload format version.
Cursor(String sortSpec, Object[] keyTuple, Cursor.Direction direction)	Build a cursor with the current payload format version.

Method Summary

Modifier and Type	Method	Description
static Cursor	decode(String encoded)	Decode a base64url-encoded cursor string.
String	encode()	Encode this cursor as a base64url-encoded JSON string (no padding).
boolean	equals(Object o)
Cursor.Direction	getDirection()
Object[]	getKeyTuple()
String	getSortSpec()
int	getVersion()
int	hashCode()
String	toString()

Methods inherited from class Object

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

Field Details

CURRENT_VERSION

public static final int CURRENT_VERSION

Current cursor payload format version. Bump and add a migration when the JSON shape changes incompatibly.

See Also:

• Constant Field Values

Constructor Details

Cursor

public Cursor(String sortSpec,
 Object[] keyTuple,
 Cursor.Direction direction)

Build a cursor with the current payload format version.

Cursor

public Cursor(int version,
 String sortSpec,
 Object[] keyTuple,
 Cursor.Direction direction)

Build a cursor with an explicit payload format version. Intended for decoding; callers constructing new cursors should use Cursor(String, Object[], Direction).

Method Details

getVersion

public int getVersion()

getSortSpec

public String getSortSpec()

getKeyTuple

public Object[] getKeyTuple()

Returns:

a defensive copy of the key tuple; never null, never empty.

getDirection

public Cursor.Direction getDirection()

encode

public String encode()

Encode this cursor as a base64url-encoded JSON string (no padding).

decode

public static Cursor decode(String encoded)

Decode a base64url-encoded cursor string.

Throws:

IllegalArgumentException - if the string is not valid base64url, not valid JSON, or is missing required fields. Callers in the REST layer should translate this into a MalformedArgException / 400 response.

equals

public boolean equals(Object o)

Overrides:

equals in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

toString

public String toString()

Overrides:

toString in class Object