CompoundQuery (P2J - Progress 4GL to Java Conversion and Runtime)

java.lang.Object
- com.goldencode.p2j.persist.AbstractQuery
- - com.goldencode.p2j.persist.DynamicQuery
  - - com.goldencode.p2j.persist.CompoundQuery

All Implemented Interfaces:

BufferCollection, RecordChangeListener, IndexInformation, P2JQuery, QueryConstants, Scrollable, Openable

Direct Known Subclasses:

PresortCompoundQuery
```
public class CompoundQuery
extends DynamicQuery
implements QueryConstants, RecordChangeListener
```
A client-side (relative to the database server) implementation of a multi-table, join query. Queries of individual tables are added via one of the addComponent method variants. This query type can combine both PreselectQuerys and RandomAccessQuerys as its components. However, preselected tables must always be to the left of (i.e., outward from) non-preselected tables in the query. That is, a PreselectQuery object can never be added, once a RandomAccessQuery object has been added to a compound query.
Inner and left outer joins are supported. However, inner joins must always occur to the left (i.e., outward from) outer joins. If, at the time a component query specified as an inner join is added, there are previously added outer-join components which in their where clause use one or more buffers as the inner-join component's where clause, these outer-join components will automatically be converted to an inner join, to satisfy the condition that all inner joins are on the left of the outer-join components.
This query retrieves result records in two modes: iterating and random access. Iterating mode is active when using the iterate() method to advance the query to the next, composite row of records in the result set. Random access mode is active when using any of the other retrieval methods (first, last, next, previous, current). The difference between the modes is that iterating mode always terminates with a QueryOffEndException when no further record retrieval is possible; random access mode does not. Random access mode thus allows client code to advance off the end of the result set and continue processing.
CompoundQuery abstracts the use of multiple query implementations to achieve a dynamic, multi-table query. It delegates the record retrieval work to the underlying queries, but manages the overall navigation of the results. Delegate queries must implement the Joinable interface. Each "row" in the "result set" is a logical construct, the virtual composite of multiple record buffers. Advancing to a new row (be it forwards, backwards, first, last) means advancing the most specific query possible to the next matching record in its predetermined progression. Once the most specific query can no longer advance, the next most specific query is advanced, the most specific query is reset to its starting state, and we try to find a joining match for the most specific query again, given that its outer query has a new value with which to join. This continues until the most specific possible query has advanced, or we have moved to our least specific query component, and no further match is possible. At this point, the query is "off-end". For iterating mode, this is the end of query execution and an end condition is raised. In random access mode, further navigation is possible.
Substitution Parameters
Query substitution parameters require different modes of resolution, depending upon the type of parameter and the nature of the query. A query may be set at construction to resolve all of its parameters once, up front or iteratively, each time an iterative loop construct is entered. The former corresponds with Progress' OPEN QUERY style queries; the latter corresponds with all other iterative record retrieval constructs in Progress (e.g., FOR EACH, DO PRESELECT, REPEAT PRESELECT, REPEAT FOR).
The number of times a parameter is resolved and the timing of such resolution becomes important if an iterative record retrieval construct modifies the values of such parameters during record retrieval. This may occur, for example, if the body of an outer FOR loop modifies the value of a variable used in the where clause of an inner FOR loop. While less of an issue for preselect type queries, these can still be affected if the where clause of a nested query component invokes a client-side function, which may in turn modify state on which the query or related logic depends.
The following conversion rules apply:
```
 ------------------------------------------------------------------------
 Progress Construct                             CompoundQuery Modes
                                        resolveOnce             preselect
 ------------------------------------------------------------------------
 OPEN QUERY FOR                         true (forced to false)  false
 OPEN QUERY PRESELECT                   true (ignored?)         true
 FOR {EACH | FIRST | LAST}              false                   false
 DO PRESELECT                           false                   true
 REPEAT PRESELECT                       false                   true
 ------------------------------------------------------------------------
 
```

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private class`	`CompoundQuery.Optimizer` Inner class which attempts to optimize the enclosing, compound query's individual query components into server-side joins.
`private class`	`CompoundQuery.SnapshotParameterFilter` Filter that handles parameters passed to the component's subquery which handles the target buffer.

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
`private int`	`activeIndex` Index of component query currently being iterated
`private java.util.Map<RecordBuffer,java.lang.Integer>`	`buffersMap` Map of all buffers participating in this query to their 0-based index positions
`private Finalizable`	`cleaner` Cleaner executed when this query's block is exit.
`private java.util.ArrayList<CompoundComponent>`	`components` Query components currently in use by the compound query
`private int[]`	`counters` Current index position in each component query loop
`protected boolean`	`currentRowDeleted` Determines if the current row was deleted by DELETE-RESULT-LIST-ENTRY.
`private static boolean`	`deferOptimization` Defer optimization until after first composite row has been retrieved (experimental)
`private boolean`	`forceFullResults` Flag indicating the entire result set will be retrieved (useful for FILL operations).
`protected boolean`	`foundFirst` Determines if we have fetched a result row.
`private static CentralLogger`	`log` Logger
`private java.util.ArrayList<CompoundComponent>`	`originalComponents` Query components originally added to the compound query
`private boolean`	`postponeAccumulation` Postpone accumulation on retrieve.
`private boolean`	`preselect` Force preselection of all results?
`private boolean`	`preselected` Have results been preselected?
`private boolean`	`regCleaner` Has query been registered for resource cleanup?
`private boolean`	`resolveOnce` Resolve arguments once, up front, or on every loop cycle?
`private int`	`tableCount` Total number of tables involved in this compound query
`protected boolean`	`unregisterOnCleanup` Determines if this will be unregistered from ChangeBroker on cleanup.
`private boolean[]`	`useSnapshot` Specifies if snapshot values (values at the time when the record was loaded) should be used as FQL sub-query parameters for specific component instead of the actual values.
`private boolean`	`whereTranslated` Flag indicated if the WHERE clause has been translated.

Fields inherited from class com.goldencode.p2j.persist.DynamicQuery
cursor

Fields inherited from class com.goldencode.p2j.persist.AbstractQuery
closed, dynamicPredicate, errorHelper, excluded, included, indexedReposition, inverseSorting, lenientOffEnd, outer, parameterFilter

Fields inherited from interface com.goldencode.p2j.persist.QueryConstants
CURRENT, FIRST, ITERATE, LAST, NEXT, NONE, PREVIOUS, RETRIEVE_MODES, UNIQUE

Constructor Summary

Constructors
Constructor and Description

CompoundQuery()
Default constructor.

Constructors
Constructor and Description
`CompoundQuery()` Default constructor.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addComponent(Joinable query)` Add a joinable query to the compound query.
`void`	`addComponent(Joinable query, int iteration)` Add a joinable query to the compound query, and specify the nature of the iteration which will be performed (first, last, next, etc.) on that component, when the compound query is iterated.
`void`	`addComponent(Joinable query, int iteration, boolean outer)` Add a joinable query to the compound query, and specify the nature of the iteration which will be performed (first, last, next, etc.) on that component, when the compound query is iterated.
`(package private) void`	`addCompoundComponent(CompoundComponent component)` Add a component query to this compound query and adjust the table count accordingly.
`boolean`	`addDynamicFilter(FieldReference fr, BaseDataType val, java.lang.String format)` Adds a new constraint term to the where predicate of this query, effectively filtering out any rows whose referenced field does not match the requested value.
`P2JQuery`	`addExternalBuffers(DataModelObject... dmos)` Add one or more buffers to the list of those which this query references externally.
`protected void`	`afterReposition(boolean permitFetch, boolean error)` This method is an extension to the AbstractQuery normal behavior.
`protected boolean`	`canOptimize()` Indicate whether this object can be optimized.
`void`	`cleanup()` Clean up resources associated with this query when its scope ends.
`void`	`clearDynamicFilters()` Clears any dynamically filters added at runtime.
`void`	`clearResults()` Clear the current results from the query, so the same query instance can be executed again, without having to `re-open` it.
`void`	`close()` Explicitly close the prepared query.
`void`	`close(boolean inResource)` Explicitly close the prepared query.
`private java.lang.Object[]`	`collectRowData(int navigation)` Assemble an array of primary key IDs or DMOs for the current records in the buffers underlying this query, from left-most to right-most (in the sense of how the query joins the associated tables).
`logical`	`createResultListEntry()` Creates an entry in the result list for the current row.
`boolean`	`current()` Retrieve the current virtual, composite row of results for the compound query.
`boolean`	`current(LockType lockType)` Retrieve the current virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
`logical`	`deleteResultListEntry(boolean allowBetweenRows)` Deletes the current row of a query's result list.
`boolean`	`first()` Retrieve the first virtual, composite row of results for the compound query.
`boolean`	`first(boolean iterating)` Retrieve the first virtual, composite row of results for the compound query.
`boolean`	`first(boolean iterating, LockType lockType)` Retrieve the first virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
`boolean`	`first(LockType lockType)` Retrieve the first virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
`protected java.lang.Object`	`getBreakValue()` Return an object which represents a property value which defines the end of a sort band.
`double`	`getCombinedExecutionTime()` Function that sums and returns the execution time of the components, denoting the total time of execution of this query.
`java.lang.String`	`getCombinedFqls()` Function that combines the FQL of the components from this query.
`private java.util.ArrayList<CompoundComponent>`	`getComponents()` Retrieve the list of query components.
`OffEnd`	`getOffEnd()` Report the off-end status of this query, which is essentially the off-end status of its outermost component query.
`java.util.ArrayList<QueryOffEndListener>`	`getOffEndListeners()` Get all the off-end listeners associated with this query.
`(package private) java.util.ArrayList<CompoundComponent>`	`getOriginalComponents()` Retrieve the list of original query components (unoptimized).
`private RecordBuffer[]`	`getRecordBuffersInternal()` Get an array of all record buffers managed by this query.
`int`	`getTableCount()` Get the number of tables joined by this query.
`void`	`hintFullResults()` Mark the query to retrieve the entire result set (useful for FILL operations).
`character`	`indexInformation(NumberType n)` Conversion of INDEX-INFORMATION attribute (KW_IDX_INFO).
`CompoundQuery`	`initialize(boolean resolveOnce, boolean preselect)` Initialization logic.
`CompoundQuery`	`initialize2f()` Initialization logic.
`private void`	`initializeComponentQuery(Joinable query)` Initialize state of a component query.
`protected void`	`initReferenceRowSupport(boolean globalScope)` Init structures required to use reference row: create the map of all buffers, register parameter filters for sub-queries and register this query as a record change listener.
`protected boolean`	`isPresorted()` Determines if the query is presorted, i.e.
`boolean`	`iterate()` Advance the compound query, triggering one or more of the underlying queries to retrieve a new record.
`boolean`	`last()` Retrieve the last virtual, composite row of results for the compound query.
`boolean`	`last(boolean iterating)` Retrieve the last virtual, composite row of results for the compound query.
`boolean`	`last(boolean iterating, LockType lockType)` Retrieve the last virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
`boolean`	`last(LockType lockType)` Retrieve the last virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
`protected boolean`	`loadByValues(java.lang.Object[] data, LockType lockType, boolean iterating)` Load a virtual, composite record by loading each record buffer managed by this query with a DMO, given its primary key ID in the specified `ids` array.
`protected void`	`loadRowAtCursor()` Synchronize the query with the cursor by causing the query to load the current row's results (if any) into its backing buffer(s).
`private void`	`maybeOptimize()` Method which attempts to optimize this object's query components into one or more server-side joins.
`boolean`	`next()` Retrieve the next virtual, composite row of results for the compound query.
`boolean`	`next(boolean iterating)` Retrieve the next virtual, composite row of results for the compound query.
`boolean`	`next(boolean iterating, LockType lockType)` Retrieve the next virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
`boolean`	`next(LockType lockType)` Retrieve the next virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
`void`	`notifyRepositionListeners(boolean closed, boolean error, int targetRepositionRow)` Notify all registered listeners that query is repositioned or closed.
`void`	`open()` Open the query once all query components have been added.
`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`	`postponeAccumulation()` Switch on postponed accumulation on next retrieve.
`protected void`	`preselectResults()` Preselect all results by creating a common cursor and `SimpleResults` for each component.
`protected void`	`presort()` If the query is a presort query, then presort the results stored in the cursor.
`boolean`	`previous()` Retrieve the previous virtual, composite row of results for the compound query.
`boolean`	`previous(boolean iterating)` Retrieve the previous virtual, composite row of results for the compound query.
`boolean`	`previous(boolean iterating, LockType lockType)` Retrieve the previous virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
`boolean`	`previous(LockType lockType)` Retrieve the previous virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
`private java.lang.Object[]`	`processComponent(int navigation, CompoundComponent component, int count, LockType lockType, boolean peek)` Advance a single query component, according to the overall query navigation direction, and that component's natural iteration type.
`java.util.Iterator<RecordBuffer>`	`recordBuffers()` Report the record buffers for whose changes this object is interested in listening.
`protected void`	`registerCleaner()` Register a `Finalizable` with the transaction manager for resource cleanup when this query's scope ends.
`private boolean`	`registerRecordChangeListeners()` Register the query within each component as a record change listener.
`protected void`	`releaseAllBuffers()` Release all backing buffers of for all components.
`void`	`releaseBuffers()` Releases buffers from all components.
`protected void`	`restoreAccumulation()` Switch on postponed accumulation on next retrieve.
`protected java.lang.Object[]`	`retrieve(int navigation, LockType lockType, boolean iterating)` Retrieve a virtual, composite row of results for the compound query.
`protected java.lang.Object[]`	`retrieve(int navigation, LockType lockType, boolean iterating, boolean peek)` Retrieve a virtual, composite row of results for the compound query.
`private java.lang.Object[]`	`retrieveImpl(int navigation, LockType lockType, boolean iterating, boolean peek)` Retrieve a virtual, composite row of results for the compound query.
`void`	`setBrowsed(boolean browsed)` Indicate to this query that whether it is associated with a browse widget or not.
`private void`	`setComponentsBrowsed()` Iterate the component queries of this object and set their browsed flags to match that of this object.
`void`	`setDataRelation(DataRelation relation)` Set the recursive DATA-RELATION the query is to FILL for.
`void`	`setScrolling()` Create a cursor for this query and ensure that any component queries are scrollable, whether they already have been added, or will be added in the future.
`void`	`setSkipDeletedRecord(logical on)` Setter for SKIP-DELETED-RECORD query attribute.
`void`	`setStandalone(boolean standalone)` Change the standalone nature of this query.
`void`	`stateChanged(RecordChangeEvent event)` Respond to a record change event.
`private void`	`translateWhere()` Translate the WHERE clause for all `components`.

