Top Description Inners Methods
jakarta.data.page

public Interface PageRequest

Known Direct Implementers
jakarta.data.page.Pagination
Imports
jakarta.data.Limit, .Order, .Sort, jakarta.data.repository.OrderBy, java.util.List, .Optional

A request for a single well-specified page of query results.

A query method of a repository may have a parameter of type PageRequest if its return type indicates that it may return multiple entities, that is, if its return type is an array type, List, Stream, Page, or CursoredPage. The parameter of type PageRequest must occur after the method parameters representing regular parameters of the query itself. For example:

@OrderBy("age")
@OrderBy("ssn")
Person[] findByAgeBetween(int minAge, int maxAge, PageRequest pageRequest);

This method might be called as follows:

var page = people.findByAgeBetween(35, 59,
               PageRequest.ofSize(100));
var results = page.content();
...
while (page.hasNext()) {
    page = people.findByAgeBetween(35, 59,
               page.nextPageRequest().withoutTotal());
    results = page.content();
  ...
}

A repository method may not be declared with:

Nested and Inner Type Summary

Modifier and TypeClass and Description
public static interface
PageRequest.Cursor

A cursor that is formed from a key, relative to which a next or previous page can be requested.

public static enum
PageRequest.Mode

The type of pagination: offset-based or cursor-based, which includes a direction.

Method Summary

Modifier and TypeMethod and Description
public static PageRequest

Returns:

a new instance of PageRequest with forward cursor-based pagination. This method never returns null.
afterCursor(PageRequest.Cursor
cursor with key values, the order and number of which must match the OrderBy annotations or OrderBy name pattern and the Order and Sort parameters of the repository method to which this page request will be supplied.
cursor, long
The page number.
pageNumber, int
The number of query results in a full page.
maxPageSize, boolean
Indicates whether to retrieve the total number of elements available across all pages.
requestTotal)

Requests cursor-based pagination in the forward direction, starting after the specified key.

public PageRequest

Returns:

a new instance of PageRequest with forward cursor-based pagination. This method never returns null.
afterCursor(PageRequest.Cursor
cursor with key values, the order and number of which must match the OrderBy annotations, jakarta.data.Sort parameters, or OrderBy name pattern of the repository method to which this pagination will be supplied.
cursor)

Requests cursor-based pagination in the forward direction, starting after the specified key.

public static PageRequest

Returns:

a new instance of PageRequest with cursor-based pagination in the previous page direction. This method never returns null.
beforeCursor(PageRequest.Cursor
cursor with key values, the order and number of which must match the OrderBy annotations or OrderBy name pattern and the Order and Sort parameters of the repository method to which this page request will be supplied.
cursor, long
The page number.
pageNumber, int
The number of query results in a full page.
maxPageSize, boolean
Indicates whether to retrieve the total number of elements available across all pages.
requestTotal)

Requests cursor-based pagination in the previous page direction relative to the specified cursor.

public PageRequest

Returns:

a new instance of PageRequest with cursor-based pagination in the previous page direction. This method never returns null.
beforeCursor(PageRequest.Cursor
cursor with key values, the order and number of which must match the OrderBy annotations, jakarta.data.Sort parameters, or OrderBy name pattern of the repository method to which this pagination will be supplied.
cursor)

Requests cursor-based pagination in the previous page direction relative to the specified key values.

public Optional<PageRequest.Cursor>

Returns:

the cursor; Optional#empty() if using offset pagination.
cursor()

Returns the key values which are the starting point for cursor-based pagination.

public boolean

Returns:

true if both instances are of the same class and represent the same pagination information. Otherwise false.
equals(Object o)

Compares with another instance to determine if both represent the same pagination information.

public PageRequest.Mode

Returns:

the type of pagination.
mode()

Returns the type of pagination.

public static PageRequest

Returns:

a new instance of PageRequest. This method never returns null.
ofPage(long
The page number.
pageNumber)

Creates a new page request with the given page number and with a default size of 10.

public static PageRequest

Returns:

