public class RandomAccessQuery extends DynamicQuery implements Joinable, QueryConstants, RecordChangeListener
This class slavishly implements the Progress semantic of fully dynamic query iteration. That is, each record is searched for and retrieved individually, so that any change to an existing record can be reflected immediately in the remaining navigation performed on the query. This means that an update to the current record may cause it to reappear later in the query results, if the changes made to the record would cause it to be sorted differently than when it was first retrieved (note that this can cause infinite looping, just as in the pre-conversion, Progress code).
To implement the single-record retrieval semantic, this high level query
may issue multiple, database-level, select statements to the database for
each record retrieval attempt. For details of how this is performed, see
HQLHelper
and HQLBundle
. The result of a record retrieval
is a Data Model Object (DMO), which is stored in a RecordBuffer
.
A record buffer is associated with this object at construction.
Because of this implementation requirement, RandomAccessQuery
represents an extremely inefficient mechanism by which to query a
database for a set of records. As such, it should not be used for new
development; it is intended only to support legacy, converted code,
insofar as that code may rely on the dynamic nature of the Progress
semantic.
This class implements the Joinable
interface so that it can
be added as a component to a CompoundQuery
. When used in such a
capacity, the query should be configured to raise an end condition instead
of an error condition, in the case that a request to get the first, last,
or a unique record fails. This will allow the compound query to continue
processing normally in this case. This is accomplished by invoking AbstractQuery.setErrorIfNull(boolean)
with the parameter true
.
When used to represent a Progress query (as created with DEFINE or OPEN
QUERY), setLenientOffEnd(boolean)
must be set to true
, which
suppresses end condition exceptions for next
and
previous
commands which run off the end of the query's
results.
Transaction Isolation (Dirty Reads)
This class supports Progress' peculiar form of transaction isolation, where
uncommitted updates, inserts, and deletes that affect database indexes are
visible across sessions. This is emulated using a shared database (the
"dirty" database) which temporarily stores information about uncommitted
changes made by other contexts. When those other sessions commit or roll
back their changes, this transient information is cleared from the dirty
database and is no longer visible.
The implementation of this feature requires that the results found in the primary database backing a query be treated as provisional. Results found in the dirty database may override, if it is determined that the "dirty" result is the more correct result, given the query criteria.
P2JQuery.Parameter
Modifier and Type | Field and Description |
---|---|
private HQLBundle |
activeBundle
HQL data necessary for the current query operation
|
private int |
activeBundleKey
Key which indicates active bundle choice
|
private java.lang.Object[] |
args
Base substitution parameters for HQL queries
|
private java.lang.Object |
breakValue
Break value indicating a new sort band if non-
null |
private RecordBuffer |
buffer
Record buffer which backs this query
|
private java.lang.Object[] |
currentArgs
Substitution parameter values for the next query execution
|
private boolean |
dirtyCopy
Was last record found retrieved from the dirty database?
|
private DMOSorter |
dmoSorter
DMO sorter associated with query's sort clause
|
private boolean |
fullRecords
Force query to retrieve full records, rather than primary keys only
|
private HQLHelper |
helper
Builds HQL statements for various Hibernate queryies
|
private java.lang.String |
index
Name of index in use for this query
|
private java.lang.String |
indexInfo
Index information string as it is returned by INDEX-INFORMATION.
|
private AbstractJoin |
join
Helper object for dynamic join via a foreign key relation
|
private boolean |
lenientOffEnd
false if running off end of results should raise error |
private LockType |
lockType
Lock type to apply to records retrieved
|
private static java.util.logging.Logger |
LOG
Logger
|
private RecordChangeListener |
placeholderCleaner
RecordChangeListener which nulls out placeholder reference record
|
private Persistable |
referenceRecord
Record whose data defines current "place" in query results
|
private java.lang.String |
sort
Original sort clause (only stored until helper is built)
|
private boolean |
unregisterOnCleanup
Determines if this will be unregistered from ChangeBroker on cleanup.
|
private java.lang.String |
where
Original where clause (only stored until helper is built)
|
private java.util.function.Supplier<logical> |
whereExpr
Client-side where clause expression, if any
|
cursor
closed, inverseSorting, parameterFilter
CURRENT, FIRST, LAST, NEXT, NONE, PREVIOUS, RETRIEVE_MODES, UNIQUE
Constructor and Description |
---|
RandomAccessQuery()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
protected void |
activateFirst()
Set as active the HQL bundle corresponding with a search for the first
record matching this query's criteria.
|
private void |
activateLast()
Set as active the HQL bundle corresponding with a search for the last
record matching this query's criteria.
|
private void |
activateNext()
Set as active the HQL bundle corresponding with a search for the next
record matching this query's criteria, relative to the most recently
fetched record.
|
private void |
activatePrevious()
Set as active the HQL bundle corresponding with a search for the
previous record matching this query's criteria, relative to the most
recently fetched record.
|
protected void |
activateUnique()
Set as active the HQL bundle corresponding with a search for the single
record, if any, which matches this query's criteria.
|
void |
cleanup()
The cleanup method is overridden to allow the listener(s) to be removed from the
ChangeBroker if they were added in the global scope, otherwise, the
ChangeBroker will drop them automatically when the respective scope is finished. |
void |
close()
Explicitly close the prepared query.
|
void |
close(boolean inResource)
Explicitly close the prepared query.
|
void |
current()
Reload the record most recently loaded into the backing record buffer,
if any.
|
void |
current(LockType lockType)
Reload the record most recently loaded into the backing record buffer,
if any.
|
private void |
errorFindFirstLast()
Record or throw a FIND FIRST/LAST failed error condition for the
current DMO type.
|
protected Persistable |
execute(java.lang.Object[] values,
LockType lockType,
boolean unique,
boolean updateLock)
Execute each query stored in the active HQL bundle in turn until we
find a result or have no more statements to execute.
|
private Persistable |
executeImpl(java.lang.Object[] values,
LockType lockType,
boolean unique,
boolean updateLock)
Execute each query stored in the active HQL bundle in turn until we
find a result or have no more statements to execute.
|
private Persistable |
findNext(java.lang.Object[] values,
LockType lockType,
boolean updateLock)
Find the next record matching the search criteria, or the first such
record if no previous search has been executed against this query.
|
private Persistable |
findPrevious(java.lang.Object[] values,
LockType lockType,
boolean updateLock)
Find the previous record matching the search criteria, or the last such
record if no previous search has been executed against this query.
|
void |
first()
Navigate to the first record which meets the query criteria and retrieve
it into its record buffer.
|
void |
first(LockType lockType)
Navigate to the first record which meets the query criteria and retrieve
it into its record buffer.
|
void |
first(java.lang.Object[] values)
Navigate to the first record which meets the query criteria and retrieve
it into its record buffer.
|
void |
first(java.lang.Object[] values,
LockType lockType)
Navigate to the first record which meets the query criteria and retrieve
it into its record buffer.
|
void |
forceDynamicOperation()
Force this query to operate in dynamic retrieval mode, if it supports this mode.
|
java.lang.Object[] |
getArgs()
Get the query substitution arguments associated with this query, if any.
|
protected java.lang.Object |
getBreakValue()
Return an object which represents a property value which defines the
end of a sort band.
|
protected RecordBuffer |
getBuffer()
Get the record buffer associated with this query.
|
protected java.lang.Object[] |
getCurrentArgs()
Retrieve this query's arguments, as currently resolved.
|
protected HQLHelper |
getHelper()
Obtain the
HQLHelper object which supports this query, creating it first if
necessary. |
private java.lang.Object[] |
getIDs(Persistable dmo)
Create an array of size one, containing the primary key ID of the given
DMO.
|
AbstractJoin |
getJoin()
Get the legacy natural join, if any, associated with this query.
|
protected LockType |
getLockType()
Retrieve this query's lock type.
|
OffEnd |
getOffEnd()
Get the off-end status of this query, which indicates whether the query
has run off either end of its results.
|
java.util.List<QueryOffEndListener> |
getOffEndListeners()
Get all the off-end listeners associated with this query.
|
java.lang.String |
getOriginalWhere()
Get the original, HQL where clause associated with this query.
|
RecordBuffer[] |
getRecordBuffers()
Get an array of all record buffers managed by this query.
|
java.lang.Object[] |
getRow()
Assemble an array of size one and store in it the primary key ID for
the current record in the buffer underlying this query.
|
java.lang.String |
getSortPhrase()
Get the sort phrase associated with this query.
|
int |
getTableCount()
Get the number of tables joined by this query.
|
protected void |
handleExecuteException(LockUnavailableException exc)
This method is invoked when a locking exception is caught during query
execution.
|
protected void |
handleExecuteException(PersistenceException exc)
This method is invoked when a persistence exception is caught during
query execution.
|
protected void |
handleExecuteException(ValidationException exc)
This method is invoked when a validation exception is caught during
query execution.
|
boolean |
hasWhereExpression()
Indicate whether this query has a client-side where clause expression associated with it.
|
character |
indexInformation(NumberType n)
Conversion of INDEX-INFORMATION attribute (KW_IDX_INFO).
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort)
Initialization logic which defaults record lock type to
LockType.SHARE . |
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
DataModelObject inverse)
Initialization logic which is used when joining to another table using a foreign
key.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
DataModelObject inverse,
LockType lockType)
Initialization logic which is used when joining to another table using a foreign
key.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
DataModelObject inverse,
java.lang.Object[] args)
Initialization logic which is used when joining to another table using a foreign
key.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
DataModelObject inverse,
java.lang.Object[] args,
LockType lockType)
Initialization logic which is used when joining to another table using a foreign
key.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
LockType lockType)
Initialization logic which sets an explicit, default, record lock type.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.Object[] args)
Initialization logic which defaults record lock type to
LockType.SHARE and accepts default substitution parameters. |
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.Object[] args,
LockType lockType)
Initialization logic which sets an explicit, default, record lock type and
accepts default substitution parameters.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.String indexInfo)
Initialization logic which defaults record lock type to
LockType.SHARE . |
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.String indexInfo,
DataModelObject inverse)
Initialization logic which is used when joining to another table using a foreign
key.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.String indexInfo,
DataModelObject inverse,
LockType lockType)
Initialization logic which is used when joining to another table using a foreign
key.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.String indexInfo,
DataModelObject inverse,
java.lang.Object[] args)
Initialization logic which is used when joining to another table using a foreign
key.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.String indexInfo,
DataModelObject inverse,
java.lang.Object[] args,
LockType lockType)
Initialization logic which is used when joining to another table using a foreign
key.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.String indexInfo,
LockType lockType)
Initialization logic which sets an explicit, default, record lock type.
|
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.String indexInfo,
java.lang.Object[] args)
Initialization logic which defaults record lock type to
LockType.SHARE and accepts default substitution parameters. |
RandomAccessQuery |
initialize(DataModelObject dmo,
java.lang.String where,
java.util.function.Supplier<logical> whereExpr,
java.lang.String sort,
java.lang.String indexInfo,
java.lang.Object[] args,
LockType lockType)
Initialization logic which sets an explicit, default, record lock type and
accepts default substitution parameters.
|
protected void |
initializeBuffer()
Initialize the associated buffer by resetting its state.
|
protected boolean |
isIdOnly()
Indicate whether this query should be a projection query, retrieving only the primary key
of the target record, or whether it should retrieve the entire record as early as possible.
|
void |
last()
Navigate to the last record which meets the query criteria and retrieve
it into its record buffer.
|
void |
last(LockType lockType)
Navigate to the last record which meets the query criteria and retrieve
it into its record buffer.
|
void |
last(java.lang.Object[] values)
Navigate to the last record which meets the query criteria and retrieve
it into its record buffer.
|
void |
last(java.lang.Object[] values,
LockType lockType)
Navigate to the last record which meets the query criteria and retrieve
it into its record buffer.
|
void |
load(java.lang.Object[] data,
LockType lockType,
boolean silentIfNullId)
Load a record into its associated buffer, given an array of size one,
containing a primary key ID value of the record to be loaded, or the DMO
itself.
|
private Persistable |
loadByValue(java.lang.Object[] data,
LockType lockType)
Retrieve a record, given an array of size one, containing a primary key
ID value of the record to be retrieved, or the record itself.
|
private Persistable |
loadByValue(java.lang.Object[] data,
LockType lockType,
boolean silentIfNullId)
Retrieve a record, given an array of size one, containing a primary key
ID value of the record to be retrieved, or the record itself.
|
private void |
logQueryDetails(java.lang.String hql,
java.lang.Object[] parms,
Persistable dmo)
Log debug details about the inputs and results of a query.
|
AdaptiveComponent |
makeAdaptiveServerJoinComponent(java.util.List<AdaptiveComponent> joinList,
AdaptiveQuery query,
int iteration,
boolean outer,
CompoundComponent fallback)
Create an adaptive query component based on the information in this query (which is
presumed to be a single-table query), and given a list of adaptive query components which
represent outer, nested query loops, which will perform a server-side join to the
innermost, nested query component.
|
QueryComponent |
makePreselectServerJoinComponent(java.util.List<QueryComponent> joinList,
int iteration,
boolean outer)
Create a preselect query component based on the information in this query (which is
presumed to be a single-table query), and given a list of preselect query components which
represent outer, nested query loops, which will perform a server-side join to the
innermost, nested query component.
|
void |
next()
Navigate to the next record which meets the query criteria and retrieve
it into its record buffer.
|
void |
next(LockType lockType)
Navigate to the next record which meets the query criteria and retrieve
it into its record buffer.
|
void |
next(java.lang.Object[] values)
Navigate to the next record which meets the query criteria and retrieve
it into its record buffer.
|
void |
next(java.lang.Object[] values,
LockType lockType)
Navigate to the next record which meets the query criteria and retrieve
it into its record buffer.
|
java.lang.Object[] |
peekFirst()
Fetch the array of primary key IDs associated with the first result in
this query's result list.
|
java.lang.Object[] |
peekLast()
Fetch the array of primary key IDs associated with the last result in
this query's result list.
|
java.lang.Object[] |
peekNext()
Fetch the array of primary key IDs associated with the next result in
this query's result list.
|
java.lang.Object[] |
peekPrevious()
Fetch the array of primary key IDs associated with the previous result
in this query's result list.
|
protected void |
prepareBuffer()
Prepare buffer associated with this query for the query's execution.
|
void |
previous()
Navigate to the previous record which meets the query criteria and
retrieve it into its record buffer.
|
void |
previous(LockType lockType)
Navigate to the previous record which meets the query criteria and
retrieve it into its record buffer.
|
void |
previous(java.lang.Object[] values)
Navigate to the previous record which meets the query criteria and
retrieve it into its record buffer.
|
void |
previous(java.lang.Object[] values,
LockType lockType)
Navigate to the previous record which meets the query criteria and
retrieve it into its record buffer.
|
private Persistable |
processDirtyResults(Persistence persistence,
Persistable primaryDMO,
DirtyInfo info,
LockType lockType,
boolean updateLock)
Process the results of a dirty index check and return the most
appropriate result for the query.
|
java.util.Iterator<RecordBuffer> |
recordBuffers()
Report the record buffer for whose changes this object is interested
in listening.
|
protected void |
registerChangeListener()
Register the RecordChangeListener instance with the ChangeBroker.
|
void |
registerRecordChangeListeners(int scope)
Register all
RecordChangeListener s associated with this
query (if any), with the context-local ChangeBroker at the
indicated scope. |
protected void |
releaseBuffers()
Release the current record, if any, from the buffer which is used by
this query.
|
void |
reset(boolean resolveArgs)
Reset the query by clearing its state to a known default.
|
private void |
resolveArgs()
Resolve query substitution arguments in preparation for query execution.
|
void |
setFullRecords()
Force the query to retrieve full records, rather than primary keys only.
|
void |
setLenientOffEnd(boolean lenientOffEnd)
Set the behavior of this query as a record retrieval request moves off
the end of its results.
|
(package private) void |
setReferenceRecord(Persistable referenceRecord)
Set the record whose data defines current "place" in query results.
|
void |
setResults(Results results)
Set the given results object into this query.
|
void |
setUnknownRecord()
Set the buffer backing the query to unknown mode.
|
void |
stateChanged(RecordChangeEvent event)
Respond to a record change event.
|
void |
unique()
Navigate to a particular record which meets the query criteria and
retrieve it into its record buffer.
|
void |
unique(LockType lockType)
Navigate to a particular record which meets the query criteria and
retrieve it into its record buffer.
|
void |
unique(java.lang.Object[] values)
Navigate to a particular record which meets the query criteria and
retrieve it into its record buffer.
|
void |
unique(java.lang.Object[] values,
LockType lockType)
Navigate to a particular record which meets the query criteria and
retrieve it into its record buffer.
|
protected void |
updateBuffer(Persistable dmo,
LockType lockType,
boolean errorIfNull,
OffEnd offEnd)
Update the record buffer with the given DMO, applying the specified
lock type and error-if-null setting.
|
_isOffEnd, backward, backward, currentRow, currentRowImpl, forward, forward, incrementMoves, isNativelyPreselect, isPreselect, isScrolling, open, reposition, reposition, repositionByID, repositionByID, resetScrolling, setScrolling, size, verifyScrolling
accumulate, addAccumulator, addAccumulator, addBuffer, addBuffer, addRepositionListener, afterReposition, bufferHandle, bufferHandle, bufferHandle, bufferHandle, bufferHandle, changeForwardOnly, changeForwardOnly, deleteResultListEntry, deleteResultListEntry, exclude, forwardOnly, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getLast, getLast, getLast, getLast, getLast, getLast, getLast, getLast, getNext, 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, isBrowsed, isErrorIfNull, isFetchOnReposition, isLastOfBreakGroup, isNewBreakGroup, isOffEnd, isOpen, isRepositionNotificationActive, isSkipDeletedRecord, isStandalone, loadRowAtCursor, notifyRepositionListeners, numBuffers, numResults, numResults, optimize, prepare, prepare, prepareFetch, prepareString, preprocessSubstitutionArguments, queryBackward, queryBackward, queryClose, queryForward, queryForward, queryOpen, queryReposition, queryReposition, queryRepositionByID, removeRepositionListener, setBrowsed, setBuffers, setBuffers, setErrorIfNull, setExternalBuffers, setFetchOnReposition, setParameterFilter, setSkipDeletedRecord, setStandalone, validateSubstitutionArguments
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getReferencedBuffers, setErrorIfNull
_isOffEnd, addAccumulator, addAccumulator, addBuffer, addBuffer, addRepositionListener, backward, backward, bufferHandle, bufferHandle, bufferHandle, bufferHandle, bufferHandle, changeForwardOnly, changeForwardOnly, currentRow, currentRowImpl, deleteResultListEntry, deleteResultListEntry, exclude, forward, forward, forwardOnly, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getCurrent, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getFirst, getLast, getLast, getLast, getLast, getLast, getLast, getLast, getLast, getNext, getNext, getNext, getNext, getNext, getNext, getNext, getNext, getNumResults, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, hasAny, hasAny, hasAny, hasAny, hasOne, hasOne, hasOne, hasOne, include, indexInformation, indexInformation, isBrowsed, isFetchOnReposition, isNativelyPreselect, isOffEnd, isOpen, isPreselect, isScrolling, isSkipDeletedRecord, isStandalone, notifyRepositionListeners, numBuffers, open, optimize, prepare, prepare, prepareString, queryBackward, queryBackward, queryClose, queryForward, queryForward, queryOpen, queryReposition, queryReposition, queryRepositionByID, removeRepositionListener, reposition, reposition, repositionByID, repositionByID, setBrowsed, setBuffers, setBuffers, setExternalBuffers, setFetchOnReposition, setParameterFilter, setScrolling, setSkipDeletedRecord, setStandalone, size
private static final java.util.logging.Logger LOG
private RecordBuffer buffer
private AbstractJoin join
private java.util.function.Supplier<logical> whereExpr
private java.lang.Object[] args
private LockType lockType
private java.lang.String where
private java.lang.String sort
private DMOSorter dmoSorter
private java.lang.String index
private java.lang.String indexInfo
private HQLHelper helper
private HQLBundle activeBundle
private int activeBundleKey
private boolean lenientOffEnd
false
if running off end of results should raise errorprivate java.lang.Object[] currentArgs
private Persistable referenceRecord
private java.lang.Object breakValue
null
private boolean fullRecords
private boolean dirtyCopy
private RecordChangeListener placeholderCleaner
private boolean unregisterOnCleanup
public RandomAccessQuery()
initialize()
is
called.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort)
LockType.SHARE
.
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.String indexInfo)
LockType.SHARE
.
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.indexInfo
- Index information string as it is returned by INDEX-INFORMATION.
May be null
if it is not an OPEN QUERY case or if
you don't need debug information about selected indexes.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, DataModelObject inverse)
LockType.SHARE
.
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.inverse
- DMO to which this query should join via a foreign relation.
May be null
.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.String indexInfo, DataModelObject inverse)
LockType.SHARE
.
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.indexInfo
- Index information string as it is returned by INDEX-INFORMATION.
May be null
if it is not an OPEN QUERY case or if
you don't need debug information about selected indexes.inverse
- DMO to which this query should join via a foreign relation.
May be null
.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.Object[] args)
LockType.SHARE
and accepts default substitution parameters.
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.args
- Substitution parameters for HQL queries. These will be used
if not overridden by a record retrieval method.java.lang.IllegalArgumentException
- if any substitution argument provided is not of a supported
type.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.String indexInfo, java.lang.Object[] args)
LockType.SHARE
and accepts default substitution parameters.
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.indexInfo
- Index information string as it is returned by INDEX-INFORMATION.
May be null
if it is not an OPEN QUERY case or if
you don't need debug information about selected indexes.args
- Substitution parameters for HQL queries. These will be used
if not overridden by a record retrieval method.java.lang.IllegalArgumentException
- if any substitution argument provided is not of a supported
type.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, DataModelObject inverse, java.lang.Object[] args)
LockType.SHARE
and
accepts default substitution parameters.
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.inverse
- DMO to which this query should join via a foreign relation.
May be null
.args
- Substitution parameters for HQL queries. These will be used
if not overridden by a record retrieval method.java.lang.IllegalArgumentException
- if any substitution argument provided is not of a supported
type.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.String indexInfo, DataModelObject inverse, java.lang.Object[] args)
LockType.SHARE
and
accepts default substitution parameters.
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.indexInfo
- Index information string as it is returned by INDEX-INFORMATION.
May be null
if it is not an OPEN QUERY case or if
you don't need debug information about selected indexes.inverse
- DMO to which this query should join via a foreign relation.
May be null
.args
- Substitution parameters for HQL queries. These will be used
if not overridden by a record retrieval method.java.lang.IllegalArgumentException
- if any substitution argument provided is not of a supported
type.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, LockType lockType)
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.lockType
- Lock type to apply to records retrieved, if not overridden by
a record retrieval method.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.String indexInfo, LockType lockType)
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.indexInfo
- Index information string as it is returned by INDEX-INFORMATION.
May be null
if it is not an OPEN QUERY case or if
you don't need debug information about selected indexes.lockType
- Lock type to apply to records retrieved, if not overridden by
a record retrieval method.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, DataModelObject inverse, LockType lockType)
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.inverse
- DMO to which this query should join via a foreign relation.
May be null
.lockType
- Lock type to apply to records retrieved, if not overridden by
a record retrieval method.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.String indexInfo, DataModelObject inverse, LockType lockType)
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.indexInfo
- Index information string as it is returned by INDEX-INFORMATION.
May be null
if it is not an OPEN QUERY case or if
you don't need debug information about selected indexes.inverse
- DMO to which this query should join via a foreign relation.
May be null
.lockType
- Lock type to apply to records retrieved, if not overridden by
a record retrieval method.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.Object[] args, LockType lockType)
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.args
- Substitution parameters for HQL queries. These will be used
if not overridden by a record retrieval method.lockType
- Lock type to apply to records retrieved, if not overridden by
a record retrieval method.java.lang.IllegalArgumentException
- if any substitution argument provided is not of a supported
type.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.String indexInfo, java.lang.Object[] args, LockType lockType)
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.indexInfo
- Index information string as it is returned by INDEX-INFORMATION.
May be null
if it is not an OPEN QUERY case or if
you don't need debug information about selected indexes.args
- Substitution parameters for HQL queries. These will be used
if not overridden by a record retrieval method.lockType
- Lock type to apply to records retrieved, if not overridden by
a record retrieval method.java.lang.IllegalArgumentException
- if any substitution argument provided is not of a supported
type.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, DataModelObject inverse, java.lang.Object[] args, LockType lockType)
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.inverse
- DMO to which this query should join via a foreign relation.
May be null
.args
- Substitution parameters for HQL queries. These will be used
if not overridden by a record retrieval method.lockType
- Lock type to apply to records retrieved, if not overridden by
a record retrieval method.java.lang.IllegalArgumentException
- if any substitution argument provided is not of a supported
type.public RandomAccessQuery initialize(DataModelObject dmo, java.lang.String where, java.util.function.Supplier<logical> whereExpr, java.lang.String sort, java.lang.String indexInfo, DataModelObject inverse, java.lang.Object[] args, LockType lockType)
This code is intentionally separated from the constructor. The purpose of this separation is to allow construction to occur in the prior scope while initialization can still occur within a method or lambda that is inside the next block's scope.
dmo
- Data model object which determines the record buffer into which
records are retrieved.where
- Where clause, using HQL syntax. May be null
.whereExpr
- Client-side where clause expression. May be null
.sort
- Order by clause, using HQL syntax. May be null
only if query is to be navigated only using one of the
unique
method variants.indexInfo
- Index information string as it is returned by INDEX-INFORMATION.
May be null
if it is not an OPEN QUERY case or if
you don't need debug information about selected indexes.inverse
- DMO to which this query should join via a foreign relation.
May be null
.args
- Substitution parameters for HQL queries. These will be used
if not overridden by a record retrieval method.lockType
- Lock type to apply to records retrieved, if not overridden by
a record retrieval method.java.lang.IllegalArgumentException
- if any substitution argument provided is not of a supported
type.public void setFullRecords()
setFullRecords
in interface Joinable
public void setLenientOffEnd(boolean lenientOffEnd)
next
and previous
which do not find a record
do not raise a QueryOffEndException
. By default, this
would normally raise the exception.lenientOffEnd
- true
to suppress QueryOffEndException
for next
and previous
requests;
false
to permit these exceptions.public void first()
first
in interface P2JQuery
ErrorConditionException
- if an error occurred during record retrieval or if no record
could be found when operating in standalone mode.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void first(java.lang.Object[] values)
values
- Substitution values to use when issuing HQL queries.ErrorConditionException
- if an error occurred during record retrieval or if no record
could be found when operating in standalone mode.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void first(LockType lockType)
first
in interface P2JQuery
lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval or if no record
could be found when operating in standalone mode.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void first(java.lang.Object[] values, LockType lockType)
values
- Substitution values to use when issuing HQL queries.lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval or if no record
could be found when operating in standalone mode.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void last()
last
in interface P2JQuery
ErrorConditionException
- if an error occurred during record retrieval or if no record
could be found when operating in standalone mode.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void last(java.lang.Object[] values)
values
- Substitution values to use when issuing HQL queries.ErrorConditionException
- if an error occurred during record retrieval or if no record
could be found when operating in standalone mode.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void last(LockType lockType)
last
in interface P2JQuery
lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval or if no record
could be found when operating in standalone mode.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void last(java.lang.Object[] values, LockType lockType)
values
- Substitution values to use when issuing HQL queries.lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval or if no record
could be found when operating in standalone mode.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void next()
Use the record most recently loaded into the backing buffer as the reference point when determining the next record to visit. If no record has yet been loaded into the buffer, retrieve the first record which meets the query criteria.
next
in interface P2JQuery
ErrorConditionException
- if an error occurred during record retrieval.QueryOffEndException
- if no record could be found.public void next(java.lang.Object[] values)
Use the record most recently loaded into the backing buffer as the reference point when determining the next record to visit. If no record has yet been loaded into the buffer, retrieve the first record which meets the query criteria.
values
- Substitution values to use when issuing HQL queries.ErrorConditionException
- if an error occurred during record retrieval.QueryOffEndException
- if no record could be found.public void next(LockType lockType)
Use the record most recently loaded into the backing buffer as the reference point when determining the next record to visit. If no record has yet been loaded into the buffer, retrieve the first record which meets the query criteria.
next
in interface P2JQuery
lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval.QueryOffEndException
- if no record could be found.public void next(java.lang.Object[] values, LockType lockType)
Use the record most recently loaded into the backing buffer as the reference point when determining the next record to visit. If no record has yet been loaded into the buffer, retrieve the first record which meets the query criteria.
values
- Substitution values to use when issuing HQL queries.lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval.QueryOffEndException
- if no record could be found and lenientOffEnd
is
false
.public void previous()
Use the record most recently loaded into the backing buffer as the reference point when determining the previous record to visit. If no record has yet been loaded into the buffer, retrieve the last record which meets the query criteria.
previous
in interface P2JQuery
ErrorConditionException
- if an error occurred during record retrieval.QueryOffEndException
- if no record could be found.public void previous(java.lang.Object[] values)
Use the record most recently loaded into the backing buffer as the reference point when determining the previous record to visit. If no record has yet been loaded into the buffer, retrieve the last record which meets the query criteria.
values
- Substitution values to use when issuing HQL queries.ErrorConditionException
- if an error occurred during record retrieval.QueryOffEndException
- if no record could be found.public void previous(LockType lockType)
Use the record most recently loaded into the backing buffer as the reference point when determining the previous record to visit. If no record has yet been loaded into the buffer, retrieve the last record which meets the query criteria.
previous
in interface P2JQuery
lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval.QueryOffEndException
- if no record could be found.public void previous(java.lang.Object[] values, LockType lockType)
Use the record most recently loaded into the backing buffer as the reference point when determining the previous record to visit. If no record has yet been loaded into the buffer, retrieve the last record which meets the query criteria.
values
- Substitution values to use when issuing HQL queries.lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval.QueryOffEndException
- if no record could be found and lenientOffEnd
is
false
.public void current()
current
in interface P2JQuery
ErrorConditionException
- if an error occurred during record reload.public void current(LockType lockType)
current
in interface P2JQuery
lockType
- New lock type to apply to the record.ErrorConditionException
- if an error occurred during record reload, or the lock could
not be transitioned to the requested type.public void unique()
unique
in interface P2JQuery
ErrorConditionException
- if an error occurred during record retrieval or if more than
one record is found which match the criteria.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void unique(java.lang.Object[] values)
values
- Substitution values to use when issuing HQL queries.ErrorConditionException
- if an error occurred during record retrieval or if more than
one record is found which match the criteria.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void unique(LockType lockType)
unique
in interface P2JQuery
lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval or if more than
one record is found which match the criteria.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void unique(java.lang.Object[] values, LockType lockType)
values
- Substitution values to use when issuing HQL queries.lockType
- Lock type to acquire for the retrieved record.ErrorConditionException
- if an error occurred during record retrieval or if more than
one record is found which match the criteria.QueryOffEndException
- if no record could be found when operating in compound query
mode.public void setUnknownRecord()
setUnknownRecord
in interface Joinable
RecordBuffer.setUnknownMode()
public void reset(boolean resolveArgs)
public int getTableCount()
getTableCount
in interface P2JQuery
public java.util.List<QueryOffEndListener> getOffEndListeners()
getOffEndListeners
in interface P2JQuery
public void load(java.lang.Object[] data, LockType lockType, boolean silentIfNullId) throws PersistenceException
In the event an expected value cannot be loaded (e.g., the record has
been deleted or is otherwise no longer available), this method throws
MissingRecordException
, after setting the associated buffer
into unknown mode
. Note that a
record being locked by another session does not constitute a "missing"
record.
load
in interface Joinable
data
- Array containing a single primary key ID or DMO.lockType
- Lock type which should by used. Set to null
to
allow query to use its current lock type.silentIfNullId
- If true
, do not raise MissingRecordException
if some of the provided IDs are null
. null
IDs are valid for queries with OUTER join.MissingRecordException
- if any record cannot be loaded, because it is no longer available
(e.g., deleted, etc.).PersistenceException
- if there is an error loading data.getRow()
public void setResults(Results results)
setResults
in interface Joinable
results
- New result set for this query.public java.lang.Object[] getRow()
getRow
in interface Joinable
load(java.lang.Object[], com.goldencode.p2j.persist.lock.LockType, boolean)
public java.lang.Object[] peekFirst()
This implementation always returns an array with a single element,
(or null
), since this query type uses a single record
buffer.
public java.lang.Object[] peekLast()
This implementation always returns an array with a single element,
(or null
), since this query type uses a single record
buffer.
public java.lang.Object[] peekNext()
This implementation always returns an array with a single element,
(or null
), since this query type uses a single record
buffer.
peekNext
in interface Scrollable
null
if there is no such result.public java.lang.Object[] peekPrevious()
This implementation always returns an array with a single element,
(or null
), since this query type uses a single record
buffer.
peekPrevious
in interface Scrollable
null
if there is no such result.public RecordBuffer[] getRecordBuffers()
getRecordBuffers
in interface Joinable
public java.lang.Object[] getArgs()
public AbstractJoin getJoin()
public java.lang.String getOriginalWhere()
getOriginalWhere
in interface Joinable
null
if there is none.public void forceDynamicOperation()
This implementation does nothing, since this query type always is in dynamic retrieval mode.
forceDynamicOperation
in interface Joinable
public java.lang.String getSortPhrase()
getSortPhrase
in interface Joinable
public AdaptiveComponent makeAdaptiveServerJoinComponent(java.util.List<AdaptiveComponent> joinList, AdaptiveQuery query, int iteration, boolean outer, CompoundComponent fallback)
makeAdaptiveServerJoinComponent
in interface Joinable
joinList
- List of adaptive components representing nested query loops which will contain
the adaptive query component returned by this method. The last component in the
list represents the nested query loop immediately containing the returned query
component, with which the join will be made.query
- Adaptive query which will manage the server-side join of joinList
and
the returned query component.iteration
- Iteration type: FIRST, LAST, or NEXT.outer
- true
if the join should be a left outer join. This type of join is
not supported at the time of this writing, so this parameter should always be
false
. It is here to support a planned, future enhancement.fallback
- A compound query component to use in the event the multi-table adaptive query
switches from preselect to dynamic retrieval mode.public QueryComponent makePreselectServerJoinComponent(java.util.List<QueryComponent> joinList, int iteration, boolean outer)
makePreselectServerJoinComponent
in interface Joinable
joinList
- List of preselect components representing nested query loops which will contain
the preselect query component returned by this method. The last component in the
list represents the nested query loop immediately containing the returned query
component, with which the join will be made.iteration
- Iteration type: FIRST, LAST, or NEXT.outer
- true
if the join should be a left outer join. This type of join is
not supported at the time of this writing, so this parameter should always be
false
. It is here to support a planned, future enhancement.public boolean hasWhereExpression()
hasWhereExpression
in interface Joinable
true
if there is a where expression; else false
.public java.util.Iterator<RecordBuffer> recordBuffers()
ChangeBroker
to receive notifications of any change to DMOs whose
interface types match that returned by the RecordBuffer.getDMOInterface()
method of the returned buffer.recordBuffers
in interface RecordChangeListener
public void registerRecordChangeListeners(int scope)
RecordChangeListener
s associated with this
query (if any), with the context-local ChangeBroker
at the
indicated scope.registerRecordChangeListeners
in interface Joinable
scope
- Scope at which listeners should be registered with the change broker.public void close()
close
in interface P2JQuery
close
in class AbstractQuery
public void close(boolean inResource)
public void cleanup()
ChangeBroker
if they were added in the global scope, otherwise, the
ChangeBroker
will drop them automatically when the respective scope is finished.cleanup
in interface P2JQuery
cleanup
in class AbstractQuery
public void stateChanged(RecordChangeEvent event) throws PersistenceException
stateChanged
in interface RecordChangeListener
event
- Event which describes the DMO state change.PersistenceException
- if any error occurs while processing the state change event.public OffEnd getOffEnd()
public character indexInformation(NumberType n)
indexInformation
in interface IndexInformation
indexInformation
in interface P2JQuery
indexInformation
in class AbstractQuery
n
- An integer expression that evaluates to the level of join for which you want index
information.void setReferenceRecord(Persistable referenceRecord)
referenceRecord
- The record whose data defines current "place" in query results.protected void registerChangeListener()
protected boolean isIdOnly()
true
for a projection query, else false
.protected void initializeBuffer()
protected void releaseBuffers()
releaseBuffers
in class AbstractQuery
QueryOffEndException
- if the buffer contained a record and it was released.protected void prepareBuffer() throws ValidationException
ValidationException
- if the parent's implementation is invoked and a buffer flush
triggers a validation error for the record currently stored in
the buffer.protected void updateBuffer(Persistable dmo, LockType lockType, boolean errorIfNull, OffEnd offEnd)
dmo
is null.dmo
- Record to be stored in buffer.lockType
- Lock type associated with the record, which will be remembered
by the buffer.errorIfNull
- If true
, setting a null
value as the
current record in an underlying buffer will raise an error
condition (if not in silent error mode); if false
,
this action will raise an end condition instead.offEnd
- Enum indicating whether query is off-end, and if so, in which
direction.protected java.lang.Object getBreakValue()
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
.
getBreakValue
in class DynamicQuery
null
.protected RecordBuffer getBuffer()
protected java.lang.Object[] getCurrentArgs()
protected LockType getLockType()
protected Persistable execute(java.lang.Object[] values, LockType lockType, boolean unique, boolean updateLock)
The latest record to be stored in the record buffer, if any, marks our
current position in the query's results. Its data is used to substitute
into the placeholder parameters in the query statements' augmented where
clauses. These are added to the values
provided as part of
the base query.
Client-Side Where Clause Handling
If this query involves a client-side where clause expression, an
additional layer of criteria checking takes place. In addition to the
search described above, each returned result is temporarily stored in
the associated record buffer, and the where expression is executed.
If the expression indicates a match, the record is returned. Otherwise,
additional records are retrieved and tested until either a match is
found or no more records are available in the requested navigation
direction.
Unique queries combined with client-side where clauses require special handling and may perform particularly poorly as a result. In this case, every record returned by the first-pass query must be tested against the client-side where expression, even once a result has been found. This must be done to ensure only one record matches the specified criteria. The only exception is the case where a second record is actually found, in which case the uniqueness requirement has been violated, and the remainder of the scan is aborted due to the error.
values
- Array of substitution parameter values for the base where
clause (i.e., the un-augmented portion of the clause).lockType
- Type of lock to acquire for the found record.unique
- true
if there should be no more than one match
for the conditions specified; false
if multiple
matches are possible.updateLock
- true
if the status of the lock on the retrieved
record should be modified; else false
. This is
set to true
for actual retrievals, and to
false
when only detecting whether a record would
be found, or when peeking a record.null
if
no record was found.ErrorConditionException
- if a recoverable error occurred whileprotected void handleExecuteException(LockUnavailableException exc)
ErrorManager
.
Subclasses which require different handling must override this method.
exc
- Cause exception.protected void handleExecuteException(ValidationException exc)
ErrorManager
.
Subclasses which require different handling must override this method.
exc
- Cause exception.protected void handleExecuteException(PersistenceException exc)
ErrorManager
.
Subclasses which require different handling must override this method.
exc
- Cause exception.protected HQLHelper getHelper()
HQLHelper
object which supports this query, creating it first if
necessary.protected void activateUnique()
protected void activateFirst()
private void activateLast()
private void activateNext()
private void activatePrevious()
private void resolveArgs()
This causes all variable (i.e. BaseDataType
) arguments to
be duplicated, and all Resolvable
s, except
FieldReference
s, to be resolved and the result stored.
FieldReference
s are simply stored, and are resolved
separately, on demand, each time the query is executed.
private Persistable findNext(java.lang.Object[] values, LockType lockType, boolean updateLock)
values
- Array of substitution parameter values for the base where
clause (i.e., the un-augmented portion of the clause).lockType
- Type of lock to acquire for the found record.updateLock
- true
if the status of the lock on the retrieved
record should be modified; else false
. This is
set to true
for actual retrievals, and to
false
when only detecting whether a record would
be found, or when peeking a record.private Persistable findPrevious(java.lang.Object[] values, LockType lockType, boolean updateLock)
values
- Array of substitution parameter values for the base where
clause (i.e., the un-augmented portion of the clause).lockType
- Type of lock to acquire for the found record.updateLock
- true
if the status of the lock on the retrieved
record should be modified; else false
. This is
set to true
for actual retrievals, and to
false
when only detecting whether a record would
be found, or when peeking a record.private Persistable loadByValue(java.lang.Object[] data, LockType lockType)
data
- Array containing a single primary key ID or DMO.lockType
- Type of lock to be applied to the record loaded.null
if there is no record matching the ID.private Persistable loadByValue(java.lang.Object[] data, LockType lockType, boolean silentIfNullId)
data
- Array containing a single primary key ID or DMO.lockType
- Type of lock to be applied to the record loaded.silentIfNullId
- If true
, do not raise error if some of the provided
IDs are null
. null
IDs are valid for
queries with OUTER join.null
if there is no record matching the ID.private java.lang.Object[] getIDs(Persistable dmo)
dmo
- Data record whose ID is to be stored in the array.null
if dmo
is null
.private void errorFindFirstLast()
ErrorConditionException
- if silent error mode is suppressed.private Persistable executeImpl(java.lang.Object[] values, LockType lockType, boolean unique, boolean updateLock)
The latest record to be stored in the record buffer, if any, marks our
current position in the query's results. Its data is used to substitute
into the placeholder parameters in the query statements' augmented where
clauses. These are added to the values
provided as part of
the base query.
values
- Array of substitution parameter values for the base where
clause (i.e., the un-augmented portion of the clause).lockType
- Type of lock to apply to the found record.unique
- true
if there should be no more than one match
for the conditions specified; false
if multiple
matches are possible.updateLock
- true
if the status of the lock on the retrieved
record should be modified; else false
. This is
set to true
for actual retrievals, and to
false
when only detecting whether a record would
be found (i.e., the hasXXXX()
methods).null
if
no record was found.ErrorConditionException
- if a recoverable error occurred whileprivate Persistable processDirtyResults(Persistence persistence, Persistable primaryDMO, DirtyInfo info, LockType lockType, boolean updateLock) throws PersistenceException
persistence
- Persistence services object.primaryDMO
- Candidate DMO found in the primary database. Will not be
null
.info
- Information found during the dirty database check.lockType
- Type of lock to apply to the found record.updateLock
- true
if the status of the lock on the retrieved
record should be modified; else false
. This is
set to true
for actual retrievals, and to
false
when only detecting whether a record would
be found (i.e., the hasXXXX()
methods).primaryDMO
or dirtyDMO
,
depending upon which record is most appropriate in terms of the
index being walked, and possibly the most recently found
record, in the case of a relative move (NEXT/PREVIOUS).PersistenceException
- if any error occurs retrieving a record from the primary
database, after determining its ID in the dirty database.LockUnavailableException
- if a no-wait lock requested on dirtyDMO
is
currently unavailable.private void logQueryDetails(java.lang.String hql, java.lang.Object[] parms, Persistable dmo)
hql
- HQL query statement.parms
- Query substitution parametersdmo
- DMO record found, if any.