Methods inherited from class com.goldencode.p2j.persist.DynamicQuery
_isOffEnd, backward, backward, currentRow, currentRowImpl, forward, forward, incrementMoves, isNativelyPreselect, isPreselect, isScrolling, reposition, reposition, repositionByID, repositionByID, repositionByID, reset, resetScrolling, size, verifyScrolling

Methods inherited from class com.goldencode.p2j.persist.AbstractQuery
_getNext, _isSkipDeletedRecord, accumulate, addAccumulator, addAccumulator, addBuffer, addBuffer, addQueryEventListener, addRepositionListener, afterReposition, afterReposition, bufferHandle, bufferHandle, bufferHandle, bufferHandle, bufferHandle, buffersMatch, changeForwardOnly, changeForwardOnly, 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, isBrowsed, isDynamicPredicate, isErrorIfNull, isFatalError, isFetchOnReposition, isFillingBrowseRows, isIndexedReposition, isIterating, isLastOfBreakGroup, isLenientOffEnd, isNewBreakGroup, isOffEnd, isOmitAlias, isOpen, isPresort, isRepositionNotificationActive, isSkipDeletedRecord, isStandalone, notifyQueryCloseListeners, notifyQueryOpenListeners, numBuffers, numResults, numResults, prepare, prepare, prepareFetch, prepareString, preprocessSubstitutionArguments, queryBackward, queryBackward, queryClose, queryForward, queryForward, queryOpen, queryReposition, queryReposition, queryRepositionByID, removeRepositionListener, setBuffers, setBuffers, setCache, setCache, setDynamicPredicate, setErrorIfNull, setFatalError, setFetchOnReposition, setFillingBrowseRows, setIndexedReposition, setIterating, setLenientOffEnd, setOmitAlias, setOuter, setParameterFilter, setPresort, 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.P2JQuery
_getNext, addAccumulator, addAccumulator, addQueryEventListener, addRepositionListener, changeForwardOnly, changeForwardOnly, deleteResultListEntry, exclude, 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, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getPrevious, getRecordBuffers, hasAny, hasAny, hasAny, hasAny, hasOne, hasOne, hasOne, hasOne, include, indexInformation, indexInformation, isBrowsed, isDynamicPredicate, isFetchOnReposition, isFillingBrowseRows, isFindByRowid, isFirstOfGroup, isFirstOfGroup, isIndexedReposition, isIterating, isLastOfGroup, isLastOfGroup, isOffEnd, isPresort, isSkipDeletedRecord, isStandalone, notifyQueryCloseListeners, notifyQueryOpenListeners, prepare, prepare, prepareString, queryBackward, queryBackward, queryClose, queryForward, queryForward, queryOpen, queryReposition, queryReposition, queryRepositionByID, queryRepositionByID, removeRepositionListener, resetQuery, setBasicLogging, setBasicLogging, setCache, setCache, setDynamicPredicate, setErrorIfNull, setFetchOnReposition, setFillingBrowseRows, setIndexedReposition, setIterating, setLenientOffEnd, setParameterFilter, setPresort, 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
  - log
