Module jakarta.data
Package jakarta.data.page

Interface PageRequest

public interface PageRequest

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:


 @Find
 @OrderBy("age")
 @OrderBy("ssn")
 Page<Person> agedBetween(@By("age") @Is(AtLeast.class) int minAge,
                          @By("age") @Is(AtMost.class) int maxAge,
                          PageRequest pageRequest);

This method might be called as follows:


 Page<Person> page = people.agedBetween(
                35, 59,
                PageRequest.ofSize(100));
 List<Person> results = page.content();
 ...
 while (page.hasNext()) {
     page = people.agedBetween(
                35, 59,
                page.nextPageRequest().withoutTotal());
     results = page.content();
     ...
 }

A repository method may not be declared with:

  • more than one parameter of type PageRequest or Limit,
  • a parameter of type PageRequest and a parameter of type Limit, or
  • a parameter of type PageRequest in combination with the First annotation or the keyword First.

Instances of PageRequest are immutable.

  • Method Details

    • ofPage

      static PageRequest ofPage(long pageNumber)
      Creates a new page request with the given page number and with a default size of 10.
      Parameters:
      pageNumber - The page number.
      Returns:
      a new instance of PageRequest. This method never returns null.
      Throws:
      IllegalArgumentException - when the page number is negative or zero.

    • ofPage

      static PageRequest ofPage(long pageNumber, int maxPageSize, boolean requestTotal)
      Creates a new page request without a cursor.
      Parameters:
      pageNumber - The page number.
      maxPageSize - The number of query results in a full page.
      requestTotal - Indicates whether to retrieve the total number of elements available across all pages.
      Returns:
      a new instance of PageRequest. This method never returns null.
      Throws:
      IllegalArgumentException - when the page number is negative or zero.

    • ofSize

      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 - The number of query results in a full page.
      Returns:
      a new instance of PageRequest. This method never returns null.
      Throws:
      IllegalArgumentException - when maximum page size is negative or zero.

    • afterCursor

      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 - 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 - The page number.
      maxPageSize - The number of query results in a full page.
      requestTotal - Indicates whether to retrieve the total number of elements available across all pages.
      Returns:
      a new instance of PageRequest with forward cursor-based pagination. This method never returns null.
      Throws:
      IllegalArgumentException - if the cursor is null or has no values.

    • beforeCursor

      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 - 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 - The page number.
      maxPageSize - The number of query results in a full page.
      requestTotal - Indicates whether to retrieve the total number of elements available across all pages.
      Returns:
      a new instance of PageRequest with cursor-based pagination in the previous page direction. This method never returns null.
      Throws:
      IllegalArgumentException - if the cursor is null or has no values.

    • afterCursor

      PageRequest afterCursor(PageRequest.Cursor cursor)

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

      Parameters:
      cursor - cursor with key values, the order and number of which must match the OrderBy annotations, Sort parameters, or OrderBy name pattern of the repository method to which this pagination will be supplied.
      Returns:
      a new instance of PageRequest with forward cursor-based pagination. This method never returns null.
      Throws:
      IllegalArgumentException - if no key values are provided.

    • beforeCursor

      PageRequest beforeCursor(PageRequest.Cursor cursor)

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

      Parameters:
      cursor - cursor with key values, the order and number of which must match the OrderBy annotations, Sort parameters, or OrderBy name pattern of the repository method to which this pagination will be supplied.
      Returns:
      a new instance of PageRequest with cursor-based pagination in the previous page direction. This method never returns null.
      Throws:
      IllegalArgumentException - if no key values are provided.

    • equals

      boolean equals(Object o)
      Compares with another instance to determine if both represent the same pagination information.
      Overrides:
      equals in class Object
      Returns:
      true if both instances are of the same class and represent the same pagination information. Otherwise false.

    • cursor

      Optional<PageRequest.Cursor> cursor()
      Returns the key values which are the starting point for cursor-based pagination.
      Returns:
      the cursor; Optional.empty() if using offset pagination.

    • mode

      PageRequest.Mode mode()
      Returns the type of pagination.
      Returns:
      the type of pagination.

    • page

      long page()
      Returns the page to be returned.
      Returns:
      the page to be returned.

    • size

      int size()
      Returns the requested size of each page
      Returns:
      the requested size of each page

    • requestTotal

      boolean requestTotal()

      Indicates that a query method which returns a Page should retrieve the total number of elements available across all pages. The ability to retrieve totals is enabled by default for JCQL queries but is not available for native SQL queries and some JPQL queries. To obtain a page request with total retrieval disabled, call withoutTotal().

      A repository implementation might obtain a total from the database before returning the page of results, or might defer fetching the total until Page.totalElements() or Page.totalPages() method is invoked. In the case of deferred fetching, the call to totalElements() or totalPages() raises an exception if the database request fails or if the database is incapable of computing totals.

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

    • page

      PageRequest page(long pageNumber)

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

      Parameters:
      pageNumber - the page number.
      Returns:
      a new instance of PageRequest. This method never returns null.
      Since:
      1.1

    • size

      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 - the number of query results in a full page.
      Returns:
      a new instance of PageRequest. This method never returns null.

    • withoutTotal

      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:
      a page request with requestTotal() set to false.

    • withTotal

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