Package jakarta.data.page

Interface PageRequest<T>

Type Parameters:
T - entity class of the attributes that are used as sort criteria.
public interface PageRequest<T>

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<Person> pageRequest);

 ...
 for (PageRequest<Person> p = PageRequest.of(Person.class).size(100);
      p != null; p = page.length == 0 ? null : p.next()) {
   page = people.findByAgeBetween(35, 59, p);
   ...
 }

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 keyword First.

A repository method throws IllegalArgumentException if it is called with an argument of type PageRequest with nonempty sort criteria, and a separate argument or arguments of type Sort or Order.

A repository method throws DataException if the database is incapable of ordering the query results using the given sort criteria.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    PageRequest.Cursor
    A cursor that is formed from a key, relative to which a next or previous page can be requested.
    static enum 
    PageRequest.Mode
    The type of pagination: offset-based or cursor-based, which includes a direction.

  • Method Summary

    Modifier and Type
    Method
    Description
    PageRequest<T>
    afterCursor(PageRequest.Cursor cursor)
    Requests cursor-based pagination in the forward direction, starting after the specified key.
    PageRequest<T>
    afterKey(Object... key)
    Requests cursor-based pagination in the forward direction, starting after the specified key.
    PageRequest<T>
    asc(String property)
    Creates a new page request with the same pagination information, appending the specified ascending sort with lower priority than all other sort criteria (if any) that have already been specified.
    PageRequest<T>
    ascIgnoreCase(String property)
    Creates a new page request with the same pagination information, appending the specified case-insensitive ascending sort with lower priority than all other sort criteria (if any) that have already been specified.
    PageRequest<T>
    beforeCursor(PageRequest.Cursor cursor)
    Requests cursor-based pagination in the previous page direction relative to the specified key values.
    PageRequest<T>
    beforeKey(Object... key)
    Requests cursor-based pagination in the previous page direction relative to the specified key.
    Optional<PageRequest.Cursor>
    cursor()
    Returns the key values which are the starting point for cursor-based pagination.
    PageRequest<T>
    desc(String property)
    Creates a new page request with the same pagination information, appending the specified descending sort with lower priority than all other sort criteria (if any) that have already been specified.
    PageRequest<T>
    descIgnoreCase(String property)
    Creates a new page request with the same pagination information, appending the specified case-insensitive descending sort with lower priority than all other sort criteria (if any) that have already been specified.
    boolean
    equals(Object o)
    Compares with another instance to determine if both represent the same pagination information.
    PageRequest.Mode
    mode()
    Returns the type of pagination.
    PageRequest<T>
    next()
    Returns the PageRequest requesting the next page if using offset pagination.
    static <T> PageRequest<T>
    of(Class<T> entityClass)
    Creates a page request to use when querying on entities of the specified entity class.
    static <T> PageRequest<T>
    ofPage(long pageNumber)
    Creates a new page request with the given page number and with a default size of 10.
    static <T> PageRequest<T>
    ofSize(int maxPageSize)
    Creates a new page request for requesting pages of the specified size, starting with the first page number, which is 1.
    long
    page()
    Returns the page to be returned.
    PageRequest<T>
    page(long pageNumber)
    Creates a new page request with the same pagination information, but with the specified page number.
    PageRequest<T>
    previous()
    Returns the PageRequest requesting the previous page if using offset pagination, or null if this is the first page, that is, when page() returns 1.
    boolean
    requestTotal()
    Indicates that a query method which returns a Page should retrieve the total number elements available across all pages.
    int
    size()
    Returns the requested size of each page
    PageRequest<T>
    size(int maxPageSize)
    Creates a new page request with the same pagination information, but with the specified maximum page size.
    PageRequest<T>
    sortBy(Sort<? super T> sort)
    Creates a new page request with the same pagination information, but using the specified sort criteria.
    PageRequest<T>
    sortBy(Sort<? super T> sort1, Sort<? super T> sort2)
    Creates a new page request with the same pagination information, but using the specified sort criteria.
    PageRequest<T>
    sortBy(Sort<? super T> sort1, Sort<? super T> sort2, Sort<? super T> sort3)
    Creates a new page request with the same pagination information, but using the specified sort criteria.
    PageRequest<T>
    sortBy(Sort<? super T> sort1, Sort<? super T> sort2, Sort<? super T> sort3, Sort<? super T> sort4)
    Creates a new page request with the same pagination information, but using the specified sort criteria.
    PageRequest<T>
    sortBy(Sort<? super T> sort1, Sort<? super T> sort2, Sort<? super T> sort3, Sort<? super T> sort4, Sort<? super T> sort5)
    Creates a new page request with the same pagination information, but using the specified sort criteria.
    PageRequest<T>
    sortBy(Iterable<Sort<? super T>> sorts)
    Creates a new page request with the same pagination information, but using the specified sort criteria.
    List<Sort<? super T>>
    sorts()
    Return the order collection if it was specified on this page request, otherwise an empty list.
    PageRequest<T>
    withoutTotal()
    Returns an otherwise-equivalent page request with requestTotal() set to false, so that totals will not be retrieved from the database.
    PageRequest<T>
    withTotal()
    Returns an otherwise-equivalent page request with requestTotal() set to false, so that totals will be retrieved from the database.

  • Method Details

    • of

      static <T> PageRequest<T> of(Class<T> entityClass)

      Creates a page request to use when querying on entities of the specified entity class.

      This method is useful for supplying the entity type when using untyped Sort instances. For example,

       PageRequest<Car> page1Request = PageRequest.of(Car.class).page(1).size(25).sortBy(
                                          Sort.desc("price"),
                                          Sort.asc("mileage"),
                                          Sort.asc("vin"));

      If using typed Sort instances from the StaticMetamodel, a more concise way to create page requests is to start with the Order class, as follows:

       PageRequest<Car> page1Request = Order.by(_Car.price.desc(),
                                       _Car.mileage.asc(),
                                       _Car.vin.asc())
                                   .page(1)
                                   .size(25);
      Type Parameters:
      T - entity class of attributes that can be used as sort criteria.
      Parameters:
      entityClass - entity class of attributes that can be used as sort criteria.
      Returns:
      a new instance of PageRequest. This method never returns null.

    • ofPage

      static <T> PageRequest<T> ofPage(long pageNumber)
      Creates a new page request with the given page number and with a default size of 10.
      Type Parameters:
      T - entity class of the attributes that are used as sort criteria.
      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.

    • ofSize

      static <T> PageRequest<T> ofSize(int maxPageSize)
      Creates a new page request for requesting pages of the specified size, starting with the first page number, which is 1.
      Type Parameters:
      T - entity class of the attributes that are used as sort criteria.
      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.

    • afterKey

      PageRequest<T> afterKey(Object... key)

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

      Parameters:
      key - values forming the key, 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 applied.
      Returns:
      a new instance of PageRequest with forward cursor-based pagination. This method never returns null.
      Throws:
      IllegalArgumentException - if no values are provided for the key.

    • beforeKey

      PageRequest<T> beforeKey(Object... key)

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

      Parameters:
      key - values forming the key, 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 applied.
      Returns:
      a new instance of PageRequest with cursor-based pagination in the previous page direction. This method never returns null.
      Throws:
      IllegalArgumentException - if no values are provided for the key.

    • afterCursor

      PageRequest<T> 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<T> 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.

    • asc

      PageRequest<T> asc(String property)

      Creates a new page request with the same pagination information, appending the specified ascending sort with lower priority than all other sort criteria (if any) that have already been specified.

      Parameters:
      property - name of the entity attribute upon which to sort.
      Returns:
      a new instance of PageRequest with the ascending sort as its lowest priority sort criteria.
      Throws:
      NullPointerException - when the property is null

    • ascIgnoreCase

      PageRequest<T> ascIgnoreCase(String property)

      Creates a new page request with the same pagination information, appending the specified case-insensitive ascending sort with lower priority than all other sort criteria (if any) that have already been specified. The case-insensitive sort means that the respective value in the database is compared independent of case.

      Parameters:
      property - name of the entity attribute upon which to sort.
      Returns:
      a new instance of PageRequest with the case-insensitive ascending sort as its lowest priority sort criteria.
      Throws:
      NullPointerException - when the property is null

    • desc

      PageRequest<T> desc(String property)

      Creates a new page request with the same pagination information, appending the specified descending sort with lower priority than all other sort criteria (if any) that have already been specified.

      Parameters:
      property - name of the entity attribute upon which to sort.
      Returns:
      a new instance of PageRequest with the descending sort as its lowest priority sort criteria.
      Throws:
      NullPointerException - when the property is null

    • descIgnoreCase

      PageRequest<T> descIgnoreCase(String property)

      Creates a new page request with the same pagination information, appending the specified case-insensitive descending sort with lower priority than all other sort criteria (if any) that have already been specified. The case-insensitive sort means that the respective value in the database is compared independent of case.

      Parameters:
      property - name of the entity attribute upon which to sort.
      Returns:
      a new instance of PageRequest with the case-insensitive descending sort as its lowest priority sort criteria.
      Throws:
      NullPointerException - when the property is null

    • 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 elements available across all pages. This behavior is enabled by default. To obtain a page request with total retrieval disabled, call withoutTotal().
      Returns:
      true if the total number of elements should be retrieved from the database.

    • sorts

      List<Sort<? super T>> sorts()
      Return the order collection if it was specified on this page request, otherwise an empty list.
      Returns:
      the order collection; will never be null.

    • next

      PageRequest<T> next()

      Returns the PageRequest requesting the next page if using offset pagination.

      If using cursor-based pagination, traversal of pages must only be done via the CursoredPage.nextPageRequest(), CursoredPage.previousPageRequest(), or cursor, not with this method.

      Returns:
      The next PageRequest.
      Throws:
      UnsupportedOperationException - if this PageRequest has a Cursor.

    • previous

      PageRequest<T> previous()

      Returns the PageRequest requesting the previous page if using offset pagination, or null if this is the first page, that is, when page() returns 1.

      If using cursor-based pagination, traversal of pages must only be done via the CursoredPage.nextPageRequest(), CursoredPage.previousPageRequest(), or cursor, not with this method.

      Returns:
      The previous PageRequest, or null if this is the first page.
      Throws:
      UnsupportedOperationException - if this PageRequest has a Cursor.

    • page

      PageRequest<T> 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.

    • size

      PageRequest<T> 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.

    • sortBy

      PageRequest<T> sortBy(Iterable<Sort<? super T>> sorts)

      Creates a new page request with the same pagination information, but using the specified sort criteria. The order of precedence for sort criteria is that of any statically specified sort criteria (from the OrderBy keyword, OrderBy annotation, or ORDER BY clause of a the Query annotation), followed by the order of the Iterable that is supplied to this method.

      Parameters:
      sorts - sort criteria to use.
      Returns:
      a new instance of PageRequest. This method never returns null.

    • sortBy

      PageRequest<T> sortBy(Sort<? super T> sort)

      Creates a new page request with the same pagination information, but using the specified sort criteria. The order of precedence for sort criteria is that of any statically specified sort criteria (from the OrderBy keyword, OrderBy annotation, or ORDER BY clause of a the Query annotation), followed by the order in which the Sort parameters to this method are listed.

      Parameters:
      sort - sort criteria to use.
      Returns:
      a new instance of PageRequest. This method never returns null.

    • sortBy

      PageRequest<T> sortBy(Sort<? super T> sort1, Sort<? super T> sort2)

      Creates a new page request with the same pagination information, but using the specified sort criteria. The order of precedence for sort criteria is that of any statically specified sort criteria (from the OrderBy keyword, OrderBy annotation, or ORDER BY clause of a the Query annotation), followed by the order in which the Sort parameters to this method are listed.

      Parameters:
      sort1 - dynamic sort criteria to use first.
      sort2 - dynamic sort criteria to use second.
      Returns:
      a new instance of PageRequest. This method never returns null.

    • sortBy

      PageRequest<T> sortBy(Sort<? super T> sort1, Sort<? super T> sort2, Sort<? super T> sort3)

      Creates a new page request with the same pagination information, but using the specified sort criteria. The order of precedence for sort criteria is that of any statically specified sort criteria (from the OrderBy keyword, OrderBy annotation, or ORDER BY clause of a the Query annotation), followed by the order in which the Sort parameters to this method are listed.

      Parameters:
      sort1 - dynamic sort criteria to use first.
      sort2 - dynamic sort criteria to use second.
      sort3 - dynamic sort criteria to use last.
      Returns:
      a new instance of PageRequest. This method never returns null.

    • sortBy

      PageRequest<T> sortBy(Sort<? super T> sort1, Sort<? super T> sort2, Sort<? super T> sort3, Sort<? super T> sort4)

      Creates a new page request with the same pagination information, but using the specified sort criteria. The order of precedence for sort criteria is that of any statically specified sort criteria (from the OrderBy keyword, OrderBy annotation, or ORDER BY clause of a the Query annotation), followed by the order in which the Sort parameters to this method are listed.

      Parameters:
      sort1 - dynamic sort criteria to use first.
      sort2 - dynamic sort criteria to use second.
      sort3 - dynamic sort criteria to use third.
      sort4 - dynamic sort criteria to use last.
      Returns:
      a new instance of PageRequest. This method never returns null.

    • sortBy

      PageRequest<T> sortBy(Sort<? super T> sort1, Sort<? super T> sort2, Sort<? super T> sort3, Sort<? super T> sort4, Sort<? super T> sort5)

      Creates a new page request with the same pagination information, but using the specified sort criteria. The order of precedence for sort criteria is that of any statically specified sort criteria (from the OrderBy keyword, OrderBy annotation, or ORDER BY clause of a the Query annotation), followed by the order in which the Sort parameters to this method are listed.

      Parameters:
      sort1 - dynamic sort criteria to use first.
      sort2 - dynamic sort criteria to use second.
      sort3 - dynamic sort criteria to use third.
      sort4 - dynamic sort criteria to use fourth.
      sort5 - dynamic sort criteria to use last.
      Returns:
      a new instance of PageRequest. This method never returns null.

    • withoutTotal

      PageRequest<T> 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<T> withTotal()
      Returns an otherwise-equivalent page request with requestTotal() set to false, so that totals will be retrieved from the database.
      Returns:
      a page request with requestTotal() set to true.