FWD » Core Development » Database

/*

** Module   : RandomAccessQuery.java

** Abstract : Backing query for converted queries which require dynamic record retrieval

**

** Copyright (c) 2004-2020, Golden Code Development Corporation.

**

** -#- -I- --Date-- --JPRM-- --------------------------Description-------------------------------

** 001 ECF 20051007   @23259 Created initial version. Backing query for

**                           converted queries which require a dynamic

**                           record retrieval semantic.

** 002 ECF 20051111   @23386 Adapted to use with CompoundQuery. Implements

**                           Joinable, which is used by CompoundQuery when

**                           adding query components.

** 003 ECF 20051129   @23574 Added lenient-off-end mode. When in this

**                           mode, QueryOffEndExceptions thrown by the

**                           underlying buffer during next and previous

**                           operations are suppressed.

** 004 ECF 20051216   @23747 Added scrolling support. Now extends the new

**                           DynamicQuery base class, which provides

**                           cursoring support services. Modified

**                           retrieval logic to allow for repositioning.

** 005 ECF 20060104   @23828 Added accumulation support. Record retrieval

**                           methods first, last, next, and previous now

**                           update any registered accumulators after

**                           successfully retrieving a record.

** 006 GES 20060202   @24226 Removed main().

** 007 ECF 20060202   @24355 Added temp table support. Add buffer's

**                           multiplex ID as a query substitution argument

**                           for temp table queries.

** 008 ECF 20060208   @24365 Changed arguments processing in constructor.

**                           Store duplicates of BaseDataType arguments

**                           rather than references to the original

**                           objects.

** 009 ECF 20060215   @24723 Added support for client-side where clause

**                           processing. Major changes to execute() were

**                           necessary to support this. All constructors

**                           now accept an optional WhereExpression

**                           parameter. Also improved handling of query

**                           substitution parameter resolution to be more

**                           correct.

** 010 ECF 20060302   @25023 Add support for foreign key joins. Added new

**                           constructor variants which mirror existing

**                           constructors, but accept an additional,

**                           inverse DMO parameter. Modified query

**                           execution to integrate natural joins.

** 011 ECF 20060317   @25171 Fixed defect related to extent fields. Use

**                           mapping of query substitution parameters,

**                           which may have been reordered during HQL

**                           where clause preprocessing.

** 012 ECF 20060330   @25256 Removed final modifier from class. FindQuery

**                           extends this class.

** 013 ECF 20060424   @25696 Added new constructor variants. Each existing

**                           variant now has a counterpart which does not

**                           expect a WhereExpression parameter.

** 014 ECF 20060424   @25700 Roll back previous change.

** 015 ECF 20060529   @26645 Added initializeBuffer method. Resets buffer

**                           during query construction.

** 016 ECF 20060531   @26851 Replaced EndConditionException with

**                           QueryOffEndException. The latter is a more

**                           specific version of the former, used to

**                           indicate a query has run off the end of its

**                           result set.

** 017 ECF 20060610   @27102 Fixed lock processing defect. A record must

**                           not be stored in the buffer after a NO-WAIT

**                           record lock attempt fails.

** 018 ECF 20060621   @27506 Logging improvements.

** 019 ECF 20060713   @28046 Use new DBUtils class.

** 020 ECF 20060720   @28118 Minor changes driven by RecordBuffer naming

**                           changes. RecordBuffer.getLatestRecord() was

**                           changed to getSnapshot().

** 021 ECF 20060728   @28272 Minor change to accommodate RecordBuffer

**                           changes. Enclose RecordBuffer.setTempRecord()

**                           call in a try-catch block.

** 022 ECF 20060802   @28353 Added break value support. Implemented new

**                           getBreakValue() method.

** 023 ECF 20060803   @28404 Added updateBuffer() method. Allows

**                           subclasses to override setting current record

**                           into buffer.

** 024 ECF 20060925   @29964 Check for a pending error before retrieving a

**                           record. Retrieval is not attempted if an

**                           error is pending in the ErrorManager.

** 025 ECF 20061003   @30155 Call prepareFetch() instead of obsolete

**                           method checkPendingError(). Implemented

**                           releaseBuffers() to override do-nothing

**                           AbstractQuery implementation.

** 026 ECF 20061019   @30530 Changed reset() method. If the query is in

**                           scrolling mode, the cursor is reset as part

**                           of this method's processing.

** 027 ECF 20061023   @30609 Moved errorIfNull logic to AbstractQuery base

**                           class. Method setErrorIfNull() is now

**                           required by the P2JQuery interface and is

**                           implemented in AbstractQuery instead of here.

** 028 ECF 20061027   @30755 Replaced Object with DataModelObject for DMO

**                           arguments to methods/constructors. Required

**                           for compile-time type safety.

** 029 ECF 20061115   @31210 Changed call to set current buffer record.

**                           RecordBuffer API has changed to permit proper

**                           management of placeholder snapshot record.

**                           Added isResetSnapshot() method to allow

**                           subclasses to override this behavior.

** 030 ECF 20070216   @32165 Explicitly set errorIfNull to false. This is

**                           required to override the default setting of

**                           true made by AbstractQuery.

** 031 ECF 20070228   @32248 Optimized no-lock and temp table fetches. In

**                           these cases, it is not necessary to fetch the

**                           record in two steps. The no-lock case makes

**                           no guarantee that the record in memory has

**                           not been updated by other sessions. The temp

**                           table case guarantees that no other session

**                           can make an update to the record in memory,

**                           because a temp table record is inherently

**                           scoped to a session.

** 032 ECF 20070308   @32335 Fixed behavior for first/last. Upon failure

**                           to find a record, if not in looping mode,

**                           these methods must report a 'FIND FIRST/LAST

**                           failed...' message.

** 033 ECF 20070412   @32985 Retrofit to use RecordLockContext for record

**                           locking. Accommodate method name change in

**                           RecordBuffer: setCurrentRecord --> setRecord.

** 034 ECF 20070416   @33028 Integrated user interrupt handling.

** 035 ECF 20070504   @33410 Retrofitted load() method to use modified

**                           signature specified by Joinable.

** 036 ECF 20070508   @33460 Fixed executeImpl() to properly handle a

**                           validation exception. New requirement based

**                           on a change to RecordBuffer.flush().

** 037 ECF 20070518   @33684 Added getRecordBuffers() and recordBuffers().

**                           The former is required by the Joinable

**                           interface. The latter is required by the

**                           RecordChangeListener interface.

** 038 EVL 20070609   @34005 Adding explicit import of the class

**                           org.hibernate.type.Type to eliminate conflict

**                           with the same class from java.lang.reflect

**                           package to be able to compile for Java 6.

** 039 ECF 20070718   @34571 Fixed findNext()/findPrevious() and their

**                           callers. These methods were not properly

**                           updating locks when necessary.

** 040 ECF 20070713   @34858 Moved all CAN-FIND specific processing to the

**                           FindQuery subclass. Exposed some private

**                           methods as protected and refactored class to

**                           support this.

** 041 ECF 20070827   @35002 Minor optimization for temp table queries.

**                           Omit multiplex ID from query substitution

**                           parameters. HQLHelper now hard-codes the ID

**                           into the where clause, since it is known at

**                           the time the where clause is generated.

** 042 ECF 20070926   @35246 Fix placeholder record defect. In cases where

**                           the referenceRecord DMO is modified, we need

**                           to null it out and use the buffer's current

**                           snapshot as our placeholder record instead.

** 043 ECF 20071130   @36123 Removed isRefreshSnapshot() method. The

**                           RecordBuffer placeholder snapshot is no

**                           longer cleared by any query type when the

**                           query does not find a record to place in the

**                           buffer. Integrated generics.

** 044 ECF 20071204   @36266 Fixed off-end tracking. Replaced boolean flag

**                           with OffEnd enum to discern between off-end

**                           directions (i.e., off back vs off front of

**                           result set). Current off-end status and

**                           active sort index are reported to the record

**                           buffer when fetching a record. Off-end status

**                           is checked when searching for a new record.

** 045 ECF 20080112   @37006 Removed restriction of dealing only with IDs.

**                           This query can now handle both Persistables

**                           and primary key IDs when retrieving data.

**                           This is necessary when the full record is

**                           needed immediately, not just an ID, such as

**                           in presort cases.

** 046 CA  20080311   @37430 Removed the listener code from c'tor and

**                           added it to the new registerChangeListener()

**                           method.

** 047 ECF 20080310   @37482 Made changes necessary to support embedded,

**                           H2 database.

** 048 SVL 20080418   @38041 Added support for the inverse sorting.

** 049 SVL 20080421   @38082 Added support for legacy key join helper.

** 050 ECF 20080508   @38245 Override base lock type for temporary tables.

**                           This allows some downstream optimizations.

** 051 ECF 20080510   @38610 Implemented support for dirty database

**                           checking. Looks into a shared database of

**                           uncommitted updates and possibly overrides

**                           data found in primary database.

** 052 ECF 20080609   @38652 Removed overly aggressive optimization in

**                           executeImpl(). Queries with non-NO-LOCK types

**                           must also search among uncommitted updates,

**                           and locks must be acquired on dirty records.

** 053 ECF 20080610   @38690 Fixed dirty check processing in executeImpl()

**                           method. We were not correctly handling the

**                           case of finding a dirty version of the same

**                           DMO found in the primary database.

** 054 ECF 20080611   @38712 Fixed processResults(). When acquiring a lock

**                           for a dirty record, the record should be

**                           reloaded, in case it disappeared while we

**                           were waiting on the lock.

** 055 CA  20080618   @38868 When the JOINed foreign buffer does not refer

**                           any record, the query must return no result

**                           as it can not be executed.

** 056 SVL 20080630   @38985 Fixed executeImpl() for the case when a dirty

**                           record is inserted and modified.

** 057 SVL 20080730   @39222 Added dmoSorter instance variable.

** 058 CA  20080815   @39465 Support API change in DBUtils.

** 060 ECF 20081009   @40082 Integrated new support for inlining query

**                           substitution parameters. Queries supported by

**                           this class don't actually have their

**                           parameters inlined, but changes were needed

**                           to integrate HQLPreprocessor API changes and

**                           the ParameterIndices class.

** 061 ECF 20081105   @40312 Implemented registerRecordChangeListeners().

**                           Required by the Joinable interface.

** 062 ECF 20081215   @40917 Modified executeImpl(). A validation error

**                           ignores silent error mode, since the flushing

**                           of the previous record in the buffer is not

**                           masked by silent error mode.

** 063 ECF 20090303   @41599 Fixed to better support being a Joinable

**                           component of a CompoundQuery. Implemented

**                           RecordChangeListener, added getOffEnd()

**                           method. Replaced activeBundleKey Object with

**                           an int to support changes in HQLHelper.

** 064 ECF 20090317   @41627 Removed early calls to getHelper(). This

**                           method must not be invoked until the query is

**                           actually being executed, because of possible

**                           dependencies in HQLHelper.obtain() on the

**                           state of the query's substitution parameters.

**                           Specifically, a FieldReference parameter may

**                           not be backed by a record if this method is

**                           invoked arbitrarily early.

** 065 ECF 20090512   @42154 Modified prepareBuffer(). Now invokes flushAll()

**                           instead of flush() on backing buffer. This

**                           ensures all like buffers are allowed to flush

**                           their transient records properly.

** 066 ECF 20090603   @42596 Added support for Progress isolation leak quirk.

**                           Modified executeImpl() and processResults() to

**                           use new features in HQLPreprocessor and in

**                           DirtyShareContext to leak uncommitted changes to

**                           other sessions and to select appropriate record.

** 067 ECF 20090609   @42635 Fixed executeImpl(). We now evict, if possible,

**                           those DMOs read into the Hibernate Session, but

**                           not loaded into the record buffer. This includes

**                           DMOs whose uncommitted changes are leaked to

**                           other sessions early, and DMOs which are found in

**                           the primary database, but overridden by records

**                           found by the dirty share manager.

** 068 ECF 20090623   @42941 Fixed executeImpl(). Handle the case of a unique

**                           search finding information in the dirty database.

**                           Also added back multiplex ID as a substitution

**                           parameter for temp table queries.

** 069 ECF 20090703   @43058 Reimplemented load() method. This method now sets

**                           the backing buffer to unknown mode and throws

**                           MissingRecordException if a target record cannot

**                           be loaded.

** 070 ECF 20090716   @43221 Enabled lazy record buffer initialization. Added

**                           RecordBuffer.initialize() call in c'tor.

** 071 ECF 20090724   @43421 Added implicit transaction support. In various

**                           methods which execute queries, we push/pop an

**                           implicit transaction.

** 072 CA  20090731   @43470 Register the query for off-end listener 

**                           registration after block initialization (done

**                           only for block types FOR and FOR EACH). Added

**                           getOffEndListeners, which returns a list of all

**                           off-end listeners for all used buffers.

** 073 SVL 20091030   @44293 getOffEnd() function was made public in order to

**                           support API change into P2JQuery. 

** 074 OM  20130829          Added change detection to buffer on current() methods.

**                           Updated calls to match the new Persistence.load() signatures.

** 075 ECF 20131028          Import change.

** 076 OM  20140107          Added TODO for missing fatal error message.

** 077 SVL 20140604          Added support for index information field.

** 078 ECF 20140814          Replaced RecordBuffer.flushAll with flush in prepareBuffer method.

**                           Fixed dirty share logic to work with new flush/validate algorithm.

**                           Replaced Apache commons logging with J2SE logging.

** 079 OM  20150507          Removed listener from global scope of ChangeBroker.

** 080 ECF 20150801          Implemented new Joinable methods necessary for compound query

**                           optimization. Error message fix. Enabled database statistics.

** 081 ECF 20150906          Reimplemented silent error mode processing of query substitution

**                           parameters. Fixed NPE related to outer joins.

** 082 SVL 20151112          Continue normally if reposition failed in load().

** 083 EVL 20160223          Javadoc fixes to make compatible with Oracle Java 8 for Solaris 10.

** 084 SVL 20160314          Added setter for referenceRecord.

** 085 OM  20160316          Signature of DirtyShareContext.getDirtyInfo() has changed.

**     ECF 20160504          Pass new parameter to Persistence.load. Minor change to isIdOnly.

** 086 SVL 20160608          The query can handle null IDs (for scrolling compound queries

**                           with OUTER join).

** 087 ECF 20160615          Bias toward fetching full records when possible.

** 088 IAS 20160701          Fixed legacy name in the [565] error message.

** 089 IAS 20160714          Use legacy name instead of DMO alias.

** 090 OM  20160715          Added support for template records.

**                           Persistence.popImplicitTransaction() changed signature.

** 091 ECF 20160725          Fixed buffer lookup during HQL preprocessing.

** 092 ECF 20160823          Improved executeImpl to better detect missing records and avoid

**                           deadlock.

** 093 ECF 20160901          DirtyShareContext.isDirtyDelete signature change.

** 094 GES 20160804          Switched from WhereExpression to lambda usage.

**         20160919          All initialization is now done with a default constructor followed

**                           by a call to initialize(). This enables query instance members in

**                           converted code to be local variables that are effectively final.

**                           This is needed to support lambdas without moving queries to be

**                           instance members. Queries as instance members breaks recursion

**                           use cases.

** 095 CA  20161012          Fixed scope processing when the query is from a persistent 

**                           procedure, and is part of a QUERY resource.

** 096 ECF 20161014          Fixed implementation of current() method in the event there is no

**                           current record in the buffer to reload, and this is not considered

**                           an error in the context of the query (e.g., query represents an

**                           outer join and record can be null).

** 097 ECF 20171212          Reworked query substitution parameter error handling and error

**                           condition handling.

** 098 OM  20171129          releaseBuffers() is overwritten from P2JQuery.

**     ECF 20171217          Added workaround to executeImpl to avoid dirty share manager blowup,

**                           but this is not a long-term solution.

** 099 ECF 20180201          Removed initializeBuffer, which released the current record too

**                           aggressively.

** 100 OM  20180220          Fixed LEFT OUTER JOIN queries.

** 101 OM  20180321          Fixed NPE caused by a null substitution array.

** 102 ECF 20180418          Fixed sort clause generation in makeAdaptiveServerJoinComponent.

** 103 OM  20180515          Added dynamic filtering of results set.

** 104 OM  20180901          Improved dynamic filtering.

** 105 OM  20180918          Filtering is case insensitive and uses LIKE patterns.

**     OM  20180924          Filtering on decimal fields uses STRING(f, format) function.

** 106 OM  20181023          Added external buffers when making the adaptive server join

**                           components.

** 107 OM  20190330          Ignore close request when query not fully initialized.

** 108 ECF 20190813          Change to RecordBuffer.release and RecordBuffer.setRecord APIs.

** 109 SVL 20191002          Log if sort index was not found.

** 110 CA  20191005          A query must know if it is dynamic, when closing.

** 111 CA  20191009          Added where and sort clause translation in case of bound buffers.

** 112 CA  20200110          If the index is missing, assume the primary index (encountered when 

**                           the sort clause uses fields in a WORD index).

**     EVL 20200206          Adding NPE protection to initialize method.

** 113 ECF 20200419          Removed Hibernate dependencies.

*/

