com.goldencode.p2j.persist

Class DynamicQuery

java.lang.Object

com.goldencode.p2j.persist.AbstractQuery

com.goldencode.p2j.persist.DynamicQuery

All Implemented Interfaces:

BufferCollection, IndexInformation, P2JQuery, Scrollable, Openable

Direct Known Subclasses:

CompoundQuery, RandomAccessQuery

abstract class DynamicQuery
extends AbstractQuery
implements Scrollable

Abstract base class for query classes which dynamically navigate and retrieve results, and which must support results list scrolling.

The primary purpose of this class is to manage a query cursor for results list scrolling and repositioning, and to provide an API to client code to perform these tasks, and to interrogate the cursor for state data.

This class implements the RecordChangeListener interface. When the setScrolling() method is invoked, this object is registered as a listener with the context-local ChangeBroker instance, so that it can receive notifications of record deletions. If the deleted record was in this query's cache, the cache is expired. Subclasses must implement the recordBuffers() method.

Nested Class Summary

Nested classes/interfaces inherited from interface com.goldencode.p2j.persist.P2JQuery

P2JQuery.Parameter, P2JQuery.ParamResolver, P2JQuery.QueryEventListener, P2JQuery.QueryOpenedListener

Field Summary

Fields

Modifier and Type	Field and Description
protected Cursor	cursor Cursor which scrolls query results
private int	moveCount Number of times the query's position has moved (non-scrolling only)

Fields inherited from class com.goldencode.p2j.persist.AbstractQuery

closed, dynamicPredicate, errorHelper, excluded, included, indexedReposition, inverseSorting, lenientOffEnd, outer, parameterFilter

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DynamicQuery() Default constructor.

Method Summary

Modifier and Type	Method and Description
boolean	_isOffEnd() Indicate whether the cursor has run off one or the other end of the associated query's list of available results.
boolean	backward(int rows) Move the current cursor position backward by the specified number of rows.
boolean	backward(NumberType rows) Move the current cursor position backward by the specified number of rows.
void	clearResults() Clear the current results from the query, so the same query instance can be executed again, without having to re-open it.
integer	currentRow() Get the 1-based index of the current row in the result set.
integer	currentRowImpl() Get the 1-based index of the current row in the result set.
boolean	forward(int rows) Advance the current cursor position forward by the specified number of rows.
boolean	forward(NumberType rows) Advance the current cursor position forward by the specified number of rows.
protected abstract java.lang.Object	getBreakValue() Return an object which represents a property value which defines the end of a sort band.
protected void	incrementMoves() Increment the counter of how many times the current result row of this query has changed.
boolean	isNativelyPreselect() Indicate whether this query is a preselect query by its nature.
boolean	isPreselect() Indicate whether this query preselects all of its results.
boolean	isScrolling() Indicate whether this query's scrolling flag has been set.
void	open() Open the prepared query and reset the cursor.
void	reposition(int row) Reposition the query to the specified row in the result set.
void	reposition(NumberType row) Reposition the cursor to the specified row in the result set.
boolean	repositionByID(java.lang.Long... serIDs) 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.
void	repositionByID(recid id) Reposition the cursor such that a request to retrieve the next result will retrieve the result which matches the specified primary key ID.
void	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 the query to a clean state.
protected void	resetScrolling() Create a query cursor to enable results list scrolling/repositioning.
void	setScrolling() Create a query cursor to enable results list scrolling/repositioning.
integer	size() Get the current size of the cached results list.
protected void	verifyScrolling() Verify that this query is a scrolling query; that is, that it has an associated cursor.

Methods inherited from class com.goldencode.p2j.persist.AbstractQuery