```
private static final CentralLogger log
```
    Logger
  - deferOptimization
```
private static final boolean deferOptimization
```
    Defer optimization until after first composite row has been retrieved (experimental)
    
    See Also:
    
    Constant Field Values
  - currentRowDeleted
```
protected boolean currentRowDeleted
```
    Determines if the current row was deleted by DELETE-RESULT-LIST-ENTRY. Note that if the query is off-end, it also can be "deleted".
  - foundFirst
```
protected boolean foundFirst
```
    Determines if we have fetched a result row. Only for non-scrolling queries.
  - unregisterOnCleanup
```
protected boolean unregisterOnCleanup
```
    Determines if this will be unregistered from ChangeBroker on cleanup.
  - preselect
```
private boolean preselect
```
    Force preselection of all results?
  - originalComponents
```
private final java.util.ArrayList<CompoundComponent> originalComponents
```
    Query components originally added to the compound query
  - resolveOnce
```
private boolean resolveOnce
```
    Resolve arguments once, up front, or on every loop cycle?
  - components
```
private java.util.ArrayList<CompoundComponent> components
```
    Query components currently in use by the compound query
  - preselected
```
private boolean preselected
```
    Have results been preselected?
  - counters
```
private int[] counters
```
    Current index position in each component query loop
  - useSnapshot
```
private boolean[] useSnapshot
```
    Specifies if snapshot values (values at the time when the record was loaded) should be used as FQL sub-query parameters for specific component instead of the actual values. The array has size components.size() - 1 and excludes the first (outermost) component because it cannot have FQL which includes fields of an outer component.
  - activeIndex
```
private int activeIndex
```
    Index of component query currently being iterated
  - tableCount
```
private int tableCount
```
    Total number of tables involved in this compound query
  - postponeAccumulation
```
private boolean postponeAccumulation
```
    Postpone accumulation on retrieve.
  - buffersMap
```
private java.util.Map<RecordBuffer,java.lang.Integer> buffersMap
```
    Map of all buffers participating in this query to their 0-based index positions
  - regCleaner
```
private boolean regCleaner
```
    Has query been registered for resource cleanup?
  - forceFullResults
