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

java.lang.Object
- com.goldencode.p2j.persist.FQLPreprocessor

All Implemented Interfaces:

HQLParserTokenTypes
```
public final class FQLPreprocessor
extends java.lang.Object
implements HQLParserTokenTypes
```
A preprocessor for where clauses written in FQL (extension of HQL). It performs the following functions:
- Handles references to text properties in a dialect-specific manner. In cases where functions are usable within index definitions, encloses each qualified reference to a text value within a SQL RTRIM function, so that trailing whitespace (specifically space, tab, line feed, and carriage return characters) is trimmed by the database server at query execution time. This is necessary to emulate Progress' treatment of character fields in where clauses. Qualifying references may be DMO properties which store text values or server-side functions which return text data. In cases where functions cannot be embedded within index definitions, replaces text property references with computed column references.
- Rewrites where clauses written with an enhanced form of FQL syntax on the fly, in order to facilitate rewritten it to SQL, further downstream.
- Rewrites unary logical expressions as binary comparisons with true in order to work around a defect in the ORM's FQL parser which disallows unary logical conditions (TODO: is this still the case?).
- Identifies and preserves sets of DMO properties used as restriction criteria in the preprocessed where clause. The names of these properties are stored as sets, indexed in a map by the associated DMO implementation class(es).
- Injects error handling functions around expressions which need to be protected. Expressions which meet the following criteria must be enclosed in the checkError() function. The first parameter to this function is initError(false), and the second parameter is the expression requiring error handling. The criteria are:
  - include a server-side PL function;
  - evaluate to a boolean result;
  - reside within the where clause of a subselect phrase.
  The call to initError(false) initializes the error handler for the current checkError() scope. The execution of the expression may or may not report an error to the error handler. The checkError() function checks the error handler's current scope for an error and handles it as necessary.
- Handles "manual" overloading of user defined functions. Multiple user defined functions can be registered for the same base functions name. At preprocessing time, the parameter signature determines which overloaded function will be used, and the overloaded function name is replaced in FQL with a specific backing function.
- In certain cases, inlines query substitution parameters directly into the where clause string. Only those parameters which participate in range matches (e.g., >, >=, <, <=, and some forms of LIKE) are inlined, and then only if the database dialect supports it, and the caller has requested it. Instances of this class which have had parameters inlined are not cached. The purpose of inlining is to allow the backing database to choose a better query plan when it prepares the query, since it has more information about range matches than if this information were provided later, at query execution time.
- Collects equality matches between the current buffer's properties and substitution parameter placeholders or literal values, for the purpose of enabling a rudimentary analysis of the where clause's complexity and suitability for participation in a server-side join with other tables.
Furthermore, each instance of this class provides the necessary contextual information required by the enclosing query to properly embed the rewritten where clause into an overall FQL statement.
For example, the FWD environment allows the following syntax:
```
    from SomeDMOImpl as alias
    where alias.propertyABC[5] = ?
 
```
as shorthand for something like:
```
    from SomeDMOImpl as alias
    join alias.composite32 as alias_composite32
    where alias_composite32.propertyABC = ? and index(alias_composite32) = 5
 
```
The former syntax is not directly supported by Hibernate and so the where clause alias.propertyABC[5] = ? is expanded to the latter form internally, within the P2J persistence framework.
This rewriting is only necessary in the particular situation where a DMO class contains a list of composite elements, and a where clause references a property of such a composite element. The above example corresponds to a Hibernate mapping of:
```
    ...
    [class name="SomeDMOImpl" ...]
       ...
       [list name="composite32" ]
          ...
          [composite-element class="SomeDMOImpl$Composite32"]
             [property name="propertyABC" ... /]
             ...
          [/composite-element]
       [/list]
       ...
    [/class]
    ...
 
```
Allowing the shorthand syntax hides the complexity of the DMO implementation underlying the Hibernate mapping, and prevents the public API of the persistence runtime from becoming more complicated. The latter point is made because, in addition to the expansion of the where clause, one or more ANSI-style joins will be added to the overall FQL statement, and the order of query substitution parameters may be changed. The following service methods are provided to enable enclosing queries to embed the preprocessed where clause in the FQL statement, and to organize substitution parameters in the proper order:
A where clause is preprocessed during construction of an instance of this class. Parsing errors are logged, but are otherwise ignored. Ultimately, the ORM will report an FQL problem if the input where clause is invalid.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`private static class`	`FQLPreprocessor.CacheKey` Instances of this class are used as keys to cache instances of `HQLPreprocessor`.
`(package private) static class`	`FQLPreprocessor.PropertyMatch` Object which contains information about a single comparison of a database property to a substitution parameter or literal value.
`static class`	`FQLPreprocessor.PropertyPair` A public container for storing a pair of properties.
`static class`	`FQLPreprocessor.SessionAttr` Mutable SESSION attributes added to the UDF calls
`private static class`	`FQLPreprocessor.UdfNamesHolder` Holds the set of UDFs synthetic names.

Field Summary

Fields
Modifier and Type	Field and Description
`private java.util.LinkedHashSet<java.lang.String>`	`ansiJoins` FQL subexpressions to perform ANSI joins of associated lists
`private static LRUCache<java.lang.String,HQLAst>`	`astCache` Cache of parsed ASTs representing where clauses
`private java.util.Map<java.lang.String,RecordBuffer>`	`bufferMap` Temporary map of dmo alias names to record buffers
`private static LRUCache<FQLPreprocessor.CacheKey,FQLPreprocessor>`	`cacheNoArgs` Cache of prepared instances, indexed by Persistence and where clause
`private static LRUCache<FQLPreprocessor.CacheKey,FQLPreprocessor>`	`cacheWithArgs` Cache of prepared instances, indexed by Persistence and where clause
`private Database`	`database` Database associated with this object
`private java.util.Deque<RecordBuffer>`	`defaultBuffers` The stack of default buffers when sub-SELECTs are processed.
`private boolean`	`dependsOnSessionAttribute` Flag indicating that the query depends on mutable SESSION attribute(s).
`private java.lang.String`	`dropAlias` DMO alias to drop during FQL where clause generation or `null` if none
`private java.util.LinkedList<java.lang.String>`	`dropAliases` The stack of original aliases names when sub-SELECTs are processed.
`private java.util.List<java.lang.String>`	`earlyPublishEntities` List of entities which publish uncommitted changes prematurely
`private boolean`	`findByRowid` Flag the query that it should performed on recid/rowid lookup table.
`private java.lang.Long`	`findByRowidValue` The actual `rowid` value that is to be loaded if it is a constant detected in `fql` preprocessing.
`private FQLExpression`	`fql` FQL-compliant where clause (possibly rewritten)
`private static java.lang.String`	`GUARDED` Prefix for guarded versions of UDFs
`private boolean`	`hasContains` Flags any `contains` method encountered while processing the predicate.
`private boolean`	`inline` Whether substitution parameter inlining is permitted/was performed
`private boolean`	`inlinedTernary` Flag indicating if a ternary then/else was removed based on substitution parameter value, thus caching will not be possible.
`private static CentralLogger`	`LOG` Logger
`private boolean`	`nonConstantContains` Flag indicating that the FQL has a "contains" keyword with a non-constant expression.
`private static FQLPreprocessor`	`NOP_INSTANCE` A do-nothing instance for empty where clauses
`private static java.util.Map<FunctionKey,java.lang.String>`	`overloadedFunctions` Map of FQL function keys to overloaded SQL (unique) function names
`private ParameterIndices`	`paramIndices` Mapping of index positions for substitution parameters after rewrite
`private java.util.List<FQLPreprocessor.PropertyMatch>`	`propertyMatches` List of property matches detected in a where clause
`private java.util.BitSet`	`queryProperties` The set of properties used in the query predicate.
`private java.lang.String`	`replacementAlias` If not `null` the `dropAlias` is forced instead of dropping it.
`private java.util.LinkedList<java.lang.String>`	`replacementAliases` The stack of unique aliases for the outer sub-SELECTs are processed.
`private java.util.Map<java.lang.String,java.util.Set<java.lang.String>>`	`restrictionProperties` Map of properties used by this where clause, keyed by DMO entity
`private java.util.List<FQLPreprocessor.PropertyPair>`	`substPairs` The substitution pairs.
`private static HQLAst`	`TERNARY_COMPARE_EXP_TEMPLATE` The template for the normalized ternary which was used in a comparison expression.
`private static HQLAst`	`TERNARY_LOGICAL_EXP_TEMPLATE` The template for the normalized ternary which was used in a logical expression.
`private UniqueIndexLookup`	`uniqueIndexLookup` Helper that helps indentifying if this where clause is in fact a unique index look-up.

