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

Method Summary

Modifier and Type	Method and Description
boolean	finished() Indicates if the required number of items have been added to the page
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.
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
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

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