```
private boolean forceFullResults
```
    Flag indicating the entire result set will be retrieved (useful for FILL operations).
  - cleaner
```
private final Finalizable cleaner
```
    Cleaner executed when this query's block is exit.
  - whereTranslated
```
private boolean whereTranslated
```
    Flag indicated if the WHERE clause has been translated.
- Constructor Detail
  - CompoundQuery
```
public CompoundQuery()
```
    Default constructor. Initialization is deferred until initialize() is called.
- 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
    
    Overrides:
    
    clearResults in class DynamicQuery
  - initialize
```
public CompoundQuery initialize(boolean resolveOnce,
                                boolean preselect)
```
    Initialization logic.
    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.
    
    Parameters:
    
    preselect - true to force preselection of all results; false otherwise.
    
    Returns:
    
    The query instance.
  - initialize2f
```
public CompoundQuery initialize2f()
```
    Initialization logic.
    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.
    
    Returns:
    
    This query instance.
  - setScrolling
```
public void setScrolling()
```
    Create a cursor for this query and ensure that any component queries are scrollable, whether they already have been added, or will be added in the future.
    
    Specified by:
    
    setScrolling in interface P2JQuery
    
    Overrides:
    
    setScrolling in class DynamicQuery
  - getTableCount
```
public int getTableCount()
```
    Get the number of tables joined by this query.
    
    Specified by:
    
    getTableCount in interface P2JQuery
    
    Returns:
    
    Number of tables joined by this query.
  - getOffEndListeners
```
public java.util.ArrayList<QueryOffEndListener> getOffEndListeners()
```
    Get all the off-end listeners associated with this query.
    
    Specified by:
    
    getOffEndListeners in interface P2JQuery
    
    Returns:
    
    the off-end listeners associated with this query.
  - hintFullResults
```
public void hintFullResults()
```
    Mark the query to retrieve the entire result set (useful for FILL operations).
    
    Specified by:
    
    hintFullResults in interface P2JQuery
  - addComponent
```
public void addComponent(Joinable query)
```
    Add a joinable query to the compound query. If this is not the first component to be added to the query, its results will be joined to the immediately previous component by an inner join. This query will be iterated using the NEXT iteration type.
    
    Parameters:
    
    query - Query which will perform the fundamental work for this component when the compound query is iterated.
    
    Throws:
    
    java.lang.IllegalStateException - if this method is invoked during an iteration cycle.
    
    See Also:
    
    iterate()
  - addComponent
```
public void addComponent(Joinable query,
                         int iteration)
```
    Add a joinable query to the compound query, and specify the nature of the iteration which will be performed (first, last, next, etc.) on that component, when the compound query is iterated. If this is not the first component to be added to the query, its results will be joined to the immediately previous component by an inner join.
    
    Parameters:
    
    query - Query which will perform the fundamental work for this component when the compound query is iterated.
    
    iteration - A constant indicating the type of work to be performed upon an iteration of the compound query. This parameter determines whether the underlying query will be asked to perform a first, last, next, previous, or unique record retrieval.
    
    Throws:
    
    java.lang.IllegalStateException - if this method is invoked during an iteration cycle.
    
    See Also:
    
    iterate()
  - addComponent
```
public void addComponent(Joinable query,
                         int iteration,
                         boolean outer)
```
    Add a joinable query to the compound query, and specify the nature of the iteration which will be performed (first, last, next, etc.) on that component, when the compound query is iterated. If this is not the first component to be added to the query, the type of join performed with the immediately previous component is determined by the value of outer.
    
    Parameters:
    
    query - Query which will perform the fundamental work for this component when the compound query is iterated.
    
    iteration - A constant indicating the type of work to be performed upon an iteration of the compound query. This parameter determines whether the underlying query will be asked to perform a first, last, next, previous, or unique record retrieval.
    
    outer - true if this component should be joined to the previously added component via a left outer join; false if an inner join is required.
    If, at the time a component query specified as an inner join is added, there are previously added outer-join components which in their where clause use one or more buffers as the inner-join component's where clause, these outer-join components will automatically be converted to an inner join, to satisfy the condition that all inner joins are on the left of the outer-join components.
    
    Throws:
    
    java.lang.IllegalStateException - if this method is invoked during an iteration cycle.
    
    See Also:
    
    iterate()
  - addExternalBuffers
```
public P2JQuery addExternalBuffers(DataModelObject... dmos)
```
    Add one or more buffers to the list of those which this query references externally. These typically will be buffers referenced by converted CAN-FIND expressions embedded in the query's FQL expression, which are not the primary buffers associated with the query.
    This method overrides the default implementation to set external buffers on the most recently added component of this compound query. It therefore must be called immediately after the target component is added and before the query is opened, optimized, or executed.
    
    Specified by:
    
    addExternalBuffers in interface P2JQuery
    
    Overrides:
    
    addExternalBuffers in class AbstractQuery
    
    Parameters:
    
    dmos - One or more external buffers to add to the most recently added query component.
    
    Returns:
    
    This query instance.
    
    Throws:
    
    java.lang.IllegalStateException - if called before a component has been added or after query has been optimized.
  - setSkipDeletedRecord
```
public void setSkipDeletedRecord(logical on)
```
    Setter for SKIP-DELETED-RECORD query attribute.
    
    Specified by:
    
    setSkipDeletedRecord in interface P2JQuery
    
    Overrides:
    
    setSkipDeletedRecord in class AbstractQuery
    
    Parameters:
    
    on - New value for the attribute.
  - setBrowsed
```
public void setBrowsed(boolean browsed)
```
    Indicate to this query that whether it is associated with a browse widget or not.
    
    Specified by:
    
    setBrowsed in interface P2JQuery
    
    Overrides:
    
    setBrowsed in class AbstractQuery
    
    Parameters:
    
    browsed - true to indicate the query has an associated browse widget, else false.
  - open
```
public void open()
```
    Open the query once all query components have been added.
    
    Specified by:
    
    open in interface P2JQuery
    
    Overrides:
    
    open in class DynamicQuery
  - iterate
```
public boolean iterate()
```
    Advance the compound query, triggering one or more of the underlying queries to retrieve a new record. This produces a virtual, composite row of results which is the combination of the records retrieved by each component query.
    
    Throws:
    
    QueryOffEndException - if no more records can be retrieved by the underlying queries.
    
    ErrorConditionException - if an underlying query triggers an error.
  - first
```
public boolean first()
```
    Retrieve the first virtual, composite row of results for the compound query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    first in interface P2JQuery
    
    Returns:
    
    true if query could retrive the first record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - first
```
public boolean first(boolean iterating)
```
    Retrieve the first virtual, composite row of results for the compound query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Parameters:
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    Returns:
    
    true if query could retrive the first record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an underlying query triggers an error.
  - first