/*

** This program is free software: you can redistribute it and/or modify

** it under the terms of the GNU Affero General Public License as

** published by the Free Software Foundation, either version 3 of the

** License, or (at your option) any later version.

**

** This program is distributed in the hope that it will be useful,

** but WITHOUT ANY WARRANTY; without even the implied warranty of

** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

** GNU Affero General Public License for more details.

**

** You may find a copy of the GNU Affero GPL version 3 at the following

** location: https://www.gnu.org/licenses/agpl-3.0.en.html

** 

** Additional terms under GNU Affero GPL version 3 section 7:

** 

**   Under Section 7 of the GNU Affero GPL version 3, the following additional

**   terms apply to the works covered under the License.  These additional terms

**   are non-permissive additional terms allowed under Section 7 of the GNU

**   Affero GPL version 3 and may not be removed by you.

** 

**   0. Attribution Requirement.

** 

**     You must preserve all legal notices or author attributions in the covered

**     work or Appropriate Legal Notices displayed by works containing the covered

**     work.  You may not remove from the covered work any author or developer

**     credit already included within the covered work.

** 

**   1. No License To Use Trademarks.

** 

**     This license does not grant any license or rights to use the trademarks

**     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks

**     of Golden Code Development Corporation. You are not authorized to use the

**     name Golden Code, FWD, or the names of any author or contributor, for

**     publicity purposes without written authorization.

** 

**   2. No Misrepresentation of Affiliation.

** 

**     You may not represent yourself as Golden Code Development Corporation or FWD.

** 

**     You may not represent yourself for publicity purposes as associated with

**     Golden Code Development Corporation, FWD, or any author or contributor to

**     the covered work, without written authorization.

** 

**   3. No Misrepresentation of Source or Origin.

** 

**     You may not represent the covered work as solely your work.  All modified

**     versions of the covered work must be marked in a reasonable way to make it

**     clear that the modified work is not originating from Golden Code Development

**     Corporation or FWD.  All modified versions must contain the notices of

**     attribution required in this license.

*/