Fields inherited from interface com.goldencode.p2j.persist.hql.HQLParserTokenTypes
ALIAS, AND, AS, BOOL_FALSE, BOOL_TRUE, CASE, CAST, COMMA, CONCAT, DEC_LITERAL, DIGIT, DIVIDE, DMO, DOT, ELSE, END, EOF, EQUALS, ESCAPE, FROM, FUNCTION, GT, GTE, IN, INDEX, IS, IS_NULL, JOIN, LBRACKET, LETTER, LIKE, LONG_LITERAL, LPARENS, LT, LTE, MINUS, MULTIPLY, NOT, NOT_EQ, NOT_NULL, NULL, NULL_TREE_LOOKAHEAD, NUM_LITERAL, OR, PLUS, PROPERTY, RBRACKET, RPARENS, SELECT, SQL_TYPE, STRING, SUBSCRIPT, SUBSELECT, SUBST, SYM_CHAR, SYMBOL, TERNARY, THEN, UN_MINUS, VALID_1ST_IDENT, VALID_SYM_CHAR, WHEN, WHERE, WS

Constructor Summary

Constructors
Modifier	Constructor and Description
`private`	`FQLPreprocessor(Database database, java.lang.String where, java.util.Map<java.lang.String,RecordBuffer> bufferMap, java.lang.Object[] parameters, FqlType[] paramTypes, java.lang.String[] referenceSubs, Dialect dialect, boolean overload, boolean inline, java.lang.String dropAlias, java.lang.String replacementAlias, boolean informational, java.util.Set<java.lang.String> indexedFields)` Constructor which accepts an unprocessed where clause.
`private`	`FQLPreprocessor(java.util.List<RecordBuffer> bound, java.util.List<RecordBuffer> definition, java.lang.String where, boolean singleBuffer)` Translate this `where` clause to use the bound DMO's alias and property names, instead the definition (conversion-time) alias and property names.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`private void`	`addRestrictionProperty(java.lang.String entity, java.lang.String property)` Add the given property name to the set of properties used by this where clause as restriction criteria.
`private java.util.Map<HQLAst,java.lang.String>`	`analyzeComposites(HQLAst root)` Analyze the AST generated for the FQL expression, identifying those subtrees which are targets for conversion.
`private void`	`annotateParameters(HQLAst root, FqlType[] paramTypes)` Walk the FQL AST, annotating query substitution parameter nodes with their data types as they are visited.
`(package private) java.util.Iterator<java.lang.String>`	`ansiJoins()` Get an iterator on the ANSI-style join subexpressions which must be merged by the enclosing query into the overall FQL query statement, in order to properly join associated composite element lists (if any).
`private HQLAst`	`augmentForUnknownValue(HQLAst root, Dialect dialect)` Walk the tree, which has been simplified/rolled-up `simplifyUnknowns(Set)` by now, and augment certain binary sub-expressions to match Progress' unknown value semantics.
`private boolean`	`checkFindByRowid(HQLAst root)` Analyze the query preprocessed tree and checks if it represents a simple ROWID/RECID lookup.
`private UniqueIndexLookup`	`checkUniqueFind()` Check if the where clause is a look-up over a unique index.
`private void`	`collectPropertyMatches(HQLAst root)` Walk the where clause AST and collect all simple property matches.
`private static HQLAst`	`createAstNode(int type, java.lang.String text, HQLAst parent)` Utility method for creating a designed HQLAst node.
`private ParameterIndices`	`createParameterIndices(HQLAst root, java.lang.Object[] parameters)` Create the mapping of substitution parameters to their corresponding substitution placeholders in the rewritten FQL where clause.
`private void`	`duplicateAugmentedOperand(HQLAst source, HQLAst parent)` Duplicate the given source operand node and graft the duplicate under `parent`.
`private FQLExpression`	`emit(HQLAst root, boolean translate)` Emit the `restructured` where clause AST into an infix notation expression, which is compliant with the FQL syntax supported by the ORM.
`private HQLAst`	`fixEmptyContains(HQLAst root, java.lang.Object[] parameters)` Replaces `contains` function node with `false` is the second argument is an empty string.
`private java.lang.String`	`generateJoin(java.lang.String compName, java.lang.String alias, java.lang.String verboseAlias)` Generate a single FQL subexpression for an ANSI-style join, which joins a "master" DMO record with an associated list of composite elements.
`private java.util.LinkedHashSet<java.lang.String>`	`generateJoins(java.util.Map<HQLAst,java.lang.String> targets)` Define the set of ANSI-style join statements required to join the "master" DMO with one or more associated lists of composite elements.
`static FQLPreprocessor`	`get(java.lang.String where, Database database, Dialect dialect, RecordBuffer[] buffers, java.lang.Object[] parameters, java.lang.String[] referenceSubs, boolean inline, java.lang.String dropAlias, java.lang.String replacementAlias, boolean informational, java.util.Set<java.lang.String> indexedFields)` Factory method which accepts an unprocessed where clause, the database instance and the database dialect associated with the enclosing query, the DMO implementation class, and the substitution parameters, if any, for the query.
`private java.lang.Iterable<HQLAst>`	`getDenormalizedFields(HQLAst root)` Get list of denormalized fields with extent for where clause AST.
`(package private) java.util.List<java.lang.String>`	`getEarlyPublishEntities()` Retrieve the list of DMO entity names which will trigger the premature publication of uncommitted changes across sessions, once the query containing this preprocessor's underlying where clause is executed.
`long`	`getFindByRowid(java.lang.Object[] queryParams)` If this query is a ROWID/RECID lookup, get the record ID we are looking for.
`(package private) FQLExpression`	`getFQL()` Get the (possibly rewritten) where clause, which is compliant with FQL syntax.
`(package private) ParameterIndices`	`getParameterIndices()` Get the `ParameterIndices` object associated with this query.
`(package private) java.util.List<FQLPreprocessor.PropertyMatch>`	`getPropertyMatches()` Get an unmodifiable list of the property matches collected for this where clause.
`java.util.BitSet`	`getQueryProperties()` Obtains the list of properties the preprocessed FQL is based on.
`(package private) static java.lang.String`	`getRegisteredFunction(Database database, java.lang.String fqlFunction, java.lang.Class<?>[] paramTypes)` Returns the SQL name of the user-defined function previously registered by `registerFunction(Database, String, String, Method)`.
`(package private) java.util.Map<java.lang.String,java.util.Set<java.lang.String>>`	`getRestrictionProperties()` Get an unmodifiable map of DMO entity names to sets of the names of the DMO properties used as restriction criteria in the preprocessed where clause.
`java.util.List<FQLPreprocessor.PropertyPair>`	`getSubstPairs()` Obtain the substitution pair list, if any.
`UniqueIndexLookup`	`getUniqueIndexLookup()` Retrieve the unique index loop-up object, responsible for storing information on the unique index that is used.
`(package private) boolean`	`hasAnsiJoins()` Report whether any ANSI-style join subexpressions are present.
`(package private) boolean`	`hasContains()` Reports whether the predicate uses `contains()` function at least once.
`(package private) boolean`	`hasNonConstantContains()` Report whether "contains" keyword with a non-constant expression is present in the FQL.
`private HQLAst`	`honorDisjunctiveForm(HQLAst root)` The method receives a HQLAst and searches for augmented nodes and rewrites them if possible.
`static void`	`initializeCache()` Initializes the cache using CacheManager.
`private boolean`	`injectComputedColumn(HQLAst astNode)` Given an AST which represents a qualified or an unqualified text property, replace the property's text (the property name) with a name which represents a computed column.
`private void`	`inlineDenormalizedField(HQLAst ast, java.lang.Object[] parameters)` Replace legacy indexed property with extent with custom property.
`private java.util.List<FQLPreprocessor.PropertyPair>`	`inlineReferenceSubs(HQLAst root, java.lang.String[] referenceSubs)` Given an array containing one or more strings and zero or more nulls, replace those query substitution parameters in the where clause AST which positionally coincide with the non-null strings in the array.
`private int`	`inlineSubstitutionParameter(HQLAst ast, java.lang.Object[] parameters, Dialect dialect)` Attempt to inline a single query substitution parameter, if it is a numeric, text, or date type.
`private boolean`	`isBinaryOperator(Aast ast)` Convenience method to detect whether an AST represents a binary operator, based on its token type.
`(package private) static boolean`	`isConstant(HQLAst node)` Starting from `node`, check if the current expreesion is constant or not.
`boolean`	`isDependsOnSessionAttribute()` Checks if the query depends on mutable SESSION attribute(s).
`boolean`	`isFindByRowid()` Check if the preprocessed query is a simple RECID/ROWID lookup query.
`private boolean`	`isMandatoryProperty(HQLAst alias, HQLAst property)` Determine whether the given property in the context of the DMO class represented by the given buffer alias represents a mandatory (i.e., non-nullable) database column.
`private boolean`	`isOppositeOperandNullable(HQLAst ast, int index)` Given an AST and its index, and assuming it is one of two operands in a binary comparison, indicate whether the opposite operand is nullable.
`private static boolean`	`isUDF(Dialect dialect, HQLAst n)` Check if node represents UDF.
`private static boolean`	`isUDFArgument(Dialect dialect, HQLAst n)` Check if node represents UDF argument.
`boolean`	`isUniqueFind(boolean includeRowid)` Check if the where clause is a conjunction of equality clauses that strictly cover an unique index.
`private RecordBuffer`	`lookupBuffer(Aast alias)` Look up the record buffer associated with the given alias.
`private HQLAst`	`mainWalk(HQLAst root, java.lang.Object[] parameters, FqlType[] paramTypes, Dialect dialect, boolean overload)` Walk the AST depth-first from root to leaves and rewrite certain nodes.
`private void`	`makeExplicitCast(HQLAst parent, int index, Dialect dialect)` Replaces the specified child node of a given parent with `cast(? as <datatype>)` if it represents a substitution parameter.
`private void`	`manuallyOverload(HQLAst function)` Manually disambiguate a user defined function by taking its overloaded function name and data type signature and replacing the name in its AST with a unique name generated when the function was registered.
`private HQLAst`	`normalizeTernary(HQLAst root, java.lang.Object[] parameters)` Normalize a ternary clause into an equivalent logical expression.
`private HQLAst`	`parse()` Scan and parse the input where clause and return it in the form of an abstract syntax tree.
`private void`	`preprocess(java.lang.String where, java.lang.Object[] parameters, FqlType[] paramTypes, java.lang.String[] referenceSubs, Dialect dialect, boolean overload, boolean informational, java.util.Set<java.lang.String> indexedFields)` The main worker method which drives preprocessing.
`static void`	`registerFunction(Database database, java.lang.String fqlFunction, java.lang.String sqlFunction, java.lang.reflect.Method method)` Register a user-defined function to the specified backing method for the given database.
`private HQLAst`	`restructure(HQLAst root, java.util.Map<HQLAst,java.lang.String> targets)` Restructure the AST subtrees (if any) defined as rewrite targets by the `composite analysis step`.
`private void`	`rewriteAlias(HQLAst alias, HQLAst relRoot, java.lang.String compName)` Given a particular, target subtree and a composite list entity name, rewrite the AST as described in the `restructure(com.goldencode.p2j.persist.hql.HQLAst, java.util.Map<com.goldencode.p2j.persist.hql.HQLAst, java.lang.String>)` method.
`private void`	`simplifyProperties(HQLAst root, boolean eliminateUpper, boolean eliminateRtrim)` Eliminates unneeded [upper] functions for case-insensitive properties and [rtrim] functions for automatically rtrimmed properties.
`private java.util.Set<HQLAst>`	`simplifyUnknowns(java.util.Set<HQLAst> unknowns)` Get rid of unknowns in an FQL AST by evaluating relations in which these unknowns participate.
`(package private) static java.lang.String`	`translate(java.util.List<RecordBuffer> bound, java.util.List<RecordBuffer> definition, java.lang.String where, boolean singleBuffer)` Translate this `where` clause to use the bound DMO's alias and property names, instead the definition (conversion-time) alias and property names.
`private HQLAst`	`trySimplifyBooleans(HQLAst booleanOperand, HQLAst root)` Tries to roll up subexpressions according to the following rules: {condition} or false --> {condition} {condition} or true --> true {condition} and true --> {condition} {condition} and false --> false
`(package private) boolean`	`wasInlined()` Indicate whether query substitution parameters participating in range checks were inlined directly into the query string.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - GUARDED
```
private static final java.lang.String GUARDED
```
    Prefix for guarded versions of UDFs
    
    See Also:
    
    Constant Field Values
  - LOG
