com.bea.p13n.pagination
Interface PagedResult<T>

All Superinterfaces

Serializable

All Known Subinterfaces:

FilterablePagedResult<T>, ICMPagedResult<T>, SortableFilterablePagedResult<T>, SortablePagedResult<T>

public interface PagedResult<T>
extends Serializable

Result of some query, organized as pages. Each page consists of some number (usually page size) of beans (T), and is accessed via an Iterator.

It is generally expected that most implementations will be backed by something like database queries, and should be optimized for paganated access. That is, rather than retrieving a full set of results into memory and breaking that into pages, the implementation should retrieve results a page (or a few pages) at a time, and return those via this interface.

The objects contained on the pages should be Java Beans or Strings, since sorting and filtering of these objects is done based on bean properties.

A PagedResult must be Serializable so that it can be stored, for example, in the HttpSession for use across several requests.

See Also

SortablePagedResult, FilterablePagedResult, SortableFilterablePagedResult

Field Summary

static int

COUNT_UNKNOWN Represents an unknown count.

Method Summary

void	close() Close the result and release any resources which it holds.
int	getCurrentPageNumber() Get the current page number.
Iterator<T>	getPage(int pageNumber) Get the specified page.
int	getPageCount() How many pages are available.
int	getPageSize() Get the size of the pages.
int	getTotalItemCount() Get the total number of items represented by these pages.
boolean	hasNextPage() Is there a next page? Will a call to nextPage() succeed?
boolean	hasPage(int pageNumber) Does the given page exist? Should a call to getPage( pageNumber ) succeed? Generally, this means that getPageNumber() < getPageCount(), but some iterators may not allow random access to all pages, in which case this might return false even when you could get to that page using next/previous.
boolean	hasPreviousPage() Is there a previous page? Will a call to previousPage() succeed?
boolean	isCompleteResults() Does this result represent a complete set of results? If not, then probably the maximum number of query results was reached and this iterator only represents a subset of the actual query.
boolean	isGetPageSupported() Does this iterator allow random access to pages? This method (vs.
Iterator<T>	nextPage() Get an iterator of the next page full of things.
Iterator<T>	previousPage() Get an iterator of the previous page full of things.
void	resize(int pageSize) Set a new page size.

Field Detail

COUNT_UNKNOWN

static final int COUNT_UNKNOWN

Represents an unknown count.

See Also

getTotalItemCount(), getPageCount(), Constants Summary

Method Detail

getPageSize

int getPageSize()

Get the size of the pages. Each call to, for example, nextPage, should return (aproximately) this many items. Do not rely on this number to iterate thru the items, as some pages (like the last page) may have fewer.

getTotalItemCount

int getTotalItemCount()

Get the total number of items represented by these pages. Might return COUNT_UNKNOWN, if the number of items is indeterminant.

getPageCount

int getPageCount()

How many pages are available. Sometimes this might be indeterminent, for example in a large search where the implementation does not know the true size of the result until it reaches the end. In that case, this method should return COUNT_UNKNOWN. If it does return a value, then getPage( getPageCount() - 1 ) must return the last page of results.

isCompleteResults

boolean isCompleteResults()

Does this result represent a complete set of results? If not, then probably the maximum number of query results was reached and this iterator only represents a subset of the actual query.

getCurrentPageNumber

int getCurrentPageNumber()

Get the current page number. This will be the number of the page retrieved by the last call to nextPage, previousPage, or getPage. If none of those methods have yet been called, it should return -1 (because the next page will be page 0, the first page).

hasNextPage

boolean hasNextPage()

Is there a next page? Will a call to nextPage() succeed?

nextPage

Iterator<T> nextPage()
                     throws NoSuchElementException

Get an iterator of the next page full of things.

Throws

NoSuchElementException - if there is no next page.

hasPreviousPage

boolean hasPreviousPage()

Is there a previous page? Will a call to previousPage() succeed?

previousPage

Iterator<T> previousPage()
                         throws NoSuchElementException

Get an iterator of the previous page full of things.

Throws

NoSuchElementException - if there is no previous page.

isGetPageSupported

boolean isGetPageSupported()

Does this iterator allow random access to pages? This method (vs. hasPage) can be used by a GUI to decide if presenting a "go to page" button or field is appropriate.

hasPage

boolean hasPage(int pageNumber)

Does the given page exist? Should a call to getPage( pageNumber ) succeed? Generally, this means that getPageNumber() < getPageCount(), but some iterators may not allow random access to all pages, in which case this might return false even when you could get to that page using next/previous.

getPage

Iterator<T> getPage(int pageNumber)
                    throws IndexOutOfBoundsException,
                           UnsupportedOperationException

Get the specified page.

Throws

IndexOutOfBoundsException - if the pageNumber is negative or is after the last page.

UnsupportedOperationException - if this PageIterator does not support random access of pages (or of that page).

close

void close()

Close the result and release any resources which it holds. Users must call this when finished using this object.

resize

void resize(int pageSize)
            throws IllegalArgumentException

Set a new page size. When a new page size is set, a PageIterator is REQUIRED to reset itself to "before" page one, so that nextPage will then return a new first page with the new sizing.

Throws

IllegalArgumentException - if pageSize is less than or equal to zero