```
public boolean first(LockType lockType)
```
    Retrieve the first virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    first in interface P2JQuery
    
    Parameters:
    
    lockType - Lock type which should override that of any underlying query.
    
    Returns:
    
    true if query could retrive the first record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - first
```
public boolean first(boolean iterating,
                     LockType lockType)
```
    Retrieve the first virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Parameters:
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    lockType - Lock type which should override that of any underlying query.
    
    Returns:
    
    true if query could retrive the first record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an underlying query triggers an error.
  - last
```
public boolean last()
```
    Retrieve the last virtual, composite row of results for the compound query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    last in interface P2JQuery
    
    Returns:
    
    true if query could retrive the last record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - last
```
public boolean last(boolean iterating)
```
    Retrieve the last virtual, composite row of results for the compound query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Parameters:
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    Returns:
    
    true if query could retrive the last record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an underlying query triggers an error.
  - last
```
public boolean last(LockType lockType)
```
    Retrieve the last virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    last in interface P2JQuery
    
    Parameters:
    
    lockType - Lock type which should override that of any underlying query.
    
    Returns:
    
    true if query could retrive the last record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - last
```
public boolean last(boolean iterating,
                    LockType lockType)
```
    Retrieve the last virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Parameters:
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    lockType - Lock type which should override that of any underlying query.
    
    Returns:
    
    true if query could retrive the last record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an underlying query triggers an error.
  - next
```
public boolean next()
```
    Retrieve the next virtual, composite row of results for the compound query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    next in interface P2JQuery
    
    Returns:
    
    true if query could retrive the next record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - next
```
public boolean next(boolean iterating)
```
    Retrieve the next virtual, composite row of results for the compound query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Parameters:
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    Returns:
    
    true if query could retrive the next record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an underlying query triggers an error.
  - next
```
public boolean next(LockType lockType)
```
    Retrieve the next virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    next in interface P2JQuery
    
    Parameters:
    
    lockType - Lock type which should override that of any underlying query.
    
    Returns:
    
    true if query could retrive the next record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - next
```
public boolean next(boolean iterating,
                    LockType lockType)
```
    Retrieve the next virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Parameters:
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    lockType - Lock type which should override that of any underlying query.
    
    Returns:
    
    true if query could retrive the next record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an underlying query triggers an error.
  - previous
```
public boolean previous()
```
    Retrieve the previous virtual, composite row of results for the compound query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    previous in interface P2JQuery
    
    Returns:
    
    true if query could retrive the previous record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - previous
```
public boolean previous(boolean iterating)
```
    Retrieve the previous virtual, composite row of results for the compound query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Parameters:
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    Returns:
    
    true if query could retrive the previous record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an underlying query triggers an error.
  - previous
```
public boolean previous(LockType lockType)
```
    Retrieve the previous virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    previous in interface P2JQuery
    
    Parameters:
    
    lockType - Lock type which should override that of any underlying query.
    
    Returns:
    
    true if query could retrive the previous record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - previous
```
public boolean previous(boolean iterating,
                        LockType lockType)
```
    Retrieve the previous virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Parameters:
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    lockType - Lock type which should override that of any underlying query.
    
    Returns:
    
    true if query could retrive the previous record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an underlying query triggers an error.
  - current
```
public boolean current()
```
    Retrieve the current virtual, composite row of results for the compound query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    current in interface P2JQuery
    
    Returns:
    
    true if query could retrive the current record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - current
```
public boolean current(LockType lockType)
```
    Retrieve the current virtual, composite row of results for the compound query, overriding the lock type to apply to each underlying query.
    This is a combination of records retrieved by each component query. If the compound query involves outer joins, some of the underlying buffers may be empty when this method returns.
    
    Specified by:
    
    current in interface P2JQuery
    
    Parameters:
    
    lockType - Lock type which should override that of any underlying query.
    
    Returns:
    
    true if query could retrive the current record succefully; false if unsuccessful and lenientOffEnd is set on true.
    
    Throws:
    
    ErrorConditionException - if an underlying query triggers an error.
  - peekFirst
```
public java.lang.Object[] peekFirst()
```
    Fetch the array of primary key IDs associated with the first result in this query's result list.
    This implementation actually updates the underlying record buffer(s).
    
    Returns:
    
    Array of record IDs reflecting the first query result, or null if there is no such result.
  - peekLast
```
public java.lang.Object[] peekLast()
```
    Fetch the array of primary key IDs associated with the last result in this query's result list.
    This implementation actually updates the underlying record buffer(s).
    
    Returns:
    
    Array of record IDs reflecting the last query result, or null if there is no such result.
  - peekNext
```
public java.lang.Object[] peekNext()
```
    Fetch the array of primary key IDs associated with the next result in this query's result list.
    This implementation actually updates the underlying record buffer(s). The difference between this function and next() function is that this function calls Scrollable.peekNext() on sub-queries in order to get the next record from underlying results, while next() returns the next record after the current row.
    
    Specified by:
    
    peekNext in interface Scrollable
    
    Returns:
    
    Array of record IDs reflecting the next query result, or null if there is no such result.
  - peekPrevious
```
public java.lang.Object[] peekPrevious()
```
    Fetch the array of primary key IDs associated with the previous result in this query's result list.
    This implementation actually updates the underlying record buffer(s). The difference between this function and previous() function is that this function calls Scrollable.peekPrevious() on sub-queries in order to get the next record from underlying results, while previous() returns the next record after the current row.
    
    Specified by:
    
    peekPrevious in interface Scrollable
    
    Returns:
    
    Array of record IDs reflecting the previous query result, or null if there is no such result.
  - notifyRepositionListeners
```
public void notifyRepositionListeners(boolean closed,
                                      boolean error,
                                      int targetRepositionRow)
```
    Notify all registered listeners that query is repositioned or closed. If this is invoked before any query components have been added to the compound query, it is ignored.
    
    Specified by:
    
    notifyRepositionListeners in interface P2JQuery
    
    Overrides:
    
    notifyRepositionListeners in class AbstractQuery
    
    Parameters:
    
    closed - A true value will inform all listeners that the query was explicitly closed.
    
    error - true if an error happened during reposition.
    
    targetRepositionRow - Row used as the target for reposition. If it was deleted, reposition with fetching may end up on a different row.
  - recordBuffers
```
public java.util.Iterator<RecordBuffer> recordBuffers()
```
    Report the record buffers for whose changes this object is interested in listening. This listener will be registered with the ChangeBroker to receive notifications of any change to DMOs whose interface types match those returned by the RecordBuffer.getDMOInterface() methods of the returned buffers.
    
    Specified by:
    
    recordBuffers in interface RecordChangeListener
    
    Returns:
    
    An iterator on the record buffers stored in each of this query's components.
  - stateChanged