```
private static final CentralLogger LOG
```
    Logger
  - NOP_INSTANCE
```
private static final FQLPreprocessor NOP_INSTANCE
```
    A do-nothing instance for empty where clauses
  - overloadedFunctions
```
private static final java.util.Map<FunctionKey,java.lang.String> overloadedFunctions
```
    Map of FQL function keys to overloaded SQL (unique) function names
  - TERNARY_LOGICAL_EXP_TEMPLATE
```
private static final HQLAst TERNARY_LOGICAL_EXP_TEMPLATE
```
    The template for the normalized ternary which was used in a logical expression.
  - TERNARY_COMPARE_EXP_TEMPLATE
```
private static final HQLAst TERNARY_COMPARE_EXP_TEMPLATE
```
    The template for the normalized ternary which was used in a comparison expression.
  - cacheWithArgs
```
private static LRUCache<FQLPreprocessor.CacheKey,FQLPreprocessor> cacheWithArgs
```
    Cache of prepared instances, indexed by Persistence and where clause
  - cacheNoArgs
```
private static LRUCache<FQLPreprocessor.CacheKey,FQLPreprocessor> cacheNoArgs
```
    Cache of prepared instances, indexed by Persistence and where clause
  - astCache
```
private static LRUCache<java.lang.String,HQLAst> astCache
```
    Cache of parsed ASTs representing where clauses
  - database
```
private final Database database
```
    Database associated with this object
  - dropAlias
```
private java.lang.String dropAlias
```
    DMO alias to drop during FQL where clause generation or null if none
  - replacementAlias
```
private java.lang.String replacementAlias
```
    If not null the dropAlias is forced instead of dropping it. This is needed in order to allow the ORM to properly resolve the fields in a query in a very specific case: - nested queries; - the dropAlias table is part of both outer and inner selects; - the dropAlias table has a field with same name. For unknown cause, the ORM will generate a SQL query that instead of this particular field, the id field of the table from outer select will be used.
    Valid only if dropAlias is not null.
  - defaultBuffers
```
private java.util.Deque<RecordBuffer> defaultBuffers
```
    The stack of default buffers when sub-SELECTs are processed. The number of elements in this collection gives the nesting level at any given moment when emitting the FQL. It is not used at parsing time.
  - dropAliases
```
private java.util.LinkedList<java.lang.String> dropAliases
```
    The stack of original aliases names when sub-SELECTs are processed. The number of elements in this collection gives the nesting level at any given moment when emitting the FQL. It is not used at parsing time.
  - replacementAliases
```
private java.util.LinkedList<java.lang.String> replacementAliases
```
    The stack of unique aliases for the outer sub-SELECTs are processed. The number of elements in this collection gives the nesting level at any given moment when emitting the FQL. It is not used at parsing time.
  - ansiJoins
```
private java.util.LinkedHashSet<java.lang.String> ansiJoins
```
    FQL subexpressions to perform ANSI joins of associated lists
  - hasContains
```
private boolean hasContains
```
    Flags any contains method encountered while processing the predicate.
  - fql
```
private FQLExpression fql
```
    FQL-compliant where clause (possibly rewritten)
  - inline
```
private boolean inline
```
    Whether substitution parameter inlining is permitted/was performed
  - inlinedTernary
```
private boolean inlinedTernary
```
    Flag indicating if a ternary then/else was removed based on substitution parameter value, thus caching will not be possible.
  - paramIndices
```
private ParameterIndices paramIndices
```
    Mapping of index positions for substitution parameters after rewrite
  - restrictionProperties
```
private java.util.Map<java.lang.String,java.util.Set<java.lang.String>> restrictionProperties
```
    Map of properties used by this where clause, keyed by DMO entity
  - earlyPublishEntities
```
private java.util.List<java.lang.String> earlyPublishEntities
```
    List of entities which publish uncommitted changes prematurely
  - propertyMatches
```
private java.util.List<FQLPreprocessor.PropertyMatch> propertyMatches
```
    List of property matches detected in a where clause
  - findByRowid
```
private boolean findByRowid
```
    Flag the query that it should performed on recid/rowid lookup table.
  - uniqueIndexLookup
```
private UniqueIndexLookup uniqueIndexLookup
```
    Helper that helps indentifying if this where clause is in fact a unique index look-up.
  - findByRowidValue
