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