a new instance of PageRequest. This method never returns null.
ofPage(long
The page number.
pageNumber, int
The number of query results in a full page.
maxPageSize, boolean
Indicates whether to retrieve the total number of elements available across all pages.
requestTotal)

Creates a new page request without a cursor.

public static PageRequest

Returns:

a new instance of PageRequest. This method never returns null.
ofSize(int
The number of query results in a full page.
maxPageSize)

Creates a new page request for requesting pages of the specified size, starting with the first page number, which is 1.

public long

Returns:

the page to be returned.
page()

Returns the page to be returned.

public boolean

Returns:

true if the total number of elements should be retrieved from the database.
requestTotal()

Indicates that a query method which returns a Page should retrieve the total number of elements available across all pages.

public int

Returns:

the requested size of each page
size()

Returns the requested size of each page

public PageRequest

Returns:

a new instance of PageRequest. This method never returns null.
size(int
the number of query results in a full page.
maxPageSize)

Creates a new page request with the same pagination information, but with the specified maximum page size.

public PageRequest

Returns:

a page request with requestTotal() set to false.
withoutTotal()

Returns an otherwise-equivalent page request with requestTotal() set to false, so that totals will not be retrieved from the database.

public PageRequest

Returns:

a page request with requestTotal() set to true.
withTotal()

Returns an otherwise-equivalent page request with requestTotal() set to false, so that totals will be retrieved from the database.

Method Detail

afterCursorback to summary
public static PageRequest afterCursor(PageRequest.Cursor cursor, long pageNumber, int maxPageSize, boolean requestTotal)

Requests cursor-based pagination in the forward direction, starting after the specified key.

Parameters
cursor:PageRequest.Cursor

cursor with key values, the order and number of which must match the OrderBy annotations or OrderBy name pattern and the Order and Sort parameters of the repository method to which this page request will be supplied.

pageNumber:long

The page number.

maxPageSize:int

The number of query results in a full page.

requestTotal:boolean

Indicates whether to retrieve the total number of elements available across all pages.

Returns:PageRequest

a new instance of PageRequest with forward cursor-based pagination. This method never returns null.

Exceptions
IllegalArgumentException:
if the cursor is null or has no values.
afterCursorback to summary
public PageRequest afterCursor(PageRequest.Cursor cursor)

Requests cursor-based pagination in the forward direction, starting after the specified key.

Parameters
cursor:PageRequest.Cursor

cursor with key values, the order and number of which must match the OrderBy annotations, jakarta.data.Sort parameters, or OrderBy name pattern of the repository method to which this pagination will be supplied.

Returns:PageRequest

a new instance of PageRequest with forward cursor-based pagination. This method never returns null.

Exceptions
IllegalArgumentException:
if no key values are provided.
beforeCursorback to summary
public static PageRequest beforeCursor(PageRequest.Cursor cursor, long pageNumber, int maxPageSize, boolean requestTotal)

Requests cursor-based pagination in the previous page direction relative to the specified cursor.

Parameters
cursor:PageRequest.Cursor

cursor with key values, the order and number of which must match the OrderBy annotations or OrderBy name pattern and the Order and Sort parameters of the repository method to which this page request will be supplied.

pageNumber:long

The page number.

maxPageSize:int

The number of query results in a full page.

requestTotal:boolean

Indicates whether to retrieve the total number of elements available across all pages.

Returns:PageRequest

a new instance of PageRequest with cursor-based pagination in the previous page direction. This method never returns null.

Exceptions
IllegalArgumentException:
if the cursor is null or has no values.
beforeCursorback to summary
public PageRequest beforeCursor(PageRequest.Cursor cursor)

Requests cursor-based pagination in the previous page direction relative to the specified key values.

Parameters
cursor:PageRequest.Cursor

cursor with key values, the order and number of which must match the OrderBy annotations, jakarta.data.Sort parameters, or OrderBy name pattern of the repository method to which this pagination will be supplied.

Returns:PageRequest

a new instance of PageRequest with cursor-based pagination in the previous page direction. This method never returns null.