```
private java.lang.Long findByRowidValue
```
    The actual rowid value that is to be loaded if it is a constant detected in fql preprocessing. If it is null but findByRowid = true then the row index was not yet evaluated because it is a SUBST node. The actual value cannot be cached in this object because it may be different at each call. To detect whether the query looks for the template record of a table, the parameter[0] of the query iteration must be analyzed.
  - bufferMap
```
private java.util.Map<java.lang.String,RecordBuffer> bufferMap
```
    Temporary map of dmo alias names to record buffers
  - substPairs
```
private java.util.List<FQLPreprocessor.PropertyPair> substPairs
```
    The substitution pairs. They are optionally computed in preprocess if replacementAliases are present.
  - queryProperties
```
private java.util.BitSet queryProperties
```
    The set of properties used in the query predicate.
  - dependsOnSessionAttribute
```
private boolean dependsOnSessionAttribute
```
    Flag indicating that the query depends on mutable SESSION attribute(s).
  - nonConstantContains
```
private boolean nonConstantContains
```
    Flag indicating that the FQL has a "contains" keyword with a non-constant expression.
- Constructor Detail
  - FQLPreprocessor
```
private FQLPreprocessor(java.util.List<RecordBuffer> bound,
                        java.util.List<RecordBuffer> definition,
                        java.lang.String where,
                        boolean singleBuffer)
```
    Translate this where clause to use the bound DMO's alias and property names, instead the definition (conversion-time) alias and property names.
    
    Parameters:
    
    bound - The runtime-bound buffers.
    
    definition - The buffers as it was used to generate the where clause at conversion time.
    
    where - The FQL to be translated.
    
    singleBuffer - Single buffer mode. If activated, a standalone property is assumed to belong the only bound buffer. Requires bound and definition to have a single element.
  - FQLPreprocessor
```
private FQLPreprocessor(Database database,
                        java.lang.String where,
                        java.util.Map<java.lang.String,RecordBuffer> bufferMap,
                        java.lang.Object[] parameters,
                        FqlType[] paramTypes,
                        java.lang.String[] referenceSubs,
                        Dialect dialect,
                        boolean overload,
                        boolean inline,
                        java.lang.String dropAlias,
                        java.lang.String replacementAlias,
                        boolean informational,
                        java.util.Set<java.lang.String> indexedFields)
                 throws PersistenceException
```
    Constructor which accepts an unprocessed where clause.
    Parameters:
    
    database - Database within which the associated query will be run.
    
    where - An unprocessed where clause which will be scanned, parsed, and possibly rewritten. Should not include the leading where keyword.
    
    bufferMap - A map of DMO aliases to their corresponding record buffers. If dropAlias is not null, a null key will be mapped to the buffer corresponding with this alias.
    
    parameters - Query substitution parameters for the where clause.
    
    paramTypes - The query substitution parameter types.
    
    dialect - Database dialect in use.
    
    overload - true to manually overload user-defined functions.
    
    inline - true to allow substitution parameters involved in range checks to be inlined; false to disallow such inlining. If inlining occurs, the preprocessor will not be cached.
    
    dropAlias - If non-null, suppress this alias qualifier when emitting the final FQL where clause string; if null, emit aliases normally.
    
    informational - Flag indicating preprocessing is analytical only and query will not be executed.
    indexedFields - The list of indexed fields. In all cases, except for indexed FIND queries:
    
    t.f <= ? and ? >= t.f expressions are always evaluated to true;
    
    t.f < ? and ? > t.f expressions are equivalent to t.f <> ?
    
    because the unknown value (?) is sorted high in P4GL index.
    In the case of FIND queries where the compared field is not part of the current index, P4GL has a flaw that evaluates the mentioned expressions:
    
    t.f <= ? and ? >= t.f to true only if t.f is unknown
    
    t.f < ? and ? > t.f are always false.
    Throws:
    
    PersistenceException - if there is any error rewriting the where clause.
- Method Detail
  - get
```
public static FQLPreprocessor get(java.lang.String where,
                                  Database database,
                                  Dialect dialect,
                                  RecordBuffer[] buffers,
                                  java.lang.Object[] parameters,
                                  java.lang.String[] referenceSubs,
                                  boolean inline,
                                  java.lang.String dropAlias,
                                  java.lang.String replacementAlias,
                                  boolean informational,
                                  java.util.Set<java.lang.String> indexedFields)
                           throws PersistenceException
```
    Factory method which accepts an unprocessed where clause, the database instance and the database dialect associated with the enclosing query, the DMO implementation class, and the substitution parameters, if any, for the query. This method may return a shared, immutable instance from a cache if such an object was created previously for the given where clause and parameter types.
    Parameters:
    
    where - An unprocessed where clause which will be scanned, parsed, and possibly rewritten. Should not include the leading where keyword.
    
    database - Database object associated with the client query.
    
    dialect - Database dialect in use.
    
    buffers - All buffers referenced by the where clause.
    
    parameters - Query substitution parameters for the where clause.
    
    referenceSubs - TODO: add description
    
    inline - true to permit inlining of substitution parameters involved in range matches (>, >=, <, <=, like); false to disallow such inlining. Inlining will embed such parameters into the FQL string directly.
    
    dropAlias - If non-null, suppress this alias qualifier when emitting the final FQL where clause string; if null, emit aliases normally.
    
    replacementAlias - In the case of a nested SELECT, use this unique alias as a replacement for default alias that may cause the ORM to generate bad SQL.
    
    informational - Flag indicating preprocessing is analytical only and query will not be executed.
    indexedFields - The list of indexed fields. In all cases, except for indexed FIND queries:
    
    t.f <= ? and ? >= t.f expressions are always evaluated to true;
    
    t.f < ? and ? > t.f expressions are equvalent to t.f <> ?
    
    because the unknown value (?) is sorted high in P4GL index.
    In the case of FIND queries where the compared field is not part of the current index, P4GL has a flaw that evaluates the mentioned expressions:
    
    t.f <= ? and ? >= t.f to true only if t.f is unknown
    
    t.f < ? and ? > t.f are always false.
    Returns:
    
    An instance of this class. At the time this object is returned, all preprocessing work is complete.
    
    Throws:
    
    PersistenceException - if there is any error rewriting the where clause.
  - registerFunction
```
public static void registerFunction(Database database,
                                    java.lang.String fqlFunction,
                                    java.lang.String sqlFunction,
                                    java.lang.reflect.Method method)
```
    Register a user-defined function to the specified backing method for the given database.
    
    Parameters:
    
    database - Database for which user-defined function is registered.
    
    fqlFunction - FQL function name (as generated in java code).
    
    sqlFunction - SQL function name that will be used in queries.
    
    method - Method which will back the given function and provide function signature.
  - getRegisteredFunction
```
static java.lang.String getRegisteredFunction(Database database,
                                              java.lang.String fqlFunction,
                                              java.lang.Class<?>[] paramTypes)
```
    Returns the SQL name of the user-defined function previously registered by registerFunction(Database, String, String, Method).
    
    Parameters:
    
    database - Database for which user-defined function is registered.
    
    fqlFunction - FQL function name (as generated in java code).
    
    paramTypes - The function signature.
    
    Returns:
    
    SQL name of the registered user-defined function or null if not found.
  - translate
```
static java.lang.String translate(java.util.List<RecordBuffer> bound,
                                  java.util.List<RecordBuffer> definition,
                                  java.lang.String where,
                                  boolean singleBuffer)
```
    Translate this where clause to use the bound DMO's alias and property names, instead the definition (conversion-time) alias and property names.
    
    Parameters:
    
    bound - The runtime-bound buffers.
    
    definition - The buffers as it was used to generate the where clause at conversion time.
    
    where - The FQL to be translated.
    
    singleBuffer - Single buffer mode. If activated, a standalone property is assumed to belong the only bound buffer. Requires bound and definition to have a single element.
    
    Returns:
    
    The translated FQL.
  - isConstant
```
static boolean isConstant(HQLAst node)
```
    Starting from node, check if the current expreesion is constant or not.
    
    Parameters:
    
    node - The HQLAst node from where we start the check.
    
    Returns:
    
    true if the current expression is constant, false otherwise.
  - getFQL
```
FQLExpression getFQL()
```
    Get the (possibly rewritten) where clause, which is compliant with FQL syntax.
    
    Returns:
    
    FQL where clause, with no leading where keyword.
  - getSubstPairs
```
public java.util.List<FQLPreprocessor.PropertyPair> getSubstPairs()
```
    Obtain the substitution pair list, if any.
    
    Returns:
    
    the substitution pair list or null if none was detected.
  - getQueryProperties
