Interface PageIterator
-
public interface PageIterator
Provides paging functionality for sets of independent objects and repository rows.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 tonextPage
moves the iterator to the second page, and so on. ThenextPage
method returnstrue
until the end of the set is reached. When the iterator reaches the end of the set, it is positioned after the last page andnextPage
returnsfalse
.The
getCurrentPage
andgetElementCount
methods throw an exception if the iterator is positioned before the first page or after the last page, or between pages after areset(mark)
operation. For proper positioning, you must callnextPage
on a new iterator and after a reset operation. You may call thegetPageMark
method at any time. Of these methods, onlynextPage
moves the position of the iterator.The returned value of
getElementCount
is always equal togetCurrentPage().length
. UsegetElementCount
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 thereset(mark)
method resets the state of the iterator to a previously saved mark. Thereset
method positions the iterator before the marked page; thenextPage
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 thenextPage
method to position the iterator to the first page.The
getPageSize
andsetPageSize
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 tonextPage
. 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.
-
-
Method Summary
Methods Modifier and Type Method and Description java.lang.Object[]
getCurrentPage()
Returns the current page in the set.byte[]
getCurrentPageCheckpoint()
Returns an opaque representation of thePageIterator
that can act as a checkpoint for a later resumption viaFactory.PageIterator.resumeInstance
.int
getElementCount()
Returns the number of elements in the current page.byte[]
getNextPageCheckpoint()
Returns an opaque representation of thePageIterator
, but for the page following the current page.PageMark
getPageMark()
Returns the current page mark on which a subsequent call toreset
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.
-
-
-
Method Detail
-
nextPage
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.- Returns:
true
until the iterator reaches the end of the set, at which time this method returnsfalse
. Returnsfalse
if the set is empty.
-
getCurrentPage
java.lang.Object[] getCurrentPage()
Returns the current page in the set.- Returns:
- An
Object
array containing the current page. - Throws:
- if the iterator is positioned before the first page or after the last page, or between pages after aEngineRuntimeException
reset(mark)
operation.
-
getElementCount
int getElementCount()
Returns the number of elements in the current page. The returned value is always equal to the value returned bygetCurrentPage().length
. UsegetElementCount
to avoid copying the potentially large internal array just to get its length.- Returns:
- An integer value for the number of elements in the current page.
- Throws:
- if the iterator is positioned before the first page or after the last page, or between pages after aEngineRuntimeException
reset(mark)
operation.
-
getTotalCount
java.lang.Integer getTotalCount()
Returns the count requested in a search that includes OPTIONS (COUNT_LIMIT N).- Returns:
- An Integer for the result count found. The possible values are:
- A null value to indicate that this is the last page, the count limit is less than or equal to the page size, or counting is disabled on the server.
- A value greater than zero to indicate an exact count; that is, all the rows were found, and the number found is less than the count limit.
- A negative of the
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.
-
getPageSize
int getPageSize()
Returns the internal paging size used by the iterator.- Returns:
- An integer value for the page size.
-
setPageSize
void setPageSize(int pageSize)
Sets the internal paging size used by the iterator. The new size takes effect on the next fetch from the server.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.
- Parameters:
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.)
-
reset
void reset()
Positions the iterator to a point before the first page of the collection. You must callnextPage
to position the iterator to the first page.
-
getPageMark
PageMark getPageMark()
Returns the current page mark on which a subsequent call toreset
will operate. Call this method before calling thereset(mark)
method.- Returns:
- A
PageMark
object corresponding to a particular page within the collection.
-
reset
void reset(PageMark mark)
Sets the iterator back to a specified page of results. Call this method after establishing the current page mark with thegetPageMark
method. You must callnextPage
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 callgetPageMark
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 callingreset(mark)
followed bynextPage
).- Parameters:
mark
- APageMark
object representing a previously saved page within the collection.
-
getCurrentPageCheckpoint
byte[] getCurrentPageCheckpoint()
Returns an opaque representation of thePageIterator
that can act as a checkpoint for a later resumption viaFactory.PageIterator.resumeInstance
. The checkpoint does not preserve theConnection
information, the security context information, or the list of items in the page. Although thebyte[]
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 aPageIterator
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 thePageIterator
state of such non-pageable collections. This method throwsEngineRuntimeException
if you try to create a checkpoint for that kind of collection.
-
getNextPageCheckpoint
byte[] getNextPageCheckpoint()
Returns an opaque representation of thePageIterator
, 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.- See Also:
getCurrentPageCheckpoint()
-
-