```
public void stateChanged(RecordChangeEvent event)
                  throws PersistenceException
```
    Respond to a record change event.
    
    Specified by:
    
    stateChanged in interface RecordChangeListener
    
    Parameters:
    
    event - Event which describes the DMO state change.
    
    Throws:
    
    PersistenceException - if any error occurs while processing the state change event.
  - setStandalone
```
public void setStandalone(boolean standalone)
```
    Change the standalone nature of this query. A query is standalone by default, but can be changed to non-standalone by the wrapper which contains it.
    
    Specified by:
    
    setStandalone in interface P2JQuery
    
    Overrides:
    
    setStandalone in class AbstractQuery
    
    Parameters:
    
    standalone - true to set query as standalone; false to set query as contained.
  - close
```
public void close()
```
    Explicitly close the prepared query.
    
    Specified by:
    
    close in interface P2JQuery
    
    Overrides:
    
    close in class AbstractQuery
  - close
```
public void close(boolean inResource)
```
    Explicitly close the prepared query. This resets execution state, but it should not change the query's structural state (i.e., the original components), in case the query is re-opened afterward.
    
    Specified by:
    
    close in interface P2JQuery
    
    Parameters:
    
    inResource - Flag indicating this query is used in a QUERY legacy resource.
  - cleanup
```
public void cleanup()
```
    Clean up resources associated with this query when its scope ends.
    
    Specified by:
    
    cleanup in interface P2JQuery
    
    Overrides:
    
    cleanup in class AbstractQuery
  - getOffEnd
```
public OffEnd getOffEnd()
```
    Report the off-end status of this query, which is essentially the off-end status of its outermost component query. The query is not considered off-end in its starting state; that is, if a result has not yet been retrieved.
    
    Specified by:
    
    getOffEnd in interface P2JQuery
    
    Returns:
    
    One of the OffEnd constants NONE, FRONT, or BACK.
  - indexInformation
```
public character indexInformation(NumberType n)
```
    Conversion of INDEX-INFORMATION attribute (KW_IDX_INFO). Getter of INDEX-INFORMATION attribute
    
    Specified by:
    
    indexInformation in interface IndexInformation
    
    Specified by:
    
    indexInformation in interface P2JQuery
    
    Overrides:
    
    indexInformation in class AbstractQuery
    
    Parameters:
    
    n - An integer expression that evaluates to the level of join for which you want index information.
    
    Returns:
    
    A character string consisting of a comma-separated list of the index or indexes the query uses at the level of join specified.
  - deleteResultListEntry
```
public logical deleteResultListEntry(boolean allowBetweenRows)
```
    Deletes the current row of a query's result list. Implements the 4GL DELETE-RESULT-LIST-ENTRY() method.
    
    Specified by:
    
    deleteResultListEntry in interface P2JQuery
    
    Overrides:
    
    deleteResultListEntry in class AbstractQuery
    
    Parameters:
    
    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).
    
    Returns:
    
    true on success.
  - createResultListEntry
```
public logical createResultListEntry()
```
    Creates an entry in the result list for the current row. Implements the 4GL CREATE-RESULT-LIST-ENTRY() method. Created entry contains id(s) of the record(s) currently located in the backing buffer(s).
    
    Specified by:
    
    createResultListEntry in interface P2JQuery
    
    Overrides:
    
    createResultListEntry in class AbstractQuery
    
    Returns:
    
    true on success.
  - setDataRelation
```
public void setDataRelation(DataRelation relation)
```
    Set the recursive DATA-RELATION the query is to FILL for.
    
    Specified by:
    
    setDataRelation in interface P2JQuery
    
    Overrides:
    
    setDataRelation in class AbstractQuery
    
    Parameters:
    
    relation - the recursive DATA-RELATION the query is to FILL for
  - getCombinedFqls
```
public java.lang.String getCombinedFqls()
```
    Function that combines the FQL of the components from this query. The FQLs are separated by a comma. This function is used for logging purposes.
    
    Returns:
    
    String The combined FQLs.
  - getCombinedExecutionTime
```
public double getCombinedExecutionTime()
```
    Function that sums and returns the execution time of the components, denoting the total time of execution of this query. This function is used for logging purposes.
    
    Returns:
    
    double The total time of execution of this CompoundQuery.
  - registerCleaner
```
protected void registerCleaner()
```
    Register a Finalizable with the transaction manager for resource cleanup when this query's scope ends.
  - afterReposition
```
protected void afterReposition(boolean permitFetch,
                               boolean error)
```
    This method is an extension to the AbstractQuery normal behavior. On a reposition, the buffers should be validated and eventually fire their write triggers. Furthermore, the bottom-most buffer should be released. The other buffers should be indeterminably released - this feature is safe to ignore.
    
    Overrides:
    
    afterReposition in class AbstractQuery
    
    Parameters:
    
    permitFetch - true to permit immediate record fetch; false to override fetchOnReposition flag and explicitly disallow immediate record fetch.
    
    error - true if error happened during reposition.
  - initReferenceRowSupport
```
protected void initReferenceRowSupport(boolean globalScope)
```
    Init structures required to use reference row: create the map of all buffers, register parameter filters for sub-queries and register this query as a record change listener.
    
    Parameters:
    
    globalScope - Flag indicating if the block at which this query is registered as record change listener is the global scope.
  - getBreakValue
```
protected 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 result in break value being null.
    
    Specified by:
    
    getBreakValue in class DynamicQuery
    
    Returns:
    
    null always; when a compound query is the backing query for a dynamic results object, it should never return a non-null value, because it cannot shift into a preselect mode.
  - retrieve
```
protected java.lang.Object[] retrieve(int navigation,
                                      LockType lockType,
                                      boolean iterating)
```
    Retrieve a virtual, composite row of results for the compound query. This method implements a client-side join of multiple, single-row record retrievals performed by the underlying, component queries. It works first from outermost component inward, retrieving a record at each level. When each component's backing buffer contains a record, the composite retrieval is complete and the method returns. On subsequent iterations, the innermost component is advanced first. If no more matches are possible at this level, the algorithm moves outward one level and attempts to advance that level. On success, it moves inward again, on failure, it moves outward again. This continues until either a new composite row of results is assembled, or no further records can be found. This progression ensures that each inner query cycles through all of its matches before the next outer query advances.
    Preselect Mode
    CompoundQuery generally operates as a dynamic query, though it can be used to generate a fixed list of preselected results. When in this mode, the first time this method is executed, a results list is generated. This is done by retrieving each virtual, composite row which meets the overall query's criteria, and caching the primary keys of these records in the underlying cursor. Each underlying query is assigned the correct subset of these IDs, such that subsequent retrieval requests can safely use the cursor to retrieve the correct records. As a result, in preselect mode, this method is only ever invoked once per query.
    
    Parameters:
    
    navigation - Type of advancement applied to the compound query; i.e., how the virtual composite result set is navigated as a whole: forward (next), backward (previous), jump to first or last, or reload current records in all buffers.
    
    lockType - Overriding lock type to apply to each underlying buffer.
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    Returns:
    
    An array of the primary key IDs for every table involved in the query, (which together identify a unique, virtual record), if a result row was successfully retrieved; null if no more results were available (and we were not iterating).
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an error occurred retrieving the record for an underlying query.
  - retrieve
```
protected java.lang.Object[] retrieve(int navigation,
                                      LockType lockType,
                                      boolean iterating,
                                      boolean peek)