```
public java.util.BitSet getQueryProperties()
```
    Obtains the list of properties the preprocessed FQL is based on.
    
    Returns:
    
    The set of properties accessed by the FQL predicate.
  - isDependsOnSessionAttribute
```
public boolean isDependsOnSessionAttribute()
```
    Checks if the query depends on mutable SESSION attribute(s).
    
    Returns:
    
    true if the query depends on mutable SESSION attribute(s).
  - isFindByRowid
```
public boolean isFindByRowid()
```
    Check if the preprocessed query is a simple RECID/ROWID lookup query.
    Generally, we can easily find such records using persistent database or dirty database for uncommitted transient records. Using normal queries, the transient record that has not validated its index, won't break the transaction isolation idiom and normally should not be shared to any context. However, using RECID/ROWID lookup query the record should be find across transactions and contexts, by direct accessing the record lookup table.
    The predicate of such query will only test for equality of the RECID/ROWID of the record against a SUBST value. Using LTE or GTE will fail to find the requested record.
    
    Returns:
    
    true if the preprocessed query is a simple RECID/ROWID lookup query.
  - getFindByRowid
```
public long getFindByRowid(java.lang.Object[] queryParams)
```
    If this query is a ROWID/RECID lookup, get the record ID we are looking for. Otherwise the result should be ignored.
    By convention, if the result is negative, the template record should be loaded. Values strictly positive are looked up into the database.
    
    Parameters:
    
    queryParams - The current parameter list for the query.
    
    Returns:
    
    the row id of the record in case of direct access using RECID/ROWID query.
  - isUniqueFind
```
public boolean isUniqueFind(boolean includeRowid)
```
    Check if the where clause is a conjunction of equality clauses that strictly cover an unique index. This way, it is guaranteed that there is zero or one record fetched at the end.
    
    Parameters:
    
    includeRowid - true if the function should consider rowid as a field of an unique index.
    
    Returns:
    
    true if the target where clause if for zero or one record due to an unique index look-up.
  - getUniqueIndexLookup
```
public UniqueIndexLookup getUniqueIndexLookup()
```
    Retrieve the unique index loop-up object, responsible for storing information on the unique index that is used. Note that the properties form a unique index, but not necessarily in the provided order. Also, some values may be null due to the fact that they are substitution.
    
    Returns:
    
    an object which may assist faster look-up based on unique indexes
  - initializeCache
```
public static void initializeCache()
```
    Initializes the cache using CacheManager. The default value of the cache is used when there is no size available from the configuration.
  - getParameterIndices
```
ParameterIndices getParameterIndices()
```
    Get the ParameterIndices object associated with this query. This object maintains an array of zero-based indices into the array of query substitution arguments for the where clause, as it exists after preprocessing is complete. This additional level of indirection is necessary because the query substitution placeholders may have been reordered within the FQL where clause expression during the FQL preprocessing rewrite step, and some parameters may have been inlined into the where clause.
    
    Returns:
    
    An object which provides a mapping of indices into the query substitution parameter list.
  - ansiJoins
```
java.util.Iterator<java.lang.String> ansiJoins()
```
    Get an iterator on the ANSI-style join subexpressions which must be merged by the enclosing query into the overall FQL query statement, in order to properly join associated composite element lists (if any).
    
    Returns:
    
    An iterator on join subexpressions. The iterator may be empty, but will not be null.
  - hasAnsiJoins
```
boolean hasAnsiJoins()
```
    Report whether any ANSI-style join subexpressions are present.
    
    Returns:
    
    true if there are ANSI joins; else false.
  - hasContains
```
boolean hasContains()
```
    Reports whether the predicate uses contains() function at least once.
    
    Returns:
    
    true if the contains() function was encountered while parsing the predicate.
  - hasNonConstantContains
```
boolean hasNonConstantContains()
```
    Report whether "contains" keyword with a non-constant expression is present in the FQL.
    
    Returns:
    
    true if "contains" keyword is present; else false
  - getEarlyPublishEntities
```
java.util.List<java.lang.String> getEarlyPublishEntities()
```
    Retrieve the list of DMO entity names which will trigger the premature publication of uncommitted changes across sessions, once the query containing this preprocessor's underlying where clause is executed.
    This method is intended to support the emulation of a quirk/bug in Progress whereby the execution of a query (in the generic sense of the term) in a session after uncommitted changes, will trigger those changes to be prematurely published to other sessions.
    TODO: this behavior may represent a version-specific bug in Progress which should be disabled in P2J for other versions than 9.1C.
    
    Returns:
    
    The list of entities, if any, which will have their uncommitted changes published prematurely if the underlying where clause is executed in the current session. The returned list may be empty, but it will never be null.
  - getPropertyMatches
```
java.util.List<FQLPreprocessor.PropertyMatch> getPropertyMatches()
```
    Get an unmodifiable list of the property matches collected for this where clause.
    
    Returns:
    
    Property matches in the order visited and collected.
  - getRestrictionProperties
```
java.util.Map<java.lang.String,java.util.Set<java.lang.String>> getRestrictionProperties()
```
    Get an unmodifiable map of DMO entity names to sets of the names of the DMO properties used as restriction criteria in the preprocessed where clause.
    
    Returns:
    
    Map of DMO entity names to sets of property names, or null if the where clause contained no restriction properties.
  - wasInlined
```
boolean wasInlined()
```
    Indicate whether query substitution parameters participating in range checks were inlined directly into the query string. If called during construction (before inlining actually occurs), this method will return whether this object can be inlined. If called after construction completes, it will return whether this object actually was inlined. That is, even if inlining was permitted, it will not have occurred if no suitable subexpressions were detected in the where clause provided.
    
    Returns:
    
    true if inlining was performed (with the caveats noted above); else false.
  - lookupBuffer
```
private RecordBuffer lookupBuffer(Aast alias)
```
    Look up the record buffer associated with the given alias.
    
    Parameters:
    
    alias - AST representing the alias (variable name) with which the buffer was defined in business logic.
    
    Returns:
    
    Record buffer associated with the alias.
    
    Throws:
    
    java.lang.IllegalArgumentException - if alias does not match any buffer whose scope is currently open.
  - preprocess
```
private void preprocess(java.lang.String where,
                        java.lang.Object[] parameters,
                        FqlType[] paramTypes,
                        java.lang.String[] referenceSubs,
                        Dialect dialect,
                        boolean overload,
                        boolean informational,
                        java.util.Set<java.lang.String> indexedFields)
                 throws PersistenceException
```
    The main worker method which drives preprocessing. Performs the following steps:
    1. parse the input where clause;
    2. restructure ASTs representing qualified names of text properties and functions to embed these names with an SQL function which trims trailing whitespace;
    3. restructure ASTs representing unary logical expressions to instead be binary logical comparisons with true.
    4. analyze the resulting AST to identify subtrees which require restructuring;
    5. possibly inline certain query substitution parameters;
    6. restructure the AST to account for the joins;
    7. generate any necessary ANSI join subexpressions;
    8. emit the rewritten result as a string and stores it for later access;
    9. create the substitution parameter index mapping.
    If the analysis performed in step 3 determines that rewriting is not necessary, the following three steps are skipped, and the original where clause simply is stored.
    Parameters:
    
    where - An unprocessed where clause which will be scanned, parsed, and possibly rewritten. Should not include the leading where keyword.
    
    parameters - Query substitution parameters for the where clause.
    
    paramTypes - The query substitution parameter types.
    
    dialect - Database dialect in use.
    
    overload - true to manually overload user-defined functions.
    
    informational - Flag indicating preprocessing is analytical only and query will not be executed.
    indexedFields - The list of indexed fields. In all cases, except for indexed FIND queries:
    
    t.f <= ? and ? >= t.f expressions are always evaluated to true;
    
    t.f < ? and ? > t.f expressions are equvalent to t.f <> ?
    
    because the unknown value (?) is sorted high in P4GL index.
    In the case of FIND queries where the compared field is not part of the current index, P4GL has a flaw that evaluates the mentioned expressions:
    
    t.f <= ? and ? >= t.f to true only if t.f is unknown
    
    t.f < ? and ? > t.f are always false.
    Throws:
    
    PersistenceException - if there is any error rewriting the where clause.
  - fixEmptyContains
```
private HQLAst fixEmptyContains(HQLAst root,
                                java.lang.Object[] parameters)
```
    Replaces contains function node with false is the second argument is an empty string.
    
    Parameters:
    
    root - The parsed FQL root.
    
    parameters - The query parameters.
    
    Returns:
    
    the new root.
  - simplifyProperties
