final class Cursor
extends java.lang.Object
This class is used by the DynamicQuery
class and requires that the
query it manages implement the Scrollable
interface. It is not
manipulated directly by business logic.
Modifier and Type | Field and Description |
---|---|
private boolean |
firstRowDeleted
Was the first row (or the last row if the scroll direction is backward) deleted by
deleteResultListEntry(boolean) ? |
private boolean |
forwardScroll
Flag indicating forward scroll direction
|
private boolean |
foundFirst
Have we visited the first result in the result set?
|
private boolean |
fullSet
Have we visited the full result set?
|
private static java.util.logging.Logger |
LOG
Logger
|
private double |
position
Current position within the results list
|
private Scrollable |
query
Scrollable query whose results are cursored
|
private Persistable[] |
referenceRow
Last fetched row used as the reference row for future iterations.
|
private RepositionCache |
repoCache
Map of primary key lists of query results to their result list rows
|
private java.util.List<java.lang.Object[]> |
results
Cached list of query results (as arrays of primary keys or DMOs)
|
Constructor and Description |
---|
Cursor(Scrollable query)
Constructor which associates the cursor with the query it is managing.
|
Modifier and Type | Method and Description |
---|---|
(package private) void |
addResultFirst(java.lang.Object[] data)
Store a result in the first position of the cached results list.
|
(package private) void |
addResultLast(java.lang.Object[] data)
Store a result in the last position of the cached results list.
|
(package private) void |
addResultNext(java.lang.Object[] data)
Add a result to the end of the cached results list.
|
(package private) void |
addResultPrevious(java.lang.Object[] data)
Prepend a result to the beginning of the cached results list.
|
private void |
addToRepoCache(java.lang.Object[] data)
Associate an array of primary key IDs representing a query result with
the cursor's current position.
|
(package private) boolean |
backward(int rows)
Move the current cursor position backward by the specified number of
rows.
|
(package private) boolean |
backward(NumberType rows)
Move the current cursor position backward by the specified number of
rows.
|
(package private) void |
beforeFirst()
Move the cursor to just before the index of the first entry, whether or
not it actually exists in the results list.
|
(package private) boolean |
contains(java.io.Serializable id,
int index)
Indicate whether the results cache contains the given ID within any of
its arrays.
|
(package private) integer |
currentRow()
Get the 1-based index of the current row in the result set.
|
(package private) boolean |
deleteResultListEntry(boolean allowBetweenRows)
Deletes the current row in the cache.
|
(package private) void |
first()
Move the cursor exactly onto the index of the first entry, whether or not it actually exists
in the results list.
|
(package private) boolean |
forward(int rows)
Advance the current cursor position forward by the specified number of
rows.
|
(package private) boolean |
forward(NumberType rows)
Advance the current cursor position forward by the specified number of
rows.
|
(package private) java.lang.Object[] |
getFirst()
Move the cursor exactly onto the index of the first result in the
cache, and return the primary key array representing that result.
|
(package private) java.lang.Object[] |
getLast()
Move the cursor exactly onto the index of the last result in the
cache, and return the primary key array representing that result.
|
(package private) java.lang.Object[] |
getNext()
Move the cursor exactly onto the index of the next result in the
cache, and return the primary key array representing that result.
|
(package private) OffEnd |
getOffEnd()
Get off-end state of query results.
|
(package private) java.lang.Object[] |
getPrevious()
Move the cursor exactly onto the index of the previous result in the
cache, and return the primary key array representing that result.
|
Persistable[] |
getReferenceRow()
Get the reference row for future iterations.
|
private java.lang.Object[] |
getResult(double resetPosition)
Retrieve the result at the cursor's current position, which should
always be at an index boundary (not between result indices).
|
(package private) java.lang.Object[] |
getRow()
Retrieve the virtual, composite row of results at the cursor's current
position.
|
(package private) boolean |
isFirstRowDeleted()
Determines if the first row (or the last row if the scroll direction is backward) deleted by
deleteResultListEntry(boolean) . |
(package private) boolean |
isForwardScroll()
Determines if the cache is build in the forward direction (starting from the first result),
or backward direction (starting from the last result).
|
(package private) boolean |
isFoundFirst()
Determines if we have visited the first result in the result set.
|
(package private) boolean |
isFullSet()
Determines if the query has fetched all of its results.
|
(package private) boolean |
isOffEnd(OffEnd boundary)
Indicate whether the cursor has crossed the specified boundary (front or
back) of the associated query's list of available results.
|
(package private) void |
last()
Move the cursor exactly onto the index of the last entry, whether or not it actually exists
in the results list.
|
private boolean |
match(java.io.Serializable[] a1,
java.lang.Object[] a2)
Detect whether all elements in one object array match those at the same
positions within another array.
|
(package private) void |
next()
Move the cursor exactly onto the index of the next entry, whether or not it actually exists
in the results list.
|
(package private) java.lang.Object[] |
peekLastLoadedResult()
Get last loaded result row.
|
(package private) void |
previous()
Move the cursor exactly onto the index of the previous entry, whether or not it actually
exists in the results list.
|
private void |
removeFromRepoCache(java.lang.Object[] data)
Delete the cache entry associated with the specified array of primary keys or DMOs .
|
(package private) void |
reposition(int row)
Reposition the cursor to the specified row in the result set.
|
(package private) void |
reposition(NumberType row)
Reposition the cursor to the specified row in the result set.
|
(package private) boolean |
reposition(java.io.Serializable[] ids,
boolean scan)
Reposition the cursor such that a request to retrieve the next result
will retrieve the result which matches the specified array of primary
key IDs.
|
(package private) boolean |
repositionByID(integer id)
Reposition the cursor such that a request to retrieve the next result
will retrieve the result which matches the specified primary key ID.
|
(package private) boolean |
repositionByID(rowid id1,
rowid... joinIDs)
Reposition the cursor such that a request to retrieve the next result
will retrieve the result which matches the specified array of primary
key IDs.
|
protected void |
reset()
Reset cursor to a known default state.
|
(package private) void |
resetReferenceRow(int startIndex)
Reset reference row snapshots starting from the given buffer index.
|
(package private) void |
setResults(java.util.List results)
Set underlying cursor results.
|
(package private) integer |
size()
Get the current size of the cached results list.
|
(package private) void |
storeReferenceRow(RecordChangeEvent event)
Store the last fetched row as the reference row for future iterations.
|
private boolean |
validateReposition(BaseDataType value)
Validate a numeric value provided to a reposition request to ensure
that it does not represent the unknown value.
|
private static final java.util.logging.Logger LOG
private java.util.List<java.lang.Object[]> results
private Persistable[] referenceRow
private final RepositionCache repoCache
private final Scrollable query
private double position
private boolean forwardScroll
private boolean foundFirst
private boolean fullSet
private boolean firstRowDeleted
deleteResultListEntry(boolean)
?Cursor(Scrollable query)
query
- Instance of a scrollable query.protected void reset()
void setResults(java.util.List results)
results
- Results to set: cached list of query results (as arrays of primary keys or DMOs).boolean repositionByID(integer id)
id
- A primary key ID, representing the target record (in the case
of a join, this ID is associated with the left-most record in
the join).true
if a matching record was found and the
cursor was repositioned to it; false
if any ID
was unknown or if a matching record could not be found (and we
are in silent error mode).ErrorConditionException
- if the specified ID represents the unknown value.boolean repositionByID(rowid id1, rowid... joinIDs)
If the specified result does not already exist in the results list, the query is instructed to retrieve results sequentially, starting with the first result, caching each result in its list. This continues until either the desired result is found (and the cursor is then repositioned accordingly), or until no more results are available (in which case the cursor remains at its current position).
id1
- A primary key ID, representing the target record (in the case
of a join, this ID is associated with the left-most record in
the join).joinIDs
- All remaining primary key IDs, if any, arranged from left to
right to coincide with the records being joined by the
underlying query.true
if a matching record was found and the
cursor was repositioned to it; false
if any ID
was unknown or if a matching record could not be found (and we
are in silent error mode).boolean reposition(java.io.Serializable[] ids, boolean scan)
If the specified result already exists in the results list, the cursor
is immediately repositioned to just before that result. Otherwise,
the behavior depends upon the value of the scan
parameter.
If it is true
, the query is instructed to retrieve results
sequentially, starting with the first available, caching each result in
its list. This continues until either the desired result is found (in
which case the cursor is repositioned accordingly), or until no more
results are available (in which case the cursor remains at its current
position).
ids
- Array of primary key IDs, arranged from left to right to
coincide with the records being joined by the underlying
query.scan
- true
to scan all results in the event a match is
not found in the cache; false
to check the cache
only.true
if a matching record was found and the
cursor was repositioned to it; false
if any ID
was unknown or if a matching record could not be found (and we
are in silent error mode).OffEnd getOffEnd()
void reposition(NumberType row)
If the specified row does not already exist in the results list, the query is instructed to retrieve results sequentially, starting with the first result, caching each result in its list. This continues until either the desired row is reached (and the cursor is then repositioned accordingly), or until no more results are available (in which case the cursor remains at its current position).
Note that this method will clear the cache if the cursor previously had been scrolling backward.
row
- 1-based index of the target position.ErrorConditionException
- if row
represents unknown value.void reposition(int row)
If the specified row does not already exist in the results list, the query is instructed to retrieve results sequentially, starting with the first result, caching each result in its list. This continues until either the desired row is reached (and the cursor is then repositioned accordingly), or until no more results are available (in which case the cursor remains at its current position).
Note that this will clear the cache if we previously had been scrolling backward.
row
- 1-based index of the target position.boolean forward(NumberType rows)
If the request carries the cursor beyond the end of the currently cached results list, the query is instructed to retrieve additional results sequentially. These are added to the results list. This continues until the request is satisfied, or until there are no more results available. In the latter case, the cursor is left positioned just beyond the last available result.
rows
- Number of rows to scroll the cursor forward.true
if operation was successful and the cursor was moved the exact amount
of rows as specified by the parameter. If false
is returned then it is
possible that cursor's position was moved but not with rows
rows.ErrorConditionException
- if rows
represents the unknown value.boolean forward(int rows)
If the request carries the cursor beyond the end of the currently cached results list, the query is instructed to retrieve additional results sequentially. These are added to the results list. This continues until the request is satisfied, or until there are no more results available. In the latter case, the cursor is left positioned just beyond the last available result.
rows
- Number of rows to scroll the cursor forward.true
if operation was successful and the cursor was moved the exact amount
of rows as specified by the parameter. If false
is returned then it is
possible that cursor's position was moved but not with rows
rows.boolean backward(NumberType rows)
If the request carries the cursor before the start of the currently cached results list, the query is instructed to retrieve additional, previous results sequentially. These are prepended to the results list. This continues until the request is satisfied, or until there are no more results available. In the latter case, the cursor is left positioned just before the first available result.
rows
- Number of rows to scroll the cursor backward.true
if operation was successful and the cursor was moved the exact amount
of rows as specified by the parameter. If false
is returned then it is
possible that cursor's position was moved but not with rows
rows.ErrorConditionException
- if rows
represents the unknown value.boolean backward(int rows)
If the request carries the cursor before the start of the currently cached results list, the query is instructed to retrieve additional, previous results sequentially. These are prepended to the results list. This continues until the request is satisfied, or until there are no more results available. In the latter case, the cursor is left positioned just before the first available result.
rows
- Number of rows to scroll the cursor backward.true
if operation was successful and the cursor was moved the exact amount
of rows as specified by the parameter. If false
is returned then it is
possible that cursor's position was moved but not with rows
rows.integer size()
integer currentRow()
boolean isOffEnd(OffEnd boundary)
true
, this indicates that the query cannot produce any more
results in that scroll direction. If boundary
is
null
or OffEnd.NONE
, assume the caller just
wants to know if the cursor has gone off-end at all (either direction).boundary
- One of the OffEnd
enum types, or null
to indicate we want to know if the cursor has gone off either
end of the result list (equivalent to specifying the enum type
NONE
).true
if the cursor is off the specified end of its
query's results list, else false
.void addResultFirst(java.lang.Object[] data)
ids
is null
, this indicates the query has run
off the beginning of its available results.data
- Result to add: the primary keys of the records backing the
result to be added or the records themselves (or a mix).void addResultLast(java.lang.Object[] data)
ids
is null
, this indicates the query has run
off the end of its available results.data
- Result to add: the primary keys of the records backing the
result to be added or the records themselves (or a mix).void addResultNext(java.lang.Object[] data)
ids
is null
, this indicates the query has run off the end of
its available results.data
- Result to add: the primary keys of the records backing the
result to be added or the records themselves (or a mix).void addResultPrevious(java.lang.Object[] data)
ids
is null
, this indicates the query has run
off the beginning of its available results.data
- Result to add: the primary keys of the records backing the
result to be added or the records themselves (or a mix).void storeReferenceRow(RecordChangeEvent event)
event
- Event caused by update of a record of specific type.void resetReferenceRow(int startIndex)
startIndex
- Starting buffer index in the set of all buffers participating in the query.public Persistable[] getReferenceRow()
java.lang.Object[] getFirst()
null
if no such result was cached.java.lang.Object[] getLast()
null
if no such result was cached.java.lang.Object[] getNext()
null
if no such result was cached.java.lang.Object[] getPrevious()
null
if no such result was cached.java.lang.Object[] getRow()
java.lang.Object[] peekLastLoadedResult()
boolean contains(java.io.Serializable id, int index)
id
- ID to match.index
- Index position at which a match is attempted within each array
stored in the results cache.true
if the cache contains the given ID, else
false
.void beforeFirst()
boolean isFullSet()
true
if the query has fetched all of its results.boolean isForwardScroll()
true
if the cache is build in the forward direction, false
if it is build in the backward directionboolean isFoundFirst()
true
if we have visited the first result in the result set.boolean deleteResultListEntry(boolean allowBetweenRows)
allowBetweenRows
- If true
then the cursor can be positioned between rows (the next
row will be deleted). false
for conventional DELETE-RESULT-LIST-ENTRY()
mode where the cursor should be positioned on a row (otherwise false
is
returned).true
on success.void next()
void first()
void last()
void previous()
boolean isFirstRowDeleted()
deleteResultListEntry(boolean)
.private java.lang.Object[] getResult(double resetPosition)
null
is returned. The latter
condition indicates that the cursor has been moved beyond a cached
result, such that the caller needs to attempt to query a result and
cache it.resetPosition
- Position to which the cursor must be reset in the event no
result is available in the cached results list at the cursor's
current position.null
if no such data exists.private void addToRepoCache(java.lang.Object[] data)
Note that this method should only be invoked when the current cursor position corresponds with the specified result, otherwise the row will be mismatched for the result.
data
- Array of primary keys or DMOs representing a query result.private void removeFromRepoCache(java.lang.Object[] data)
data
- Array of primary keys or DMOs associated with the entry to be deleted.private boolean match(java.io.Serializable[] a1, java.lang.Object[] a2)
a1
- First array. May have fewer or the same number of elements as
a2
.a2
- Second array. May have the same number or more elements than
a1
.true
if all elements in a1
equal
those elements at corresponding positions in a2
.private boolean validateReposition(BaseDataType value)
value
- ID or row number/offset to be validated.true
if the number is valid; false
if it is invalid, but we are in silent error mode.ErrorConditionException
- if the number is invalid and we are not in silent error mode.