```
    Retrieve a virtual, composite row of results for the compound query. This method implements a client-side join of multiple, single-row record retrievals performed by the underlying, component queries. It works first from outermost component inward, retrieving a record at each level. When each component's backing buffer contains a record, the composite retrieval is complete and the method returns. On subsequent iterations, the innermost component is advanced first. If no more matches are possible at this level, the algorithm moves outward one level and attempts to advance that level. On success, it moves inward again, on failure, it moves outward again. This continues until either a new composite row of results is assembled, or no further records can be found. This progression ensures that each inner query cycles through all of its matches before the next outer query advances.
    Preselect Mode
    CompoundQuery generally operates as a dynamic query, though it can be used to generate a fixed list of preselected results. When in this mode, the first time this method is executed, a results list is generated. This is done by retrieving each virtual, composite row which meets the overall query's criteria, and caching the primary keys of these records in the underlying cursor. Each underlying query is assigned the correct subset of these IDs, such that subsequent retrieval requests can safely use the cursor to retrieve the correct records. As a result, in preselect mode, this method is only ever invoked once per query.
    
    Parameters:
    
    navigation - Type of advancement applied to the compound query; i.e., how the virtual composite result set is navigated as a whole: forward (next), backward (previous), jump to first or last, or reload current records in all buffers.
    
    lockType - Overriding lock type to apply to each underlying buffer.
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    peek - true if sub-queries should be interrogated using Scrollable.peekNext()/Scrollable.peekPrevious() rather than P2JQuery.next()/P2JQuery.previous(). The difference is that in the first case sub-queries return the next/previous record from underlying results, while in the second case they return the next/previous record after the current row.
    
    Returns:
    
    An array of the primary key IDs for every table involved in the query, (which together identify a unique, virtual record), if a result row was successfully retrieved; null if no more results were available (and we were not iterating).
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an error occurred retrieving the record for an underlying query.
  - isPresorted
```
protected boolean isPresorted()
```
    Determines if the query is presorted, i.e. if the query is sorted up front in some special way.
    
    Returns:
    
    true if the query is presorted.
  - presort
```
protected void presort()
```
    If the query is a presort query, then presort the results stored in the cursor. No-op for this implementation.
  - preselectResults
```
protected void preselectResults()
```
    Preselect all results by creating a common cursor and SimpleResults for each component.
  - loadRowAtCursor
```
protected void loadRowAtCursor()
```
    Synchronize the query with the cursor by causing the query to load the current row's results (if any) into its backing buffer(s).
    
    Overrides:
    
    loadRowAtCursor in class AbstractQuery
  - loadByValues
```
protected boolean loadByValues(java.lang.Object[] data,
                               LockType lockType,
                               boolean iterating)
```
    Load a virtual, composite record by loading each record buffer managed by this query with a DMO, given its primary key ID in the specified ids array. The IDs are arranged to coincide with the tables underlying the query, from left-most to right-most (in the sense of how they are joined by the query).
    
    Parameters:
    
    data - Array of primary key IDs or DMOs, one per table involved in the query
    
    lockType - Lock type which should override that of any underlying query. Set to null to allow underlying query to use its existing lock type.
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    Returns:
    
    true if ids was not null; else false.
    
    See Also:
    
    collectRowData(int)
  - canOptimize
```
protected boolean canOptimize()
```
    Indicate whether this object can be optimized.
    
    Returns:
    
    true by default. Subclasses should override this behavior as needed.
  - registerRecordChangeListeners
```
private boolean registerRecordChangeListeners()
```
    Register the query within each component as a record change listener.
    
    Returns:
    
    true if the global scope is used for registration.
  - maybeOptimize
```
private void maybeOptimize()
```
    Method which attempts to optimize this object's query components into one or more server-side joins. Returns immediately if this is not the first attempt to do so.
    This method must only be invoked after the first query result is fetched via the un-optimized query, to ensure we correctly preserve the pre-query state of the involved record buffers, in the event the compound query runs off end immediately.
  - getRecordBuffersInternal
```
private RecordBuffer[] getRecordBuffersInternal()
```
    Get an array of all record buffers managed by this query.
    
    Returns:
    
    All record buffers managed by this query.
  - setComponentsBrowsed
```
private void setComponentsBrowsed()
```
    Iterate the component queries of this object and set their browsed flags to match that of this object.
  - collectRowData
```
private java.lang.Object[] collectRowData(int navigation)
```
    Assemble an array of primary key IDs or DMOs for the current records in the buffers underlying this query, from left-most to right-most (in the sense of how the query joins the associated tables). This method essentially takes a lightweight snapshot of the currently loaded records, so that this may be restored later.
    This snapshot is only generated for scrolling queries.
    
    Parameters:
    
    navigation - Type of advancement applied to the compound query; i.e., how the virtual composite result set is navigated as a whole: forward (next), backward (previous), jump to first or last, or reload current records in all buffers.
    
    Returns:
    
    Array of primary key IDs or DMOs, one per table involved in the query.
    
    See Also:
    
    loadByValues(java.lang.Object[], com.goldencode.p2j.persist.lock.LockType, boolean)
  - retrieveImpl
```
private java.lang.Object[] retrieveImpl(int navigation,
                                        LockType lockType,
                                        boolean iterating,
                                        boolean peek)
