Interface PaginationState


public interface PaginationState

Tracks the state required for paginating a subset of items in a collection.

Note that an n+1 querying model is used to reliably detect the last page in a set of results. For example if a collection contains 99 items with 10 items per page, then there should be 10 pages of results, 9 pages with 10 items per page, and the final page with 9 items. The fact that the final page has less than the expected 10 items indicates that the end of the collection has been reached, and that the final page MUST NOT have a next page link.

Now consider if the collection contained 100 items, we still expect 10 pages of results, but the last page will contain 10 items. There is no way to detect when generating the 10th page if a next page link should be included or not.

To address this problem, for every page of size n, we actually retrieve n+1 items. In the case of the above collection we attempt to retrieve 11 items, 10 are displayed and the last result is discarded. When displaying the next page. When we get to the last page, we attempt to retrieve 11 items, but are only returned 10, and so we can detect the end of the collection properly.

Author:
cdivilly
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final PaginationState
    Constant denoting the pagination state (or rather lack of state) of a non-paginated resource.
  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    Indicates if the required number of items have been added to the page
    Returns a fully qualified URI for the link to the first page of items
    long
    The maximum number of items to appear in the page.
    Returns a fully qualified URI for the link to the next page of items, IFF there is a subsequent page.
    long
    The offset of the first item to appear in the page
    Returns a fully qualified URI for the link to the previous page of items
    boolean
    showItem(long index)
    Must be called by the client paging the resource, each time a new item is about to be added to the page.
  • Field Details

    • NOT_PAGINATED

      static final PaginationState NOT_PAGINATED
      Constant denoting the pagination state (or rather lack of state) of a non-paginated resource.
  • Method Details

    • finished

      boolean finished()
      Indicates if the required number of items have been added to the page
      Returns:
      true if the required number of items has been added to the page, false otherwise
    • next

      String next()
      Returns a fully qualified URI for the link to the next page of items, IFF there is a subsequent page.
      Returns:
      Link to the next page, or null if the end of the collection has been reached.
    • offset

      long offset()
      The offset of the first item to appear in the page
      Returns:
      item offset
    • limit

      long limit()
      The maximum number of items to appear in the page. Note that this method will return the actual limit value + 1, because Pagination requires doing an N+1 query so that the end of the result set can be detected.
      Returns:
      maximum number of items
    • previous

      String previous()
      Returns a fully qualified URI for the link to the previous page of items
      Returns:
      Link to the previous page, or null if there is no previous page
    • showItem

      boolean showItem(long index)
      Must be called by the client paging the resource, each time a new item is about to be added to the page. The returned value should be checked to indicate whether the item should actually be displayed in the page, due to the n+1 paging model the final result in a page is discarded, and MUST NOT be displayed.
      Parameters:
      index - The zero based index of the item added to the page
      Returns:
      True if the item should be added to the page, false otherwise
    • first

      String first()
      Returns a fully qualified URI for the link to the first page of items
      Returns:
      Link to the first page