_getNext, _isSkipDeletedRecord, accumulate, addAccumulator, addAccumulator, addBuffer, addBuffer, addExternalBuffers, addQueryEventListener, addRepositionListener, afterReposition, afterReposition, afterReposition, bufferHandle, bufferHandle, bufferHandle, bufferHandle, bufferHandle, buffersMatch, changeForwardOnly, changeForwardOnly, cleanup, close, createResultListEntry, deleteResultListEntry, deleteResultListEntry, exclude, forwardOnly, getCache, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getDataRelation, getDefaultLock, getErrorHelper, getExternalBuffers, getExternalBuffersDefs, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getLast, getLast, getLast, getLast, getLast, getLast, getLast, getLast, getNext, getNext, getNext, getNext, getNext, getNext, getNext, getNumResults, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getReferencedBuffers, hasAccumulators, hasAny, hasAny, hasAny, hasAny, hasOne, hasOne, hasOne, hasOne, include, indexInformation, indexInformation, indexInformation, isBrowsed, isDynamicPredicate, isErrorIfNull, isFatalError, isFetchOnReposition, isFillingBrowseRows, isIndexedReposition, isIterating, isLastOfBreakGroup, isLenientOffEnd, isNewBreakGroup, isOffEnd, isOmitAlias, isOpen, isPresort, isRepositionNotificationActive, isSkipDeletedRecord, isStandalone, loadRowAtCursor, notifyQueryCloseListeners, notifyQueryOpenListeners, notifyRepositionListeners, numBuffers, numResults, numResults, prepare, prepare, prepareFetch, prepareString, preprocessSubstitutionArguments, queryBackward, queryBackward, queryClose, queryForward, queryForward, queryOpen, queryReposition, queryReposition, queryRepositionByID, releaseBuffers, removeRepositionListener, setBrowsed, setBuffers, setBuffers, setCache, setCache, setDataRelation, setDynamicPredicate, setErrorIfNull, setFatalError, setFetchOnReposition, setFillingBrowseRows, setIndexedReposition, setIterating, setLenientOffEnd, setOmitAlias, setOuter, setParameterFilter, setPresort, setSkipDeletedRecord, setStandalone, silentCurrent, silentCurrent, silentFirst, silentFirst, silentLast, silentLast, silentNext, silentNext, silentPrevious, silentPrevious, silentUnique, silentUnique, translateSort, translateSort, translateWhere

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.goldencode.p2j.persist.Scrollable

peekNext, peekPrevious

Methods inherited from interface com.goldencode.p2j.persist.P2JQuery

_getNext, addAccumulator, addAccumulator, addDynamicFilter, addExternalBuffers, addQueryEventListener, addRepositionListener, changeForwardOnly, changeForwardOnly, cleanup, clearDynamicFilters, close, close, createResultListEntry, current, current, deleteResultListEntry, deleteResultListEntry, exclude, first, first, forwardOnly, getBasicLogging, getCache, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getDataRelation, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getJoin, getLast, getLast, getLast, getLast, getLast, getLast, getLast, getLast, getNext, getNext, getNext, getNext, getNext, getNext, getNext, getNext, getNumResults, getOffEnd, getOffEndListeners, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getRecordBuffers, getTableCount, hasAny, hasAny, hasAny, hasAny, hasOne, hasOne, hasOne, hasOne, hintFullResults, include, indexInformation, indexInformation, indexInformation, isBrowsed, isDynamicPredicate, isFetchOnReposition, isFillingBrowseRows, isFindByRowid, isFirstOfGroup, isFirstOfGroup, isIndexedReposition, isIterating, isLastOfGroup, isLastOfGroup, isOffEnd, isPresort, isSkipDeletedRecord, isStandalone, last, last, next, next, notifyQueryCloseListeners, notifyQueryOpenListeners, notifyRepositionListeners, prepare, prepare, prepareString, previous, previous, queryBackward, queryBackward, queryClose, queryForward, queryForward, queryOpen, queryReposition, queryReposition, queryRepositionByID, queryRepositionByID, releaseBuffers, removeRepositionListener, resetQuery, setBasicLogging, setBasicLogging, setBrowsed, setCache, setCache, setDataRelation, setDynamicPredicate, setErrorIfNull, setFetchOnReposition, setFillingBrowseRows, setIndexedReposition, setIterating, setLenientOffEnd, setParameterFilter, setPresort, setSkipDeletedRecord, setStandalone, unique, unique

Methods inherited from interface com.goldencode.p2j.persist.BufferCollection

addBuffer, addBuffer, addBuffer, addBuffer, bufferHandle, bufferHandle, bufferHandle, bufferHandle, bufferHandle, numBuffers, setBuffers, setBuffers, setBuffers