```
private void simplifyProperties(HQLAst root,
                                boolean eliminateUpper,
                                boolean eliminateRtrim)
```
    Eliminates unneeded [upper] functions for case-insensitive properties and [rtrim] functions for automatically rtrimmed properties.
    
    Parameters:
    
    root - The parsed FQL root.
    
    eliminateUpper - true if upper functions should be eliminated
    
    eliminateRtrim - true if rtrim functions should be eliminated
  - normalizeTernary
```
private HQLAst normalizeTernary(HQLAst root,
                                java.lang.Object[] parameters)
```
    Normalize a ternary clause into an equivalent logical expression.
    
    Parameters:
    
    root - The parsed FQL root.
    
    parameters - The query parameters.
    
    Returns:
    
    the new root.
  - checkFindByRowid
```
private boolean checkFindByRowid(HQLAst root)
```
    Analyze the query preprocessed tree and checks if it represents a simple ROWID/RECID lookup.
    A simple ROWID/RECID lookup query only test for equality of the id field.
    
    Parameters:
    
    root - The root of the tree obtained from preprocessing the FQL query.
    
    Returns:
    
    true if the root represent the tree of a simple ROWID/RECID lookup query and false for any other kind of query.
  - checkUniqueFind
```
private UniqueIndexLookup checkUniqueFind()
```
    Check if the where clause is a look-up over a unique index.
    The goal here is to identify a common business logic pattern: find by an unique index, usually primary. The implementation doesn't detect if the where clauses combination suggest that zero or one record is expected. It just checks if the property matches match an unique index. Callers rely on this. Extending the method with heuristics for uniqueness beyond unique indexes may cause problems.
    
    Returns:
    
    true if the where clause is a conjunction of equalities covering all the fields of an unique index.
  - parse
```
private HQLAst parse()
              throws PersistenceException
```
    Scan and parse the input where clause and return it in the form of an abstract syntax tree. Rewriting is not performed at this stage.
    
    Returns:
    
    AST representing the original where clause.
    
    Throws:
    
    PersistenceException - if there is any error parsing the FQL.
  - inlineReferenceSubs
```
private java.util.List<FQLPreprocessor.PropertyPair> inlineReferenceSubs(HQLAst root,
                                                                         java.lang.String[] referenceSubs)
```
    Given an array containing one or more strings and zero or more nulls, replace those query substitution parameters in the where clause AST which positionally coincide with the non-null strings in the array. Each non-null string in the array represents a field reference to a specific DMO property. The SUBST AST node whose index coincides with that of a field reference in the array is replaced with an ALIAS node which has a PROPERTY child. If the field reference represents an extent field element, the PROPERTY node has an LBRACKET child and an INDEX grandchild.
    
    Parameters:
    
    root - FQL AST root node.
    
    referenceSubs - Array of field references and nulls.
    
    Returns:
    
    A list of pairs of properties (belonging to different tables) whose equality is guaranteed by the where predicate. These will be used to simplify the sort order when the SQL query is composed.
  - annotateParameters
```
private void annotateParameters(HQLAst root,
                                FqlType[] paramTypes)
```
    Walk the FQL AST, annotating query substitution parameter nodes with their data types as they are visited. The annotation name used for this is datatype.
    
    Parameters:
    
    root - Root AST node at which we begin the walk.
    
    paramTypes - The type of each substitution parameter.
  - collectPropertyMatches
```
private void collectPropertyMatches(HQLAst root)
```
    Walk the where clause AST and collect all simple property matches. This can be a single, binary, equality comparison of a database property to a substitution parameter or a literal value; or it can be a group of such comparisons ANDed together. Functions enclosing alias and property references are ignored. If any other expression is encountered, the analysis is aborted and no property matches are stored.
    The purpose of this collection is to conduct a rudimentary analysis of the complexity of the where clause and its suitability to participate as a sub-expression in a server-side join.
    
    Parameters:
    
    root - FQL AST root node.
  - mainWalk
```
private HQLAst mainWalk(HQLAst root,
                        java.lang.Object[] parameters,
                        FqlType[] paramTypes,
                        Dialect dialect,
                        boolean overload)
                 throws PersistenceException
```
    Walk the AST depth-first from root to leaves and rewrite certain nodes. The following modifications are made in place in the given AST:
    - A node which represents the qualified name of a DMO text property is restructured such that a new node representing an SQL trimming function is inserted between the qualified property name and its existing parent. A string node representing the characters to be trimmed is inserted as the property name's next sibling (i.e., the second parameter to the trimming function).
    - The first child of a FROM node represents the unqualified DMO interface name provided by business logic as part of a subselect phrase. This must be replaced with the unqualified name of the the DMO implementation class which implements this interface. The second child of the FROM node represents the record buffer alias which uniquely identifies the record buffer in scope. This information is used to retrieve the buffer and determine the DMO implementation name to use.
    Parameters:
    
    root - Root node of the AST for the FQL expression.
    
    parameters - Query substitution parameters for the where clause.
    
    paramTypes - The query substitution parameter types.
    
    dialect - Database dialect in use.
    
    overload - true to manually overload user-defined functions.
    
    Returns:
    
    The new root node of the AST for the FQL expression (it may change during processing).
    
    Throws:
    
    PersistenceException - if any error occurred during rewriting the AST.
    
    java.lang.IllegalArgumentException - if an alias encountered in the where clause is not mapped in the buffer manager.
  - augmentForUnknownValue
```
private HQLAst augmentForUnknownValue(HQLAst root,
                                      Dialect dialect)
                               throws PersistenceException
```
    Walk the tree, which has been simplified/rolled-up simplifyUnknowns(Set) by now, and augment certain binary sub-expressions to match Progress' unknown value semantics.
    
    Parameters:
    
    root - Root node of the AST for the FQL expression.
    
    dialect - Database dialect in use.
    
    Returns:
    
    The new root node of the AST for the FQL expression (it may change during processing).
    
    Throws:
    
    PersistenceException - if any error occurred during rewriting the AST.
  - honorDisjunctiveForm
