Package jakarta.data.page

package jakarta.data.page

Splits query results into slices or 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 slices or pages,

 Pageable.ofSize(25).sortBy(Sort.asc("lastName"),
                            Sort.asc("firstName"),
                            Sort.asc("id")); // unique identifier

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 slices or pages.

In Jakarta Data, a slice has most of the same functionality as a page, but does not offer a total count of results across all slices. Using slice rather than page is more efficient when a total count of results is not needed.

Slices and pages can be determined based on fixed positional index or relative to a cursor.

Slice and Page are computed based on their positional index within the list of results. For example, if you are on the first page of 10 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 slice/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 appliaction 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 KeysetAwareSlice and KeysetAwarePage. In this approach, queries for the next or previous page are performed relative to the last or first entry of the current page.

  • Class
    Description
    KeysetAwarePage<T>
    A page of results from a repository query that performs keyset pagination.
    KeysetAwareSlice<T>
    Keyset pagination is a form of pagination that aims to reduce the possibility of missed or duplicate results by making the request for each subsequent page relative to the observed values of entity properties from the current page.
    Page<T>
    A page is a sublist of results.
    Pageable
    This class represents pagination information.
    Pageable.Cursor
    Represents keyset values, which can be a starting point for requesting a next or previous page.
    Pageable.Mode
    The type of pagination, which can be offset pagination or keyset cursor pagination which includes a direction.
    Slice<T>
    A slice of data that indicates whether there's a next or previous slice available.