Methods inherited from interface com.goldencode.p2j.util.Openable

isOpen

Field Detail

moveCount

private int moveCount

Number of times the query's position has moved (non-scrolling only)

cursor

protected Cursor cursor

Cursor which scrolls query results

Constructor Detail

DynamicQuery

protected DynamicQuery()

Default constructor.

Method Detail

clearResults

public void clearResults()

Clear the current results from the query, so the same query instance can be executed again, without having to re-open it.

Specified by:

clearResults in interface P2JQuery

setScrolling

public void setScrolling()

Create a query cursor to enable results list scrolling/repositioning. Only one cursor is created, even if this method is invoked multiple times.

Specified by:

setScrolling in interface P2JQuery

Overrides:

setScrolling in class AbstractQuery

repositionByID

public void repositionByID(recid id)

Reposition the cursor such that a request to retrieve the next result will retrieve the result which matches the specified primary key ID. A request to retrieve the previous result will retrieve the result immediately previous to this, if any, in the results list.

Specified by:

repositionByID in interface P2JQuery

Parameters:

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).

Throws:

ErrorConditionException - if the specified ID represents the unknown value.

repositionByID

public void 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. A request to retrieve the previous result will retrieve the result immediately previous to this, if any, in the results list.

Specified by:

repositionByID in interface P2JQuery

Parameters:

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.

Throws:

ErrorConditionException - if any of the specified IDs represents the unknown value.

repositionByID

public boolean repositionByID(java.lang.Long... serIDs)

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. A request to retrieve the previous result will retrieve the result immediately previous to this, if any, in the results list. Note: This is not public API.

Specified by:

repositionByID in interface P2JQuery

Parameters:

serIDs - A set of primary key IDs, arranged from left to right to coincide with the records being joined by the underlying query.

Returns:

true on success.

Throws:

ErrorConditionException - if any of the specified IDs represents the unknown value.

reposition

public void reposition(NumberType row)

Reposition the cursor to the specified row in the result set. The row indicates the position between two results, such that a call to retrieve the next record will get the result at the specified row, and a call to retrieve the previous result will get the result before the new position.

Specified by:

reposition in interface P2JQuery

Parameters:

row - 1-based index of the target position.

Throws:

ErrorConditionException - if this query is not a scrolling query; if row represents unknown value.

reposition

public void reposition(int row)

Reposition the query to the specified row in the result set. The row indicates the position between two results, such that a call to retrieve the next record will get the record after the new position, and a call to retrieve the previous record will get the record before the new position.

Specified by:

reposition in interface P2JQuery

Parameters:

row - 1-based index of the target position.

Throws:

ErrorConditionException - if this query is not a scrolling query.

forward

public boolean forward(NumberType rows)

Advance the current cursor position forward by the specified number of rows. This will always leave the cursor between two results. For example, given a request to move 1 row forward:

• if the cursor currently is positioned directly on a result, this would move it ahead one and a half positions, to just beyond the following result;
• if the cursor currently is positioned between two results, this would move it ahead one position, to just beyond the following result.

Specified by:

forward in interface P2JQuery

Parameters:

rows - Number of rows to scroll the cursor forward.

Returns:

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.

Throws:

ErrorConditionException - if this query is not a scrolling query; if rows represents the unknown value.

forward

public boolean forward(int rows)

Advance the current cursor position forward by the specified number of rows. This will always leave the cursor between two results. For example, given a request to move 1 row forward:

• if the cursor currently is positioned directly on a result, this would move it ahead one and a half positions, to just beyond the following result;
• if the cursor currently is positioned between two results, this would move it ahead one position, to just beyond the following result.

Specified by:

forward in interface P2JQuery

Parameters:

rows - Number of rows to scroll the cursor forward.

Returns:

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.

Throws:

ErrorConditionException - if this query is not a scrolling query.

backward

public boolean backward(NumberType rows)

Move the current cursor position backward by the specified number of rows. This will always leave the cursor between two results. For example, given a request to move 1 row backward:

