public interface PageIterator
Sets of independent objects and repository rows are divided into pages; each page is a number of collection elements (objects or rows) that represent a subset of the collection elements. You can iterate a page at a time instead of one object or row at a time. As an example, if a page is defined as 10 elements, and the collection has a total of 22 elements, the first paging operation returns a page containing 10 elements, the second page returns the next 10 elements, and the third page returns the last 2 elements. This page iteration is especially useful for interactive applications that display a page of information at a time.
Each page iterator is initially positioned before the first page of the set.
The first call to the nextPage
method moves the iterator to the first page.
The second call to nextPage
moves the iterator to the second page,
and so on. The nextPage
method returns true
until the end of the set is reached. When the iterator reaches the end of the set,
it is positioned after the last page and nextPage
returns false
.
The getCurrentPage
and getElementCount
methods throw an exception if the
iterator is positioned before the first page or after the last page, or between pages
after a reset(mark)
operation. For proper positioning, you
must call nextPage
on a new iterator and after a reset operation. You
may call the getPageMark
method at any time. Of these methods, only
nextPage
moves the position of the iterator.
The returned value of getElementCount
is always equal to
getCurrentPage().length
. Use getElementCount
to
avoid copying the potentially large internal array just to get its length.
You can also get the current page continuation state (that is, the page on which
the iterator will continue with the next call) and reset the
iterator back to a previous page of results. The saved position of the iterator
is called a "page mark". The getPageMark
method retrieves
the current mark, and the reset(mark)
method resets the state of the
iterator to a previously saved mark. The reset
method positions the iterator
before the marked page; the nextPage
method must be called to position the
iterator to the marked page. It is also possible to mark and reset to the position
before the first page and the position after the last page.
The reset
method (with no parameters) positions the iterator before the first
page of the collection. This is essentially the same as getting a new iterator
from the collection. You must then call the nextPage
method to position the iterator
to the first page.
The getPageSize
and setPageSize
methods allow you to
query and adjust the internal paging size of the iterator. The new size takes
effect on the next fetch from the server. This is typically on the next call to
nextPage
. The actual size of each returned page may be smaller (including zero) or larger than
the requested page size.
The first page of a set may be pre-fetched from the server and cached in the client. All iterators of a set with a pre-fetched first page may return the same first page. All iterators fetch subsequent pages, if any, directly from the server.
Modifier and Type | Method and Description |
---|---|
java.lang.Object[] |
getCurrentPage()
Returns the current page in the set.
|
byte[] |
getCurrentPageCheckpoint()
Returns an opaque representation of the
PageIterator that can act as
a checkpoint for a later resumption via Factory.PageIterator.resumeInstance . |
int |
getElementCount()
Returns the number of elements in the current page.
|
byte[] |
getNextPageCheckpoint()
Returns an opaque representation of the
PageIterator , but for the page
following the current page. |
PageMark |
getPageMark()
Returns the current page mark on which a subsequent call to
reset will operate. |
int |
getPageSize()
Returns the internal paging size used by the iterator.
|
java.lang.Integer |
getTotalCount()
Returns the count requested in a search that includes
OPTIONS (COUNT_LIMIT N).
|
boolean |
nextPage()
Moves the iterator to the first page in the set on the first call and to the next page
in the set on subsequent calls.
|
void |
reset()
Positions the iterator to a point before the first page of the collection.
|
void |
reset(PageMark mark)
Sets the iterator back to a specified page of results.
|
void |
setPageSize(int pageSize)
Sets the internal paging size used by the iterator.
|
boolean nextPage()
true
until the iterator reaches the end of the set, at which
time this method returns false
. Returns false
if the set is empty.java.lang.Object[] getCurrentPage()
Object
array containing the current page.EngineRuntimeException
- if the iterator is positioned
before the first page or after the last page, or between pages
after a reset(mark)
operation.int getElementCount()
getCurrentPage().length
. Use
getElementCount
to avoid copying the potentially large internal array just to get its length.EngineRuntimeException
- if the iterator is positioned
before the first page or after the last page, or between pages
after a reset(mark)
operation.java.lang.Integer getTotalCount()
COUNT_LIMIT
value to indicate that the minimum count was found,
meaning that the count is at least N. If Top M is specified on the search, counting is not done
past M , and an exact count is returned if the number of rows found is less than or equal to M
when M <= N.int getPageSize()
void setPageSize(int pageSize)
Typical use cases for changing the page size is to match the number of displayed elements in a user interface or to improve performance of page retrieval.
pageSize
- An integer value for the page size. If less than 1 or if not set, the
server's default page size is used. (See the
QueryPageDefaultSize property.)
void reset()
nextPage
to position the iterator to the first page.PageMark getPageMark()
reset
will operate.
Call this method before calling the reset(mark)
method.PageMark
object corresponding to a particular page within
the collection.void reset(PageMark mark)
getPageMark
method. You must call nextPage
to position the iterator to the
marked page.
As an example, if you call nextPage
twice, the iterator is
positioned on the second page of elements. You can then call getPageMark
to get and save the page mark for that second page, which you can use later
to reposition the iterator on the second page again (by calling reset(mark)
followed by nextPage
).
mark
- A PageMark
object representing a previously saved page within
the collection.byte[] getCurrentPageCheckpoint()
PageIterator
that can act as
a checkpoint for a later resumption via Factory.PageIterator.resumeInstance
.
The checkpoint does not preserve the Connection
information, the security
context information, or the list of items in the page.
Although the byte[]
containing the checkpoint is reasonably compact, it
can generally be made smaller by using generic compression. The information in the
checkpoint is not encrypted or masked because it is not considered sensitive from the
point of view of the API.
Some collections with a PageIterator
are not actually pageable. The collection
already holds all items in the set. Because a checkpoint does not include the
individual items, it cannot be used to restore the PageIterator
state of
such non-pageable collections. This method throws EngineRuntimeException
if you try to create a checkpoint for that kind of collection.byte[] getNextPageCheckpoint()
PageIterator
, but for the page
following the current page. This method requires no server round-trips, so it is
more efficient to use this method if you will be interested in the next page as soon
as you resume from the checkpoint.getCurrentPageCheckpoint()
© Copyright IBM Corporation 2006, 2015. All rights reserved.