Exceptions
IllegalArgumentException:
if no key values are provided.
cursorback to summary
public Optional<PageRequest.Cursor> cursor()

Returns the key values which are the starting point for cursor-based pagination.

Returns:Optional<PageRequest.Cursor>

the cursor; Optional#empty() if using offset pagination.

equalsback to summary
public boolean equals(Object o)

Compares with another instance to determine if both represent the same pagination information.

Returns:boolean

true if both instances are of the same class and represent the same pagination information. Otherwise false.

Annotations
@Override
modeback to summary
public PageRequest.Mode mode()

Returns the type of pagination.

Returns:PageRequest.Mode

the type of pagination.

ofPageback to summary
public static PageRequest ofPage(long pageNumber)

Creates a new page request with the given page number and with a default size of 10.

Parameters
pageNumber:long

The page number.

Returns:PageRequest

a new instance of PageRequest. This method never returns null.

Exceptions
IllegalArgumentException:
when the page number is negative or zero.
ofPageback to summary
public static PageRequest ofPage(long pageNumber, int maxPageSize, boolean requestTotal)

Creates a new page request without a cursor.

Parameters
pageNumber:long

The page number.

maxPageSize:int

The number of query results in a full page.

requestTotal:boolean

Indicates whether to retrieve the total number of elements available across all pages.

Returns:PageRequest

a new instance of PageRequest. This method never returns null.

Exceptions
IllegalArgumentException:
when the page number is negative or zero.
ofSizeback to summary
public static PageRequest ofSize(int maxPageSize)

Creates a new page request for requesting pages of the specified size, starting with the first page number, which is 1.

Parameters
maxPageSize:int

The number of query results in a full page.

Returns:PageRequest

a new instance of PageRequest. This method never returns null.

Exceptions
IllegalArgumentException:
when maximum page size is negative or zero.
pageback to summary
public long page()

Returns the page to be returned.

Returns:long

the page to be returned.

requestTotalback to summary
public boolean requestTotal()

Indicates that a query method which returns a Page should retrieve the total number of elements available across all pages. This behavior is enabled by default. To obtain a page request with total retrieval disabled, call withoutTotal().

Returns:boolean

true if the total number of elements should be retrieved from the database.

sizeback to summary
public int size()

Returns the requested size of each page

Returns:int

the requested size of each page

sizeback to summary
public PageRequest size(int maxPageSize)

Creates a new page request with the same pagination information, but with the specified maximum page size. When a page is retrieved from the database, the number of elements in the page must be equal to the maximum page size unless there is an insufficient number of elements to retrieve from the database from the start of the page.

Parameters
maxPageSize:int

the number of query results in a full page.

Returns:PageRequest

a new instance of PageRequest. This method never returns null.

withoutTotalback to summary
public PageRequest withoutTotal()

Returns an otherwise-equivalent page request with requestTotal() set to false, so that totals will not be retrieved from the database. Note that when totals are not retrieved by a repository method with return type Page, the operations Page#totalElements() and Page#totalPages() throw an IllegalStateException when called.

Returns:PageRequest

a page request with requestTotal() set to false.

withTotalback to summary
public PageRequest withTotal()

Returns an otherwise-equivalent page request with requestTotal() set to false, so that totals will be retrieved from the database.

Returns:PageRequest

a page request with requestTotal() set to true.

jakarta.data.page back to summary

public Interface PageRequest.Cursor

Known Direct Implementers
jakarta.data.page.PageRequestCursor
A cursor that is formed from a key, relative to which a next or previous page can be requested.

Method Summary

Modifier and TypeMethod and Description
public List<?>

Returns:

an unmodifiable list containing the ordered values
elements()

An unmodifiable list of values in the key.

public boolean

Returns:

true or false.
equals(Object
a cursor against which to compare.
cursor)

Returns whether or not the values that make up the key of this cursor are equal to those of the supplied cursor.

public static PageRequest.Cursor

Returns:

a new instance of Cursor
forKey(Object...
the key
key)

