Package oracle.dbtools.plugin.api.pagination

## 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 PaginationState` | `NOT_PAGINATED` | Constant denoting the pagination state (or rather lack of state) of a non-paginated resource.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `finished()` | Indicates if the required number of items have been added to the page
    `java.lang.String` | `first()` | Returns a fully qualified URI for the link to the first page of items
    `long` | `limit()` | The maximum number of items to appear in the page.
    `java.lang.String` | `next()` | Returns a fully qualified URI for the link to the next page of items, IFF there is a subsequent page.
    `long` | `offset()` | The offset of the first item to appear in the page
    `java.lang.String` | `previous()` | 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 Detail

    - #### NOT_PAGINATED

          static final PaginationState NOT_PAGINATED

      Constant denoting the pagination state (or rather lack of state) of a non-paginated resource.

  - ### Method Detail

    - #### 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

          java.lang.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

          java.lang.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

          java.lang.String first()

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