```
private HQLAst honorDisjunctiveForm(HQLAst root)
```
    The method receives a HQLAst and searches for augmented nodes and rewrites them if possible. A node is augmented if it has the "augmented" annotation (see #augmentForUnknownValue(HQLAst)). The reconstruct occurs when only two augmented nodes are present, even if there are other conditions in the clause. At the same time, the augmented nodes must have the same AND parent. This method converts the following construct [ (t1.f1 = t2.f2 or (t1.f1 is null and t2.f2 is null)) and (t1.f3 = t2.f4 or (t1.f3 is null and t2.f4 is null)) ] into it's DNF (Disjunctive Normal Form) [ (t1.f1 = t2.f2 and t1.f3 = t2.f4) or (t1.f1 = t2.f2 and (t1.f3 is null and t2.f4 is null)) or ((t1.f1 is null and t2.f2 is null) and t1.f3 = t2.f4) or ((t1.f1 is null and t2.f2 is null) and (t1.f3 is null and t2.f4 is null)) ] which is a very specific case where two character fields are compared and augmented. There are only a few cases that are handled: a. There are only two augmented nodes. Reconstruction is as mentioned above. [ (t1.f1 = t2.f2 or (t1.f1 is null and t2.f2 is null)) and (t1.f3 = t2.f4 or (t1.f3 is null and t2.f4 is null)) ] b. There are additional conditions in the clause. Reconstruction is as mentioned above, the parent of the construct becomes the next AND and the clause will look like () OPERATOR . [ (t1.f1 = t2.f2 or (t1.f1 is null and t2.f2 is null)) and (t1.f3 = t2.f4 or (t1.f3 is null and t2.f4 is null)) OPERATOR ] There are also cases that are not handled: a. The parent of (t1.f1 = t2.f2 or (t1.f1 is null and t2.f2 is null)) is the first OR, while the parent of (t1.f3 = t2.f4 or (t1.f3 is null and t2.f4 is null)) is the first AND. [ t2.f5 = '' or (t1.f1 = t2.f2 or (t1.f1 is null and t2.f2 is null)) and (t1.f3 = t2.f4 or (t1.f3 is null and t2.f4 is null)) ] b. There are multiple augmented nodes, even if the two pairs of augmented nodes do not interfere with each other. [ ((t1.f1 = t2.f2 or (t1.f1 is null and t2.f2 is null)) and (t1.f3 = t2.f4 or (t1.f3 is null and t2.f4 is null))) or ((p1.f1 = p2.f2 or (p1.f1 is null and p2.f2 is null)) and (p1.f3 = p2.f4 or (p1.f3 is null and p2.f4 is null))) ]
    
    Parameters:
    
    root - Root node of the AST for the FQL expression.
    
    Returns:
    
    The new root node of the AST for the FQL expression (it may change during processing).
  - duplicateAugmentedOperand
```
private void duplicateAugmentedOperand(HQLAst source,
                                       HQLAst parent)
```
    Duplicate the given source operand node and graft the duplicate under parent. If source represents an extent field, annotate the duplicate node to indicate that an index check node should not be created (it would be redundant) when rewriting the alias node.
    
    Parameters:
    
    source - Original alias node (or enclosing function).
    
    parent - Parent node onto which to graft the duplicate of source as a child.
  - isMandatoryProperty
```
private boolean isMandatoryProperty(HQLAst alias,
                                    HQLAst property)
```
    Determine whether the given property in the context of the DMO class represented by the given buffer alias represents a mandatory (i.e., non-nullable) database column.
    
    Parameters:
    
    alias - Buffer alias AST
    
    property - Property AST.
    
    Returns:
    
    true if the property is mandatory, else false.
  - simplifyUnknowns
```
private java.util.Set<HQLAst> simplifyUnknowns(java.util.Set<HQLAst> unknowns)
```
    Get rid of unknowns in an FQL AST by evaluating relations in which these unknowns participate.
    
    Parameters:
    
    unknowns - Set of FQL nodes which represent all unknowns in the FQL AST. Nodes can be substitution parameters or whole statements which evaluate to unknown values.
    
    Returns:
    
    Set of FQL BOOL_TRUE and BOOL_FALSE nodes which were created during the simplifications of unknowns. May be null.
  - makeExplicitCast
```
private void makeExplicitCast(HQLAst parent,
                              int index,
                              Dialect dialect)
```
    Replaces the specified child node of a given parent with cast(? as <datatype>) if it represents a substitution parameter. E.g. the element will be replaced with cast(? as big_decimal) is we have a decimal variable.
    
    Parameters:
    
    parent - Parent of the node for which the cast must be done.
    
    index - Index of the child element.
    
    dialect - The dialect the query will be using.
  - trySimplifyBooleans
```
private HQLAst trySimplifyBooleans(HQLAst booleanOperand,
                                   HQLAst root)
                            throws AstException
```
    Tries to roll up subexpressions according to the following rules:
    - {condition} or false --> {condition}
    - {condition} or true --> true
    - {condition} and true --> {condition}
    - {condition} and false --> false
    If an expression has been rolled up to a boolean value, it tries to roll this value up with other conditions and so on.
    Parameters:
    
    booleanOperand - A node which represents a boolean operand in the expressions above.
    
    root - The root node of the whole FQL tree.
    
    Returns:
    
    The new root node of the whole FQL tree (the root node may be replaced if we have rolled up the first-level leaves).
    
    Throws:
    
    AstException - If there is any error grafting subtrees in the process of restructuring the subtree.
  - inlineDenormalizedField
```
private void inlineDenormalizedField(HQLAst ast,
                                     java.lang.Object[] parameters)
```
    Replace legacy indexed property with extent with custom property. Mark AST as inlined.
    
    Parameters:
    
    ast - A node which represents a denormalized field with extent.
    
    parameters - Query substitution parameters for the where clause.
  - inlineSubstitutionParameter
```
private int inlineSubstitutionParameter(HQLAst ast,
                                        java.lang.Object[] parameters,
                                        Dialect dialect)
```
    Attempt to inline a single query substitution parameter, if it is a numeric, text, or date type. This involves retasking a substitution parameter node to a be a different type, and changing its text, so that the original placeholder (?) is replaced with the text of the parameter's value. The node is annotated as "inlined" to enable downstream processing to accurately track the remaining placeholders.
    
    Parameters:
    
    ast - AST node which represents the query substitution parameter to be inlined.
    
    parameters - The array of substitution parameters from which the value of the inlined parameter will be determined.
    
    dialect - Database dialect in use.
    
    Returns:
    
    The FQL type of the inlined parameter, or SUBST if the parameter wasn't inlined.
  - manuallyOverload
```
private void manuallyOverload(HQLAst function)
                       throws PersistenceException
```
    Manually disambiguate a user defined function by taking its overloaded function name and data type signature and replacing the name in its AST with a unique name generated when the function was registered.
    
    Parameters:
    
    function - AST node for the function.
    
    Throws:
    
    PersistenceException - if there is an error determining the data type of any parameter of the function.
  - injectComputedColumn
```
private boolean injectComputedColumn(HQLAst astNode)
                              throws AstException
```
    Given an AST which represents a qualified or an unqualified text property, replace the property's text (the property name) with a name which represents a computed column. The computed column is a mechanism used by some databases to embed expressions into a synthetic column, particularly for use in index definitions.
    If the property reference is already embedded within an upper() function call, that call is discarded if it is redundant with the computed column definition.
    
    Parameters:
    
    astNode - Qualified or unqualified property AST node.
    
    Returns:
    
    true if the computed column reference was injected; false if the current database dialect does not use computed columns, or if the given property is not a text property.
    
    Throws:
    
    AstException - if there is an error restructuring the alias node or its parent node.
  - analyzeComposites
```
private java.util.Map<HQLAst,java.lang.String> analyzeComposites(HQLAst root)
```
    Analyze the AST generated for the FQL expression, identifying those subtrees which are targets for conversion. A subtree is a target if it is an alias whose first child is a property reference with a subscript, AND the alias/property combination is associated with a composite element in the ORM configuration.
    The AST subtree structure which represents our target is as follows:
```
    ALIAS
    |
    +--PROPERTY
       |
       +--LBRACKET
          |
          +--{...} (SUBST or NUM_LITERAL)
 
```
    In its original form, this would look like:
```
    alias.property[subscript]
 
```
    If any such constructs are identified, they are added to a map of targets and returned.
    Parameters:
    
    root - Root node of the AST for the FQL expression.
    
    Returns:
    
    Map of target AST subtrees to composite names, or null if no targets were found. The composite names are retrieved by the DatabaseManager from the appropriate ORM configurations.
  - getDenormalizedFields
```
private java.lang.Iterable<HQLAst> getDenormalizedFields(HQLAst root)
```
    Get list of denormalized fields with extent for where clause AST.
    
    Parameters:
    
    root - Root node of the AST for the FQL expression.
    
    Returns:
    
    List of AST of denormalized fields with extent.
  - addRestrictionProperty
```
private void addRestrictionProperty(java.lang.String entity,
                                    java.lang.String property)
```
    Add the given property name to the set of properties used by this where clause as restriction criteria. Each set of properties is mapped to the name of the DMO entity with which the property is associated.
    In the current implementation, the nature of the restriction is not preserved (e.g., equality match, function parameter, etc.).
    
    Parameters:
    
    entity - DMO entity containing the given property.
    
    property - Name of a property used by this where clause as a restrictive criterion.
  - restructure
```
private HQLAst restructure(HQLAst root,
                           java.util.Map<HQLAst,java.lang.String> targets)
                    throws PersistenceException
```
    Restructure the AST subtrees (if any) defined as rewrite targets by the composite analysis step. This involves the expansion of an expression, for instance:...
```
    OR [ or ]
    |
    +--EQUALS [ = ]
    |  |
    |  +--ALIAS [ alias ]
    |  |  |
    |  |  +--PROPERTY [ propertyABC ]
    |  |     |
    |  |     +--LBRACKET [ [ ]
    |  |        |
    |  |        +--NUM_LITERAL [ 0 ]
    |  |
    |  +--SUBST [ ? ]
    |
    +--EQUALS [ = ]
       |
       +--ALIAS [ alias ]
       |  |
       |  +--PROPERTY [ propertyABC ]
       |     |
       |     +--LBRACKET [ [ ]
       |        |
       |        +--NUM_LITERAL [ 1 ]
       |
       +--SUBST [ ? ]
 
```
    ...to an expression which consists of the modified original expression and index specifications added to the lop level of the tree using logical AND operators:
```
   AND [ and ]
   |
   +--AND [ and ]
   |  |
   |  +--LPARENS [ ( ]
   |  |  |
   |  |  +--OR [ or ]
   |  |     |
   |  |     +--EQUALS [ = ]
   |  |     |  |
   |  |     |  +--ALIAS [ alias_composite2_0 ]
   |  |     |  |  |
   |  |     |  |  +--PROPERTY [ propertyABC ]
   |  |     |  |
   |  |     |  +--SUBST [ ? ]
   |  |     |
   |  |     +--EQUALS [ = ]
   |  |        |
   |  |        +--ALIAS [ alias_composite2_1 ]
   |  |        |  |
   |  |        |  +--PROPERTY [ propertyABC ]
   |  |        |
   |  |        +--SUBST [ ? ]
   |  |
   |  +--EQUALS [ = ]
   |     |
   |     +--FUNCTION [ index ]
   |     |   |
   |     |   +--ALIAS [ alias_composite2_0 ]
   |     |
   |     +--NUM_LITERAL [ 0 ]
   |
   +--EQUALS [ = ]
      |
      +--FUNCTION [ index ]
      |   |
      |   +--ALIAS [ alias_composite2_1 ]
      |
      +--NUM_LITERAL [ 1 ]
 
```
    This corresponds to the following expression expansion (for this expression, two composite targets will be passed to the function):
```
    alias.propertyABC[0] = ? or alias.propertyABC[1] = ?
 
```
    ...to this one:
```
    (alias_composite2_0.propertyABC = ? or
      alias_composite2_1.propertyABC = ?) and
      index(alias_composite2_0) = 0 and
      index(alias_composite2_1) = 1
 
```
    However, the infix example above is informational only; the generation of the final, infix form of the expression is performed in a later step (see emit(com.goldencode.p2j.persist.hql.HQLAst, boolean)).
    Parameters:
    
    targets - Map of AST subtrees targeted for rewriting by the analysis step. The map's keys are the subtrees themselves; the map's values are the names of the composite list entities retrieved by the DatabaseManager.
    
    root - The root node of the AST of the whole FQL expression.
    
    Returns:
    
    The (possible new) root node of the restructured ASTs.
    
    Throws:
    
    PersistenceException - if there is any error restructuring the ASTs.
  - rewriteAlias
```
private void rewriteAlias(HQLAst alias,
                          HQLAst relRoot,
                          java.lang.String compName)
                   throws AstException
```
    Given a particular, target subtree and a composite list entity name, rewrite the AST as described in the restructure(com.goldencode.p2j.persist.hql.HQLAst, java.util.Map<com.goldencode.p2j.persist.hql.HQLAst, java.lang.String>) method.
    
    Parameters:
    
    alias - Alias subtree to be expanded.
    
    relRoot - The injection point for the index condition for the alias.
    
    compName - Name of the composite list associated with the combination of the alias name and property name encountered in the alias subtree.
    
    Throws:
    
    AstException - if there is any error grafting subtrees in the process of restructuring the subtree.
  - emit
```
private FQLExpression emit(HQLAst root,
                           boolean translate)
```
    Emit the restructured where clause AST into an infix notation expression, which is compliant with the FQL syntax supported by the ORM. This is the post-rewrite, "finished product" expression which will be returned by the getFQL() method.
    
    Parameters:
    
    root - Root of the restructured where clause AST.
    
    translate - Flag indicating if this processing is for a query translate. In this case, the dropAlias and replacementAlias is not used.
    
    Returns:
    
    Rewritten FQL where clause subexpression.
  - generateJoins
```
private java.util.LinkedHashSet<java.lang.String> generateJoins(java.util.Map<HQLAst,java.lang.String> targets)
```
    Define the set of ANSI-style join statements required to join the "master" DMO with one or more associated lists of composite elements. These will be integrated by the enclosing query into the overall FQL statement.
    Duplicates are eliminated. The order in which joins are detected is preserved in the resulting data structure, such that later iterations over the set will return these in the same order in which they were added.
    
    Parameters:
    
    targets - Map of AST subtrees targeted for rewriting by the analysis step. The map's keys are the subtrees themselves; the map's values are the names of the composite list entities retrieved by the DatabaseManager.
    
    Returns:
    
    Set of join subexpression strings. May be empty if no targets were specified, but will not be null.
  - generateJoin
```
private java.lang.String generateJoin(java.lang.String compName,
                                      java.lang.String alias,
                                      java.lang.String verboseAlias)
```
    Generate a single FQL subexpression for an ANSI-style join, which joins a "master" DMO record with an associated list of composite elements.
    
    Parameters:
    
    compName - Name of the associated list of composite elements.
    
    alias - Alias for the "master" DMO record to which the composite list is to be joined.
    
    verboseAlias - Verbose alias name, including the composite portion and subscript qualifier.
    
    Returns:
    
    Join text snippet.
  - createParameterIndices
```
private ParameterIndices createParameterIndices(HQLAst root,
                                                java.lang.Object[] parameters)
```
    Create the mapping of substitution parameters to their corresponding substitution placeholders in the rewritten FQL where clause. These placeholders (?) may have been reordered or removed (due to inlining) during the rewrite process.
    During parsing of the FQL clause, an index annotation was added to each AST of type SUBST (token type for the query substitution parameter placeholder), denoting that placeholder's position in the original where clause. We now walk the rewritten AST, extracting this annotation and storing it in a new list. The resulting array defines the new order of the substitution parameters. For parameters which were dropped, due to inlining, a null placeholder will appear in the new list.
    
    Parameters:
    
    root - Root node of the rewritten where clause AST.
    
    parameters - Query substitution parameters for the where clause.
    
    Returns:
    
    Object which maps new query substitution parameter positions to their positions in the original parameters array. These indices are zero-based.
  - isBinaryOperator
```
private boolean isBinaryOperator(Aast ast)
```
    Convenience method to detect whether an AST represents a binary operator, based on its token type.
    
    Parameters:
    
    ast - AST node to test.
    
    Returns:
    
    true if the AST's token type indicates a binary operator, else false.
  - isOppositeOperandNullable
```
private boolean isOppositeOperandNullable(HQLAst ast,
                                          int index)
```
    Given an AST and its index, and assuming it is one of two operands in a binary comparison, indicate whether the opposite operand is nullable. It is considered nullable if it is not a non-nullable DMO property.
    TODO: currently, we only test if the property is the reserved, primary key property. We should augment this test to check for other non-nullable properties.
    
    Parameters:
    
    ast - The operand opposite the operand we wish to test.
    
    index - The index of ast among its siblings. This must be 0 or 1, since the expression is binary.
    
    Returns:
    
    true if the operand opposite ast is nullable, else false.
  - createAstNode
```
private static HQLAst createAstNode(int type,
                                    java.lang.String text,
                                    HQLAst parent)
```
    Utility method for creating a designed HQLAst node. Optionally the newly created node is grafted to a parent as the last child.
    
    Parameters:
    
    type - The type of the new HQLAst node.
    
    text - The text of the new HQLAst node.
    
    parent - The parent of the new HQLAst node (if not null).
    
    Returns:
    
    the newly created and optionally grafted HQLAst node.
  - isUDF
```
private static boolean isUDF(Dialect dialect,
                             HQLAst n)
```
    Check if node represents UDF.
    
    Parameters:
    
    dialect - database dialect
    
    n - node to be checked
    
    Returns:
    
    true if node represents UDF.
  - isUDFArgument
```
private static boolean isUDFArgument(Dialect dialect,
                                     HQLAst n)
```
    Check if node represents UDF argument.
    
    Parameters:
    
    dialect - database dialect
    
    n - node to be checked
    
    Returns:
    
    true if node represents UDF argument.

Class FQLPreprocessor

Nested Class Summary

Field Summary

Fields inherited from interface com.goldencode.p2j.persist.hql.HQLParserTokenTypes

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

GUARDED

LOG

NOP_INSTANCE

overloadedFunctions

TERNARY_LOGICAL_EXP_TEMPLATE

TERNARY_COMPARE_EXP_TEMPLATE

cacheWithArgs

cacheNoArgs

astCache

database

dropAlias

replacementAlias

defaultBuffers

dropAliases

replacementAliases

ansiJoins

hasContains

fql

inline

inlinedTernary

paramIndices

restrictionProperties

earlyPublishEntities

propertyMatches

findByRowid

uniqueIndexLookup

findByRowidValue

bufferMap

substPairs

queryProperties

dependsOnSessionAttribute

nonConstantContains

Constructor Detail

FQLPreprocessor

FQLPreprocessor

Method Detail

get

registerFunction

getRegisteredFunction

translate

isConstant

getFQL

getSubstPairs

getQueryProperties

isDependsOnSessionAttribute

isFindByRowid

getFindByRowid

isUniqueFind

getUniqueIndexLookup

initializeCache

getParameterIndices

ansiJoins

hasAnsiJoins

hasContains

hasNonConstantContains

getEarlyPublishEntities

getPropertyMatches

getRestrictionProperties

wasInlined

lookupBuffer

preprocess

fixEmptyContains

simplifyProperties

normalizeTernary

checkFindByRowid

checkUniqueFind

parse

inlineReferenceSubs

annotateParameters

collectPropertyMatches

mainWalk

augmentForUnknownValue