Package jakarta.data.page

package jakarta.data.page

Splits query results into pages.

For query results that are expected to be large, it can be useful to read the results in separate parts instead of retrieving all of the results from the database at once.

To accomplish this, ensure that the results are sorted in a consistent order. This is often done by having the final sort criterion be the unique identifier, but it can be achieved by other means as long as the order is guaranteed to be deterministic. Here is an example of sort criteria to allow data to be read in pages,

 Order<Person> sorts = Order.by(Sort.asc("lastName"),
                                Sort.asc("firstName"),
                                Sort.asc("id")); // unique identifier
 Page<Person> page1 = people.findByAge(50, sorts, PageRequest.ofSize(25));

In the example above, even if multiple people have the same last names and same first names, the results will always be in the same order due to the unique identifier. The predictable order makes it possible to retrieve the query results from the database in separate pages.

Pages can be determined based on fixed positional offset or relative to a cursor.

The elements of a Page are computed based on their positional offset within the list of results. For example, if we have obtained the first page of 10 results and request the next page, the database identifies the matching entities for the query at positions 11 through 20 and retrieves them. Results are predictable if data is not modified in between page requests. If additional entities were inserted prior to requesting the second page then some of the entities that are retrieved for the second page might have also appeared on the first page. Similarly, if entities from the first page were instead removed prior to requesting the second page, then the second page will not include the entities that have now moved into positions 1 to 10.

For situations where the above must be avoided or the application wishes to avoid the performance cost of the database re-scanning data from previous pages (to determine the position), Jakarta Data offers a cursor based approach with CursoredPage. In this approach, queries for the next or previous page are performed relative to the last or first entry of the current page.

The module Javadoc provides an overview of Jakarta Data.

  • Class
    Description
    CursoredPage<T>
    A page of data retrieved to satisfy a given page request, with a cursor for each result on the page.
    Page<T>
    A page contains the data that is retrieved to satisfy a given page request.
    PageRequest
    A request for a single well-specified page of query results.
    PageRequest.Cursor
    A cursor that is formed from a key, relative to which a next or previous page can be requested.
    PageRequest.Mode
    The type of pagination: offset-based or cursor-based, which includes a direction.