Obtain an instance of Cursor for the given key.

public Object

Returns:

the key value at the specified position.
get(int
position (0 is first) of the key value to obtain.
index)

Returns the key value at the specified position.

public int

Returns:

a hash code based on the key values.
hashCode()

Returns a hash code based on the key values.

public int

Returns:

the number of values in the key.
size()

Returns the number of values in the key.

public String

Returns:

String representation of the cursor.
toString()

String representation of the cursor, including the number of key values in the cursor but not the values themselves.

Method Detail

elementsback to summary
public List<?> elements()

An unmodifiable list of values in the key.

Returns:List<?>

an unmodifiable list containing the ordered values

equalsback to summary
public boolean equals(Object cursor)

Returns whether or not the values that make up the key of this cursor are equal to those of the supplied cursor. Both instances must also have the same cursor implementation class in order to be considered equal.

Parameters
cursor:Object

a cursor against which to compare.

Returns:boolean

true or false.

Annotations
@Override
forKeyback to summary
public static PageRequest.Cursor forKey(Object... key)

Obtain an instance of Cursor for the given key.

Parameters
key:Object[]

the key

Returns:PageRequest.Cursor

a new instance of Cursor

getback to summary
public Object get(int index)

Returns the key value at the specified position.

Parameters
index:int

position (0 is first) of the key value to obtain.

Returns:Object

the key value at the specified position.

Exceptions
IndexOutOfBoundsException:
if the index is negative or greater than or equal to the size.
hashCodeback to summary
public int hashCode()

Returns a hash code based on the key values.

Returns:int

a hash code based on the key values.

Annotations
@Override
sizeback to summary
public int size()

Returns the number of values in the key.

Returns:int

the number of values in the key.

toStringback to summary
public String toString()

String representation of the cursor, including the number of key values in the cursor but not the values themselves.

Returns:String

String representation of the cursor.

Annotations
@Override
jakarta.data.page back to summary

public final Enum PageRequest.Mode

extends Enum<PageRequest.Mode>
Class Inheritance
The type of pagination: offset-based or cursor-based, which includes a direction.

Field Summary

Modifier and TypeField and Description
public static final PageRequest.Mode
CURSOR_NEXT

Indicates forward cursor-based pagination, which follows the direction of the sort criteria, using a cursor that is formed from the key of the last entity on the current page.

public static final PageRequest.Mode
CURSOR_PREVIOUS

Indicates a request for a page with cursor-based pagination in the previous page direction to the sort criteria, using a cursor that is formed from the key of first entity on the current page.

public static final PageRequest.Mode
OFFSET

Indicates a request for a page using offset pagination.

Constructor Summary

AccessConstructor and Description
private
Mode()

Method Summary

Modifier and TypeMethod and Description
public static PageRequest.Mode
valueOf(String name)

public static PageRequest.Mode[]
values()

Inherited from java.lang.Enum:
clonecompareTodescribeConstableequalsfinalizegetDeclaringClasshashCodenameordinaltoStringvalueOf

Field Detail

CURSOR_NEXTback to summary
public static final PageRequest.Mode CURSOR_NEXT

Indicates forward cursor-based pagination, which follows the direction of the sort criteria, using a cursor that is formed from the key of the last entity on the current page.

CURSOR_PREVIOUSback to summary
public static final PageRequest.Mode CURSOR_PREVIOUS

Indicates a request for a page with cursor-based pagination in the previous page direction to the sort criteria, using a cursor that is formed from the key of first entity on the current page. The order of results on each page follows the sort criteria and is not reversed.

OFFSETback to summary
public static final PageRequest.Mode OFFSET

Indicates a request for a page using offset pagination. The starting position for pages is computed as an offset from the first result based on the page number and maximum page size. Offset pagination is used when a cursor is not supplied.

Constructor Detail

Modeback to summary
private Mode()

Method Detail

valueOfback to summary
public static PageRequest.Mode valueOf(String name)
valuesback to summary
public static PageRequest.Mode[] values()