```
    Retrieve a virtual, composite row of results for the compound query. This method implements a client-side join of multiple, single-row record retrievals performed by the underlying, component queries. It works first from outermost component inward, retrieving a record at each level. When each component's backing buffer contains a record, the composite retrieval is complete and the method returns. On subsequent iterations, the innermost component is advanced first. If no more matches are possible at this level, the algorithm moves outward one level and attempts to advance that level. On success, it moves inward again, on failure, it moves outward again. This continues until either a new composite row of results is assembled, or no further records can be found. This progression ensures that each inner query cycles through all of its matches before the next outer query advances.
    
    Parameters:
    
    navigation - Type of advancement applied to the compound query; i.e., how the virtual composite result set is navigated as a whole: forward (next), backward (previous), jump to first or last, or reload current records in all buffers.
    
    lockType - Overriding lock type to apply to each underlying buffer.
    
    iterating - true if this method is being invoked within the context of an iterating loop, which can only be exited by raising an end condition; false if end condition should not be raised, even if no further advancement of the composite result is possible.
    
    peek - true if sub-queries should be interrogated using Scrollable.peekNext()/Scrollable.peekPrevious() rather than P2JQuery.next()/P2JQuery.previous(). The difference is that in the first case sub-queries return the next/previous record from underlying results, while in the second case they return the next/previous record after the current row.
    
    Returns:
    
    An array of the primary key IDs for every table involved in the query, (which together identify a unique, virtual record), if a result row was successfully retrieved; null if no more results were available (and we were not iterating).
    
    Throws:
    
    QueryOffEndException - if no more results were available in iterating mode.
    
    ErrorConditionException - if an error occurred retrieving the record for an underlying query.
  - postponeAccumulation
```
protected void postponeAccumulation()
```
    Switch on postponed accumulation on next retrieve.
  - restoreAccumulation
```
protected void restoreAccumulation()
```
    Switch on postponed accumulation on next retrieve.
  - releaseAllBuffers
```
protected void releaseAllBuffers()
```
    Release all backing buffers of for all components.
  - addCompoundComponent
```
void addCompoundComponent(CompoundComponent component)
```
    Add a component query to this compound query and adjust the table count accordingly.
    
    Parameters:
    
    component - Query component to be added.
  - getOriginalComponents
```
java.util.ArrayList<CompoundComponent> getOriginalComponents()
```
    Retrieve the list of original query components (unoptimized).
    
    Returns:
    
    See above.
  - getComponents
```
private java.util.ArrayList<CompoundComponent> getComponents()
```
    Retrieve the list of query components. Depending on when this is called (before or after optimization), it may return the list of original, unoptimized components, or the list of optimized components.
    
    Returns:
    
    See above.
  - initializeComponentQuery
```
private void initializeComponentQuery(Joinable query)
```
    Initialize state of a component query.
    
    Parameters:
    
    query - Component query to be initialized.
  - processComponent
```
private java.lang.Object[] processComponent(int navigation,
                                            CompoundComponent component,
                                            int count,
                                            LockType lockType,
                                            boolean peek)
```
    Advance a single query component, according to the overall query navigation direction, and that component's natural iteration type. It is the intersection of these two criteria which determines the actual type of retrieval which is performed.
    
    Parameters:
    
    navigation - Type of advancement applied to the compound query; i.e., how the virtual composite result set is navigated as a whole: forward (next), backward (previous), jump to first or last, or reload current records in all buffers.
    
    component - Query component being asked to retrieve a record.
    
    count - Index of this query component's result within the current join.
    
    lockType - Lock type to apply to the retrieved record for this query component
    
    peek - true if sub-queries should be interrogated using Scrollable.peekNext()/Scrollable.peekPrevious() rather than P2JQuery.next()/P2JQuery.previous(). The difference is that in the first case sub-queries return the next/previous record from underlying results, while in the second case they return the next/previous record after the current row. Peeking works only for NEXT and PREV iteration types.
    
    Returns:
    
    If peek is true: an array of the primary key IDs for the query component, if a result was successfully retrieved; null if no more results were available.
    If peek is false: always returns null.
    
    Throws:
    
    QueryOffEndException - if query component is being asked to retrieve a FIRST, LAST, or UNIQUE record, and it has already done so in the current iteration pass (prevents looping infinitely on these constructs).
    
    See Also:
    
    QueryConstants.RETRIEVE_MODES
  - translateWhere
```
private void translateWhere()
```
    Translate the WHERE clause for all components.
    This is done only once.
  - releaseBuffers
```
public void releaseBuffers()
```
    Releases buffers from all components. The row position is not affected.
    
    Specified by:
    
    releaseBuffers in interface P2JQuery
    
    Overrides:
    
    releaseBuffers in class AbstractQuery
  - addDynamicFilter
```
public boolean addDynamicFilter(FieldReference fr,
                                BaseDataType val,
                                java.lang.String format)
```
    Adds a new constraint term to the where predicate of this query, effectively filtering out any rows whose referenced field does not match the requested value. Semantically, the query will select rows that match
    new-where := (fr = val) AND (old-query).
    Note: The constraints are exclusive meaning that if constraints will be added for same field of same buffer, the query will return an empty result because the field cannot be at the same time equals to two different values.
    Use clearDynamicFilters() to clean all dynamically added criteria and restore the sorting order of the query to its original form.
    
    Specified by:
    
    addDynamicFilter in interface P2JQuery
    
    Parameters:
    
    fr - A reference to field used as filtering criterion. Only the rows that matches the specified value for this field will be selected. Must not be null.
    
    val - The filtering value for this constraint. Can be null or unknown, in which case the SQL null value will be assumed. In this case the predicate will look like:
    new-where := (fr IS NULL) AND (old-query)
    
    format - The format to be used when comparing values. The reason for this parameter is that for some datatype (ex: decimal) the on-screen value can be different from the database (because of rounding).
    
    Returns:
    
    true if the filtering constraint was successfully added. If the field reference is not related to the buffer(s) of this query, false is returned.
  - clearDynamicFilters
```
public void clearDynamicFilters()
```
    Clears any dynamically filters added at runtime. The query predicate will be restored to its form from generated at conversion time.
    
    Specified by:
    
    clearDynamicFilters in interface P2JQuery

Class CompoundQuery

Nested Class Summary

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

Field Summary

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

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

Fields inherited from interface com.goldencode.p2j.persist.QueryConstants

Constructor Summary

Method Summary

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

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

Methods inherited from class java.lang.Object

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

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

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

Field Detail

log

deferOptimization

currentRowDeleted

foundFirst

unregisterOnCleanup

preselect

originalComponents

resolveOnce

components

preselected

counters

useSnapshot

activeIndex

tableCount

postponeAccumulation

buffersMap

regCleaner

forceFullResults

cleaner

whereTranslated

Constructor Detail

CompoundQuery

Method Detail

clearResults

initialize

initialize2f

setScrolling

getTableCount

getOffEndListeners

hintFullResults

addComponent

addComponent

addComponent

addExternalBuffers

setSkipDeletedRecord

setBrowsed

open

iterate

first

first

first

first

last

last

last

last

next

next

next

next

previous

previous

previous

previous

current

current

peekFirst

peekLast

peekNext

peekPrevious

notifyRepositionListeners

recordBuffers

stateChanged

setStandalone