• if the cursor currently is positioned directly on a result, this would move it back one half position, to just before the current result;
• if the cursor currently is positioned between two results, this would move it back one position, to just before the current result.

Specified by:

backward in interface P2JQuery

Parameters:

rows - Number of rows to scroll the cursor backward.

Returns:

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.

Throws:

ErrorConditionException - if this query is not a scrolling query; if rows represents the unknown value.

backward

public boolean backward(int rows)

Move the current cursor position backward by the specified number of rows. This will always leave the cursor between two results. For example, given a request to move 1 row backward:

• if the cursor currently is positioned directly on a result, this would move it back one half position, to just before the current result;
• if the cursor currently is positioned between two results, this would move it back one position, to just before the current result.

Specified by:

backward in interface P2JQuery

Parameters:

rows - Number of rows to scroll the cursor backward.

Returns:

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.

Throws:

ErrorConditionException - if this query is not a scrolling query.

size

public integer size()

Get the current size of the cached results list. However, since this cache is built progressively as the query is scrolled, repositioned, and naturally navigated, this does not necessarily represent the full count of results which may satisfy the query.

Specified by:

size in interface P2JQuery

Returns:

Current results list size.

Throws:

ErrorConditionException - if this query is not a scrolling query.

currentRow

public integer currentRow()

Get the 1-based index of the current row in the result set. This is the index of the entry at or before which the cursor currently is positioned.

Specified by:

currentRow in interface P2JQuery

Returns:

Current row or the unknown value if the current row cannot be determined. The current row cannot be determined if the results list is empty, or if the cursor currently is in backward scroll mode.

Throws:

ErrorConditionException - if this query is not a scrolling query.

currentRowImpl

public integer currentRowImpl()

Get the 1-based index of the current row in the result set. This is the index of the entry at or before which the cursor currently is positioned.

Specified by:

currentRowImpl in interface P2JQuery

Returns:

Current row or the unknown value if the current row cannot be determined. The current row cannot be determined if the results list is empty.

Throws:

ErrorConditionException - if this query is not a scrolling query.

_isOffEnd

public boolean _isOffEnd()

Indicate whether the cursor has run off one or the other end of the associated query's list of available results. If true, this indicates that the query cannot produce any more results in the current scroll direction.

Specified by:

_isOffEnd in interface P2JQuery

Returns:

true if the cursor is off either end of its query's results list.

Throws:

ErrorConditionException - if this query is not a scrolling query.

isPreselect

public boolean isPreselect()

Indicate whether this query preselects all of its results.

Specified by:

isPreselect in interface P2JQuery

Returns:

false.

isNativelyPreselect

public boolean isNativelyPreselect()

Indicate whether this query is a preselect query by its nature.

Specified by:

isNativelyPreselect in interface P2JQuery

Returns:

true.

isScrolling

public boolean isScrolling()

Indicate whether this query's scrolling flag has been set.

Specified by:

isScrolling in interface P2JQuery

Returns:

true if this is a scrolling query; else false.

open

public void open()

Open the prepared query and reset the cursor.

Specified by:

open in interface P2JQuery

Overrides:

open in class AbstractQuery

resetScrolling

protected void resetScrolling()

Create a query cursor to enable results list scrolling/repositioning.

verifyScrolling

protected void verifyScrolling()

Verify that this query is a scrolling query; that is, that it has an associated cursor.

Throws:

java.lang.UnsupportedOperationException - if a cursor has not been associated with this query.

incrementMoves

protected void incrementMoves()

Increment the counter of how many times the current result row of this query has changed.

getBreakValue

protected abstract java.lang.Object getBreakValue()

Return an object which represents a property value which defines the end of a sort band. A sort band is a series of one or more records which share the same value for a particular property, where that property is used as the coarsest sorting criterion defined by this query's order by clause.

If the break value for this query currently is non-null, this indicates that the most recently retrieved record has crossed a sort band boundary, and that a new band has begun. This value will only be non-null at the point at which such a record is found, and will be null for all other records.

Note: break values are only tracked for invocations of next and previous. Other retrievals will results in break value being null.

Returns:

Break value if dynamic query crossed a sort band boundary, else null.

reset

protected void reset()

Reset the query to a clean state.