package com.goldencode.p2j.persist;

import java.io.*;

import java.lang.reflect.*;

import java.util.*;

import java.util.function.*;

import java.util.logging.*;

import com.goldencode.p2j.persist.dirty.*;

import com.goldencode.p2j.persist.event.*;

import com.goldencode.p2j.persist.lock.*;

import com.goldencode.p2j.security.*;

import com.goldencode.p2j.util.*;

import com.goldencode.p2j.util.LogHelper;

import com.goldencode.p2j.util.ErrorManager;

import com.goldencode.util.*;

/**

 * The backing query for converted queries which require a dynamic record

 * retrieval semantic.  This means that a single record is retrieved at a

 * time and the query manages state about that record's position relative

 * to others which also match the query's search criteria.  Furthermore,

 * any change to that record's data may change its position relative to other

 * matching records, and these changes must be supported while client code is

 * using the query to visit result records.  Client code can jump among

 * results randomly.  These moves are specified as either relative requests

 * (next, previous, current), or as absolute requests (first, last, unique).

 * <p>

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

 * <p>

 * 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

 * {@link HQLHelper} and {@link HQLBundle}.  The result of a record retrieval

 * is a Data Model Object (DMO), which is stored in a {@link RecordBuffer}.

 * A record buffer is associated with this object at construction.

 * <p>

 * Because of this implementation requirement, <code>RandomAccessQuery</code>

 * represents <i>an extremely inefficient mechanism</i> by which to query a

 * database for a set of records.  As such, <b>it should not be used for new

 * development;  it is intended only to support legacy, converted code</b>,

 * insofar as that code may rely on the dynamic nature of the Progress

 * semantic.

 * <p>

 * This class implements the <code>Joinable</code> interface so that it can

 * be added as a component to a {@link 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 {@link

 * #setErrorIfNull} with the parameter <code>true</code>.

 * <p>

 * When used to represent a Progress query (as created with DEFINE or OPEN

 * QUERY), {@link #setLenientOffEnd} must be set to <code>true</code>, which

 * suppresses end condition exceptions for <code>next</code> and

 * <code>previous</code> commands which run off the end of the query's

 * results.

 * <p>

 * <strong>Transaction Isolation (Dirty Reads)</strong>

 * <br>

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

 * <p>

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

 */

