Package jakarta.data.page

Interface Pageable

public interface Pageable

This class represents pagination information.

Pageable is optionally specified as a parameter to a repository method in one of the parameter positions after the query parameters. For example,

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

 ...
 for (Pageable p = Pageable.ofSize(100); p != null; p = page.length == 0 ? null : p.next()) {
   page = people.findByAgeBetween(35, 59, p);
   ...
 }

A repository method will fail with a DataException or a more specific subclass if

  • multiple Pageable parameters are supplied to the same method.
  • Pageable and Limit parameters are supplied to the same method.
  • a Pageable parameter is supplied in combination with the First keyword.
  • a Pageable parameter is supplied and separate Sort parameters are also supplied to the same method.
  • the database is incapable of ordering with the requested sort criteria.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static interface 
    Pageable.Cursor
    Represents keyset values, which can be a starting point for requesting a next or previous page.
    static enum 
    Pageable.Mode
    The type of pagination, which can be offset pagination or keyset cursor pagination which includes a direction.

  • Method Summary

    Modifier and Type
    Method
    Description
    Pageable
    afterKeyset(Object... keyset)
    Requests keyset pagination in the forward direction, starting after the specified keyset values.
    Pageable
    afterKeysetCursor(Pageable.Cursor keysetCursor)
    Requests keyset pagination in the forward direction, starting after the specified keyset values.
    Pageable
    beforeKeyset(Object... keyset)
    Requests keyset pagination in the reverse direction, starting after the specified keyset values.
    Pageable
    beforeKeysetCursor(Pageable.Cursor keysetCursor)
    Requests keyset pagination in the reverse direction, starting after the specified keyset values.
    Pageable.Cursor
    cursor()
    Returns the keyset values which are the starting point for keyset pagination.
    boolean
    equals(Object o)
    Compares with another instance to determine if both represent the same pagination information.
    Pageable.Mode
    mode()
    Returns the type of pagination.
    Pageable
    next()
    Returns the Pageable requesting the next page if using offset pagination.
    static Pageable
    ofPage(long pageNumber)
    Creates a new Pageable with the given page number and with a default size of 10.
    static Pageable
    ofSize(int maxPageSize)
    Creates a new Pageable for requesting pages of the specified size, starting with the first page number, which is 1.
    long
    page()
    Returns the page to be returned.
    Pageable
    page(long pageNumber)
    Creates a new Pageable instance representing the same pagination information, except with the specified page number.
    int
    size()
    Returns the requested size of each page
    Pageable
    size(int maxPageSize)
    Creates a new Pageable instance representing the same pagination information, except with the specified maximum page size.
    Pageable
    sortBy(Sort... sorts)
    Creates a new Pageable instance representing the same pagination information, except using the specified sort criteria.
    Pageable
    sortBy(Iterable<Sort> sorts)
    Creates a new Pageable instance representing the same pagination information, except using the specified sort criteria.
    List<Sort>
    sorts()
    Return the order collection if it was specified on this Pageable, otherwise an empty list.

  • Method Details

    • ofPage

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

    • ofSize

      static Pageable ofSize(int maxPageSize)
      Creates a new Pageable 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 Pageable. This method never returns null.
      Throws:
      IllegalArgumentException - when maximum page size is negative or zero.

    • afterKeyset

      Pageable afterKeyset(Object... keyset)

      Requests keyset pagination in the forward direction, starting after the specified keyset values.

      Parameters:
      keyset - keyset 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 Pageable with forward keyset pagination. This method never returns null.
      Throws:
      IllegalArgumentException - if no keyset values are provided.

    • beforeKeyset

      Pageable beforeKeyset(Object... keyset)

      Requests keyset pagination in the reverse direction, starting after the specified keyset values.

      Parameters:
      keyset - keyset 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 Pageable with reverse keyset pagination. This method never returns null.
      Throws:
      IllegalArgumentException - if no keyset values are provided.

    • afterKeysetCursor

      Pageable afterKeysetCursor(Pageable.Cursor keysetCursor)

      Requests keyset pagination in the forward direction, starting after the specified keyset values.

      Parameters:
      keysetCursor - cursor with keyset 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 Pageable with forward keyset pagination. This method never returns null.
      Throws:
      IllegalArgumentException - if no keyset values are provided.

    • beforeKeysetCursor

      Pageable beforeKeysetCursor(Pageable.Cursor keysetCursor)

      Requests keyset pagination in the reverse direction, starting after the specified keyset values.

      Parameters:
      keysetCursor - cursor with keyset 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 Pageable with reverse keyset pagination. This method never returns null.
      Throws:
      IllegalArgumentException - if no keyset 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

      Pageable.Cursor cursor()
      Returns the keyset values which are the starting point for keyset pagination.
      Returns:
      the keyset values; null if using offset pagination.

    • mode

      Pageable.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

    • sorts

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

    • next

      Pageable next()

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

      If using keyset pagination, traversal of pages must only be done via the KeysetAwareSlice.nextPageable(), KeysetAwareSlice.previousPageable(), or keyset cursor, not with this method.

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

    • page

      Pageable page(long pageNumber)

      Creates a new Pageable instance representing the same pagination information, except with the specified page number.

      Parameters:
      pageNumber - The page number
      Returns:
      a new instance of Pageable. This method never returns null.

    • size

      Pageable size(int maxPageSize)

      Creates a new Pageable instance representing the same pagination information, except with the specified maximum page size.

      Parameters:
      maxPageSize - the number of query results in a full page.
      Returns:
      a new instance of Pageable. This method never returns null.

    • sortBy

      Pageable sortBy(Iterable<Sort> sorts)

      Creates a new Pageable instance representing the same pagination information, except 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 Pageable. This method never returns null.

    • sortBy

      Pageable sortBy(Sort... sorts)

      Creates a new Pageable instance representing the same pagination information, except 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:
      sorts - sort criteria to use. This method can be invoked without parameters to request a Pageable that does not specify sort criteria.
      Returns:
      a new instance of Pageable. This method never returns null.