public class RandomAccessQuery

extends DynamicQuery

implements Joinable,

           QueryConstants,

           RecordChangeListener

{

   /** Logger */

   private static final Logger LOG = LogHelper.getLogger(RandomAccessQuery.class.getName());

   /** Template for "missing sort index" error message. */

   private static final String ERROR_LOCATE_SORT_INDEX = "Error locating index for sort phrase [%s]";

   /** Record buffer which backs this query */

   private RecordBuffer buffer;

   /** Helper object for dynamic join via a foreign key relation */

   private AbstractJoin join;

   /** Client-side where clause expression, if any */

   private Supplier<logical> whereExpr;

   /** Base substitution parameters for HQL queries before applying any dynamic filter. */

   private Object[] args;

   /** 

    * Base substitution parameters for HQL queries, including the dynamic filtering components,

    * if any.

    */

   private Object[] dfArgs;

   /** Lock type to apply to records retrieved */

   private LockType lockType;

   /** 

    * Original where clause (only stored until helper is built). It is only used for building the

    * {@code dfWhere} which also contains the information on eventual dynamic filters.

    */

   private String where = null;

   /**

    * Original where clause (only stored until helper is built), including the dynamic filtering

    * components, if any.

    */

   private String dfWhere = null;

   /** Original sort clause (only stored until helper is built) */

   private String sort = null;

   /** DMO sorter associated with query's sort clause */

   private DMOSorter dmoSorter = null;

   /** Name of index in use for this query */

   private String index = null;

   /** Index information string as it is returned by INDEX-INFORMATION. */

   private String indexInfo = null;

   /** Builds HQL statements for various Hibernate queries. */

   private HQLHelper helper = null;

   /** Cached helper for non-null arguments in left outer join queries. */

   private HQLHelper nonNullArgsHelper = null;

   /** HQL data necessary for the current query operation */

   private HQLBundle activeBundle = null;

   /** Key which indicates active bundle choice */

   private int activeBundleKey = NONE;

   /** {@code false} if running off end of results should raise error */

   private boolean lenientOffEnd = false;

   /** Substitution parameter values for the next query execution */

   private Object[] currentArgs = null;

   /** Record whose data defines current "place" in query results */

   private Record referenceRecord = null;

   /** Break value indicating a new sort band if non-<code>null</code> */

   private Object breakValue = null;

   /** Force query to retrieve full records, rather than primary keys only */

   private boolean fullRecords = false;

   /** Was last record found retrieved from the dirty database? */

   private boolean dirtyCopy = false;

   /** RecordChangeListener which nulls out placeholder reference record */

   private RecordChangeListener placeholderCleaner = null;

   /** Determines if this will be unregistered from ChangeBroker on cleanup. */

   private boolean unregisterOnCleanup = false;

   /**

    * The list of arguments for currently applied dynamic filters.

    * Note that its size may be smaller than the number of dynamic filters because the null /

    * unknown values were automatically converted to {@code is null} so they lack the argument.

    */

   private List<Object> dynamicFilterArgs = null;

   /**

    * The list of dynamic filters. These are filters added dynamically, at runtime and can also be

    * removed dynamically.

    */

   private Map<FieldReference, BaseDataType> dynamicFilters = null;

   /**

    * The list of format used by dynamic filters. These are filters added dynamically, at runtime

    * and can also be removed dynamically.

    */

   private Map<FieldReference, String> dynamicFormats = null;

   /** The static {@code ContextLocal} container for cache.  */

   private static final ContextLocal<HashMap<FastFindKey, Record>> ffContextCache = 

      new ContextLocal<HashMap<FastFindKey, Record>>() {

         @Override

         protected HashMap<FastFindKey, Record> initialValue() {

            // for the moment the cache is just a naive map

            return new HashMap<>();

         }

      };

   /** Is FastFind enabled? */

   private boolean ffEnable = true;

   /** The cached FastFind cache bounded to this context. */

   private final HashMap<FastFindKey, Record> ffCache = ffContextCache.get();

   /**

    * Default constructor. Initialization is deferred until <code>initialize()</code> is

    * called.

    */

   public RandomAccessQuery()

   {

   }

   /**

    * Initialization logic which defaults record lock type to <code>LockType.SHARE</code>.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    *            

    * @return   This query instance.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort)

   {

      return initialize(dmo, where, whereExpr, sort, null, null, null, LockType.SHARE);

   }

   /**

    * Initialization logic which defaults record lock type to <code>LockType.SHARE</code>.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    indexInfo

    *           Index information string as it is returned by INDEX-INFORMATION.

    *           May be <code>null</code> if it is not an OPEN QUERY case or if

    *           you don't need debug information about selected indexes.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    *            

    * @return   This query instance.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       String            indexInfo)

   {

      return initialize(dmo, where, whereExpr, sort, indexInfo, null, null, LockType.SHARE);

   }

   /**

    * Initialization logic which is used when joining to another table using a foreign

    * key.  Defaults record lock type to <code>LockType.SHARE</code>.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    inverse

    *           DMO to which this query should join via a foreign relation.

    *           May be <code>null</code>.

    *            

    * @return   This query instance.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       DataModelObject   inverse)

   {

      return initialize(dmo, where, whereExpr, sort, null, inverse, null, LockType.SHARE);

   }

   /**

    * Initialization logic which is used when joining to another table using a foreign

    * key.  Defaults record lock type to <code>LockType.SHARE</code>.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    indexInfo

    *           Index information string as it is returned by INDEX-INFORMATION.

    *           May be <code>null</code> if it is not an OPEN QUERY case or if

    *           you don't need debug information about selected indexes.

    * @param    inverse

    *           DMO to which this query should join via a foreign relation.

    *           May be <code>null</code>.

    *            

    * @return   This query instance.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       String            indexInfo,

                                       DataModelObject   inverse)

   {

      return initialize(dmo, where, whereExpr, sort, indexInfo, inverse, null, LockType.SHARE);

   }

   /**

    * Initialization logic which defaults record lock type to

    * <code>LockType.SHARE</code> and accepts default substitution parameters.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    args

    *           Substitution parameters for HQL queries.  These will be used

    *           if not overridden by a record retrieval method.

    *            

    * @return   This query instance.

    *           

    * @throws   IllegalArgumentException

    *           if any substitution argument provided is not of a supported

    *           type.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       Object[]          args)

   {

      return initialize(dmo, where, whereExpr, sort, null, null, args, LockType.SHARE);

   }

   /**

    * Initialization logic which defaults record lock type to

    * <code>LockType.SHARE</code> and accepts default substitution parameters.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    indexInfo

    *           Index information string as it is returned by INDEX-INFORMATION.

    *           May be <code>null</code> if it is not an OPEN QUERY case or if

    *           you don't need debug information about selected indexes.

    * @param    args

    *           Substitution parameters for HQL queries.  These will be used

    *           if not overridden by a record retrieval method.

    *            

    * @return   This query instance.

    *           

    * @throws   IllegalArgumentException

    *           if any substitution argument provided is not of a supported

    *           type.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       String            indexInfo,

                                       Object[]          args)

   {

      return initialize(dmo, where, whereExpr, sort, indexInfo, null, args, LockType.SHARE);

   }

   /**

    * Initialization logic which is used when joining to another table using a foreign

    * key.  Defaults record lock type to <code>LockType.SHARE</code> and

    * accepts default substitution parameters.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    inverse

    *           DMO to which this query should join via a foreign relation.

    *           May be <code>null</code>.

    * @param    args

    *           Substitution parameters for HQL queries.  These will be used

    *           if not overridden by a record retrieval method.

    *            

    * @return   This query instance.

    *           

    * @throws   IllegalArgumentException

    *           if any substitution argument provided is not of a supported

    *           type.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       DataModelObject   inverse,

                                       Object[]          args)

   {

      return initialize(dmo, where, whereExpr, sort, null, inverse, args, LockType.SHARE);

   }

   /**

    * Initialization logic which is used when joining to another table using a foreign

    * key.  Defaults record lock type to <code>LockType.SHARE</code> and

    * accepts default substitution parameters.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    indexInfo

    *           Index information string as it is returned by INDEX-INFORMATION.

    *           May be <code>null</code> if it is not an OPEN QUERY case or if

    *           you don't need debug information about selected indexes.

    * @param    inverse

    *           DMO to which this query should join via a foreign relation.

    *           May be <code>null</code>.

    * @param    args

    *           Substitution parameters for HQL queries.  These will be used

    *           if not overridden by a record retrieval method.

    *            

    * @return   This query instance.

    *           

    * @throws   IllegalArgumentException

    *           if any substitution argument provided is not of a supported

    *           type.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       String            indexInfo,

                                       DataModelObject   inverse,

                                       Object[]          args)

   {

      return initialize(dmo, where, whereExpr, sort, indexInfo, inverse, args, LockType.SHARE);

   }

   /**

    * Initialization logic which sets an explicit, default, record lock type.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    lockType

    *           Lock type to apply to records retrieved, if not overridden by

    *           a record retrieval method.

    *            

    * @return   This query instance.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       LockType          lockType)

   {

      return initialize(dmo, where, whereExpr, sort, null, null, null, lockType);

   }

   /**

    * Initialization logic which sets an explicit, default, record lock type.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    indexInfo

    *           Index information string as it is returned by INDEX-INFORMATION.

    *           May be <code>null</code> if it is not an OPEN QUERY case or if

    *           you don't need debug information about selected indexes.

    * @param    lockType

    *           Lock type to apply to records retrieved, if not overridden by

    *           a record retrieval method.

    *            

    * @return   This query instance.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       String            indexInfo,

                                       LockType          lockType)

   {

      return initialize(dmo, where, whereExpr, sort, indexInfo, null, null, lockType);

   }

   /**

    * Initialization logic which is used when joining to another table using a foreign

    * key.  Sets an explicit, default, record lock type.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    inverse

    *           DMO to which this query should join via a foreign relation.

    *           May be <code>null</code>.

    * @param    lockType

    *           Lock type to apply to records retrieved, if not overridden by

    *           a record retrieval method.

    *            

    * @return   This query instance.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       DataModelObject   inverse,

                                       LockType          lockType)

   {

      return initialize(dmo, where, whereExpr, sort, null, inverse, null, lockType);

   }

   /**

    * Initialization logic which is used when joining to another table using a foreign

    * key.  Sets an explicit, default, record lock type.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    indexInfo

    *           Index information string as it is returned by INDEX-INFORMATION.

    *           May be <code>null</code> if it is not an OPEN QUERY case or if

    *           you don't need debug information about selected indexes.

    * @param    inverse

    *           DMO to which this query should join via a foreign relation.

    *           May be <code>null</code>.

    * @param    lockType

    *           Lock type to apply to records retrieved, if not overridden by

    *           a record retrieval method.

    *            

    * @return   This query instance.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       String            indexInfo,

                                       DataModelObject   inverse,

                                       LockType          lockType)

   {

      return initialize(dmo, where, whereExpr, sort, indexInfo, inverse, null, lockType);

   }

   /**

    * Initialization logic which sets an explicit, default, record lock type and

    * accepts default substitution parameters.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    args

    *           Substitution parameters for HQL queries.  These will be used

    *           if not overridden by a record retrieval method.

    * @param    lockType

    *           Lock type to apply to records retrieved, if not overridden by

    *           a record retrieval method.

    *            

    * @return   This query instance.

    *

    * @throws   IllegalArgumentException

    *           if any substitution argument provided is not of a supported

    *           type.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       Object[]          args,

                                       LockType          lockType)

   {

      return initialize(dmo, where, whereExpr, sort, null, null, args, lockType);

   }

   /**

    * Initialization logic which sets an explicit, default, record lock type and

    * accepts default substitution parameters.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    indexInfo

    *           Index information string as it is returned by INDEX-INFORMATION.

    *           May be <code>null</code> if it is not an OPEN QUERY case or if

    *           you don't need debug information about selected indexes.

    * @param    args

    *           Substitution parameters for HQL queries.  These will be used

    *           if not overridden by a record retrieval method.

    * @param    lockType

    *           Lock type to apply to records retrieved, if not overridden by

    *           a record retrieval method.

    *            

    * @return   This query instance.

    *

    * @throws   IllegalArgumentException

    *           if any substitution argument provided is not of a supported

    *           type.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       String            indexInfo,

                                       Object[]          args,

                                       LockType          lockType)

   {

      return initialize(dmo, where, whereExpr, sort, indexInfo, null, args, lockType);

   }

   /**

    * Initialization logic which is used when joining to another table using a foreign

    * key.  Sets an explicit, default, record lock type and accepts default

    * substitution parameters.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    inverse

    *           DMO to which this query should join via a foreign relation.

    *           May be <code>null</code>.

    * @param    args

    *           Substitution parameters for HQL queries.  These will be used

    *           if not overridden by a record retrieval method.

    * @param    lockType

    *           Lock type to apply to records retrieved, if not overridden by

    *           a record retrieval method.

    *            

    * @return   This query instance.

    *

    * @throws   IllegalArgumentException

    *           if any substitution argument provided is not of a supported

    *           type.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       DataModelObject   inverse,

                                       Object[]          args,

                                       LockType          lockType)

   {

      return initialize(dmo, where, whereExpr, sort, null, inverse, args, lockType);

   }

   /**

    * Initialization logic which is used when joining to another table using a foreign

    * key.  Sets an explicit, default, record lock type and accepts default

    * substitution parameters.

    * <p>

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

    *

    * @param    dmo

    *           Data model object which determines the record buffer into which

    *           records are retrieved.

    * @param    where

    *           Where clause, using HQL syntax.  May be <code>null</code>.

    * @param    whereExpr

    *           Client-side where clause expression.  May be <code>null</code>.

    * @param    sort

    *           Order by clause, using HQL syntax.  May be <code>null</code>

    *           only if query is to be navigated only using one of the

    *           <code>unique</code> method variants.

    * @param    indexInfo

    *           Index information string as it is returned by INDEX-INFORMATION.

    *           May be <code>null</code> if it is not an OPEN QUERY case or if

    *           you don't need debug information about selected indexes.

    * @param    inverse

    *           DMO to which this query should join via a foreign relation.

    *           May be <code>null</code>.

    * @param    args

    *           Substitution parameters for HQL queries.  These will be used

    *           if not overridden by a record retrieval method.

    * @param    lockType

    *           Lock type to apply to records retrieved, if not overridden by

    *           a record retrieval method.

    *            

    * @return   This query instance.

    *

    * @throws   IllegalArgumentException

    *           if any substitution argument provided is not of a supported

    *           type.

    */

   public RandomAccessQuery initialize(DataModelObject   dmo,

                                       String            where,

                                       Supplier<logical> whereExpr,

                                       String            sort,

                                       String            indexInfo,

                                       DataModelObject   inverse,

                                       Object[]          args,

                                       LockType          lockType)

   {

      this.buffer = ((BufferReference) dmo).buffer();

      RecordBuffer defBuffer = ((BufferReference) dmo).definition();

      if (!buffersMatch(buffer, defBuffer))

      {

         sort = translateSort(buffer, defBuffer, sort);

         ArrayList<RecordBuffer> binding = new ArrayList<>();

         binding.add(buffer);

         ArrayList<RecordBuffer> definition = new ArrayList<>();

         definition.add(defBuffer);

         where = translateWhere(binding, definition, where);

      }

      boolean abort = false;

      if (!AbstractQuery.preprocessSubstitutionArguments(buffer.getBufferManager(), args))

      {

         setFatalError();

         abort = true;

      }

      if (buffer.isReadonly())

      {

         // TODO: readonly buffers cannot be used in any FIND statement

         //       but can be used in CAN-FIND functions

      }

      buffer.initialize();

      if (buffer.getDirtyContext() != null)

      {

         // Get index name, which is needed for dirty checking work.

         try

         {

            IndexHelper indexHelper = buffer.getIndexHelper();

            this.index = indexHelper.getIndexForSort(buffer, sort);

            if (index == null)

            {

               P2JIndex p2JavaIndex = indexHelper.getPrimaryIndex(

                                           buffer.getDMOImplementationClass().getCanonicalName());

               if (p2JavaIndex != null)

               {

                  index = p2JavaIndex.getName();

               }

            }

            this.dmoSorter = indexHelper.getSorterForSortPhrase(buffer, sort);

         }

         catch (PersistenceException exc)

         {

            if (LOG.isLoggable(Level.SEVERE))

            {

               LOG.log(Level.SEVERE, String.format(ERROR_LOCATE_SORT_INDEX, sort), exc);

            }

         }

         if (index == null && LOG.isLoggable(Level.SEVERE))

         {

            LOG.log(Level.SEVERE, String.format(ERROR_LOCATE_SORT_INDEX, sort));

         }

      }

      if (inverse != null)

      {

         if (Persistence.isForeignKeysEnabled())

         {

            join = new DynamicJoin(buffer, ((BufferReference) inverse).buffer());

         }

         else

         {

            join = new DynamicLegacyKeyJoin(buffer, ((BufferReference) inverse).buffer());

         }

      }

      else

      {

         join = null;

      }

      this.where = where;

      this.dfWhere = where;

      this.sort = sort;

      this.whereExpr = whereExpr;

      this.args = args;

      this.dfArgs = args;

      this.indexInfo = indexInfo;

      // override lock type if this is a temporary buffer;  this allows some downstream optimizations

      this.lockType = (buffer.isTemporary() ? LockType.NONE : lockType);