Package com.saxonica.ee.optim

## Class OptimizerEE

- java.lang.Object
- - net.sf.saxon.expr.parser.Optimizer
  - - com.saxonica.ee.optim.OptimizerEE

-     public class OptimizerEE
      extends Optimizer

  This class performs a number of optimizations that are specific to the Saxon-EE product. The relevant methods override dummy methods (that generally perform no optimization) in the superclass, which is used by Saxon-HE.

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.expr.parser.Optimizer

      `config, tracing`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `OptimizerEE​(Configuration config)` | Create the Saxon-EE optimizer

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `assessFunctionStreamability​(XSLFunction sourceFunction, UserFunction compiledFunction)` | Assess whether a declared-streamable function is actually streamable.
    `void` | `checkStreamability​(XSLTemplate sourceTemplate, TemplateRule compiledTemplate)` | Check the streamability of a template
    `Expression` | `compileToByteCode​(ICompilerService compilerService, Expression expr, java.lang.String objectName, int evaluationMethods)` | Generate Java byte code for an expression
    `Expression` | `convertPathExpressionToKey​(SlashExpression pathExp, ExpressionVisitor visitor)` | Examine a path expression to see whether it can be replaced by a call on the key() function; if so, generate an appropriate key definition and return the call on key().
    `FilterExpression` | `convertToFilterExpression​(SlashExpression pathExp, TypeHierarchy th)` | Convert a path expression such as a/b/c[predicate] into a filter expression of the form (a/b/c)[predicate].
    `Expression` | `eliminateCommonSubexpressions​(Expression in)` | Eliminate common subexpressions.
    `Sequence` | `evaluateStreamingArgument​(Expression expr, XPathContext context)` | Evaluate the streaming (first) argument of a streamable stylesheet function
    `int` | `gatherOrExpressions​(int commonParts, ExpressionVisitor visitor, ContextItemStaticInfo contextItemType, java.util.HashMap<Expression,​java.util.List<Expression>> map, java.util.List<Expression> otherExps, Expression expr)` | Try to convert a collection of comparisons connected by "or" operators into a single GeneralComparison
    `Expression` | `generateMultithreadedInstruction​(Expression instruction)` | Generate a multi-threaded version of an instruction.
    `void` | `injectByteCodeCandidates​(Expression expression)` |
    `int` | `isIndexableFilter​(Expression filter)` | Test whether a filter predicate is indexable.
    `Expression` | `makeByteCodeCandidate​(ExpressionOwner owner, Expression expr, java.lang.String objectName, int requiredEvaluationModes)` | Insert a ByteCodeCandidate into the expression tree.
    `Expression` | `makeConditionalDocumentSorter​(DocumentSorter sorter, SlashExpression path)` | Make a conditional document sorter.
    `void` | `makeCopyOperationsExplicit​(Expression parent, Operand childOp)` | In streaming mode, make the copy operation applied to subexpressions of a complex-content sequence constructor into explicit copy-of operations.
    `GroundedValue` | `makeIndexedValue​(SequenceIterator iter)` | Create an indexed value
    `Expression` | `optimizeForExpressionForStreaming​(ForExpression expr)` | In streaming mode, optimize a ForExpression for streaming.
    `Expression` | `optimizeGeneralComparison​(ExpressionVisitor visitor, GeneralComparison gc, boolean backwardsCompatible, ContextItemStaticInfo contextItemType)` | Optimize a GeneralComparison expression.
    `void` | `optimizeNodeSetPattern​(NodeSetPattern pattern)` |
    `Expression` | `optimizeNumberInstruction​(NumberInstruction ni, ContextItemStaticInfo contextInfo)` |
    `Expression` | `optimizeQuantifiedExpressionForStreaming​(QuantifiedExpression expr)` | In streaming mode, optimize a QuantifiedExpression for streaming.
    `Expression` | `optimizeSaxonStreamFunction​(ExpressionVisitor visitor, ContextItemStaticInfo cisi, Expression select)` | Attempt to optimize a copy operation.
    `Expression` | `optimizeValueComparison​(ValueComparison vc, ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Optimize a value comparison
    `void` | `prepareForStreaming​(Expression exp)` | Prepare an expression for streaming
    `Expression` | `promoteExpressionsToGlobal​(Expression expr, GlobalVariableManager globalVariableManager, ExpressionVisitor visitor)` | Identify expressions within a function or template body that can be promoted to be evaluated as global variables.
    `FilterExpression` | `reorderPredicates​(FilterExpression f, ExpressionVisitor visitor, ContextItemStaticInfo cisi)` | Consider reordering the predicates in a filter expression based on cost estimates and other criteria
    `Expression` | `tryGeneralComparison​(ExpressionVisitor visitor, ContextItemStaticInfo contextItemType, OrExpression orExpr)` | Try to convert an Or expression into a comparison with Literal sequence
    `Expression` | `tryIndexedFilter​(FilterExpression f, ExpressionVisitor visitor, boolean indexFirstOperand, boolean contextIsDoc)` | Try converting a filter expression to a call on the key function.
    `Expression` | `tryInlineFunctionCall​(UserFunctionCall functionCall, ExpressionVisitor visitor, ContextItemStaticInfo contextItemType)` | Replace a function call by the body of the function, assuming all conditions for inlining the function are satisfied
    `Expression` | `trySwitch​(Choose choose, ExpressionVisitor visitor)` | Try to convert a Choose expression (or an XQuery 3.0 switch) into an optimized switch

    - ### Methods inherited from class net.sf.saxon.expr.parser.Optimizer

      `getConfiguration, getOptimizerOptions, isOptionSet, isVariableReplaceableByDot, makeInversion, setOptimizerOptions, trace, trace`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### OptimizerEE

          public OptimizerEE​(Configuration config)

      Create the Saxon-EE optimizer
      Parameters:
        `config` - the Saxon-EE configuration

  - ### Method Detail

    - #### optimizeValueComparison

          public Expression optimizeValueComparison​(ValueComparison vc,
                                                    ExpressionVisitor visitor,
                                                    ContextItemStaticInfo contextInfo)
                                             throws XPathException

      Optimize a value comparison
      Overrides:
        `optimizeValueComparison` in class `Optimizer`
      Parameters:
        `vc` - the value comparison expression
        `visitor` - the expression visitor
        `contextInfo` - static context item information
      Returns:
        either the original value comparison, or an optimized equivalent
      Throws:
        `XPathException` - if things go wrong

    - #### optimizeGeneralComparison

          public Expression optimizeGeneralComparison​(ExpressionVisitor visitor,
                                                      GeneralComparison gc,
                                                      boolean backwardsCompatible,
                                                      ContextItemStaticInfo contextItemType)

      Optimize a GeneralComparison expression. Saxon-EE has a number of strategies for handling these; for example when comparing against a constant set of values, the expression is turned into a call on map:contains().
      Overrides:
        `optimizeGeneralComparison` in class `Optimizer`
      Parameters:
        `visitor` - the expression visitor
        `gc` - the GeneralComparison to be optimized
        `backwardsCompatible` - true if in 1.0 compatibility mode
      Returns:
        the simplified expression

    - #### optimizeSaxonStreamFunction

          public Expression optimizeSaxonStreamFunction​(ExpressionVisitor visitor,
                                                        ContextItemStaticInfo cisi,
                                                        Expression select)
                                                 throws XPathException

      Attempt to optimize a copy operation. Return null if no optimization is possible.
      Overrides:
        `optimizeSaxonStreamFunction` in class `Optimizer`
      Parameters:
        `select` - the expression that selects the items to be copied
      Returns:
        null if no optimization is possible, or an expression that does an optimized copy of these items otherwise
      Throws:
        `XPathException`

    - #### makeCopyOperationsExplicit

          public void makeCopyOperationsExplicit​(Expression parent,
                                                 Operand childOp)

      In streaming mode, make the copy operation applied to subexpressions of a complex-content sequence constructor into explicit copy-of operations. This makes constructs such as `<e><xsl:sequence select="y"/></e>` streamable, by using the same run-time logic as if xsl:copy-of had been used.
      Overrides:
        `makeCopyOperationsExplicit` in class `Optimizer`
      Parameters:
        `parent` - The parent expression of the expression that is to be wrapped in an implicit copy-of.
        `childOp` - The operand that is to be wrapped in an implicit copy-of, if it is suitable.

    - #### checkStreamability

          public void checkStreamability​(XSLTemplate sourceTemplate,
                                         TemplateRule compiledTemplate)
                                  throws XPathException

      Check the streamability of a template
      Overrides:
        `checkStreamability` in class `Optimizer`
      Parameters:
        `sourceTemplate` - the source of the template in the stylesheet tree
        `compiledTemplate` - the compiled template
      Throws:
        `XPathException` - if the template is declared streamable but does not satisfy the straming rules

    - #### optimizeForExpressionForStreaming

          public Expression optimizeForExpressionForStreaming​(ForExpression expr)

      In streaming mode, optimize a ForExpression for streaming. This is possible if the "in" part of the for expression does a downward selection of the streamed input, while the "return" part does not access the streamed input at all (specifically, if it has no dependencies on the context node). The expression is converted to streamable form by rewriting "for $t in S return f($t)" as "for-each S return f(.)". This depends on the generated for-each expression being streamable, which will not always be the case, for example if the return expression makes two downward selections from the range variable, or a non-downward selection.
      Overrides:
        `optimizeForExpressionForStreaming` in class `Optimizer`
      Parameters:
        `expr` - the expression to be optimized
      Returns:
        the optimized expression, or the original expression if no optimization was possible.

    - #### optimizeQuantifiedExpressionForStreaming

          public Expression optimizeQuantifiedExpressionForStreaming​(QuantifiedExpression expr)
                                                              throws XPathException

      In streaming mode, optimize a QuantifiedExpression for streaming. This is possible if the "select" part of the quantified expression does a downward selection of the streamed input, while the "satisfies" part does not access the streamed input at all (specifically, if it has no dependencies on the context node). The expression is converted to streamable form by rewriting "some $t in S satisfies f($t)" as "exists(for-each S return boolean(f(.)[.])", and likewise mutatis mutandis for "every $t....". This depends on the generated for-each expression being streamable, which will not always be the case, for example if the satisfies expression makes two downward selections from the range variable, or a non-downward selection.
      Overrides:
        `optimizeQuantifiedExpressionForStreaming` in class `Optimizer`
      Parameters:
        `expr` - the expression to be optimized
      Returns:
        the optimized expression, or the original expression if no optimization was possible.
      Throws:
        `XPathException`

    - #### convertPathExpressionToKey

          public Expression convertPathExpressionToKey​(SlashExpression pathExp,
                                                       ExpressionVisitor visitor)

      Examine a path expression to see whether it can be replaced by a call on the key() function; if so, generate an appropriate key definition and return the call on key(). If not, return null.
      Overrides:
        `convertPathExpressionToKey` in class `Optimizer`
      Parameters:
        `pathExp` - The path expression to be converted.
        `visitor` - The expression visitor
      Returns:
        the optimized expression, or null if no optimization is possible

    - #### tryIndexedFilter

          public Expression tryIndexedFilter​(FilterExpression f,
                                             ExpressionVisitor visitor,
                                             boolean indexFirstOperand,
                                             boolean contextIsDoc)

      Try converting a filter expression to a call on the key function. Return the supplied expression unchanged if not possible
      Overrides:
        `tryIndexedFilter` in class `Optimizer`
      Parameters:
        `f` - the filter expression to be converted
        `visitor` - the expression visitor, which must be currently visiting the filter expression f
        `indexFirstOperand` - true if the first operand of the filter comparison is to be indexed;
        `contextIsDoc` - true if the context item is known to be a document node
      Returns:
        the optimized expression, or the unchanged expression f if no optimization is possible

    - #### reorderPredicates

          public FilterExpression reorderPredicates​(FilterExpression f,
                                                    ExpressionVisitor visitor,
                                                    ContextItemStaticInfo cisi)
                                             throws XPathException

      Consider reordering the predicates in a filter expression based on cost estimates and other criteria
      Overrides:
        `reorderPredicates` in class `Optimizer`
      Parameters:
        `f` - the filter expression
        `visitor` - expression visitor
        `cisi` - information about the context item type
      Returns:
        either the original expression, or an optimized replacement
      Throws:
        `XPathException` - if things go wrong

    - #### convertToFilterExpression

          public FilterExpression convertToFilterExpression​(SlashExpression pathExp,
                                                            TypeHierarchy th)

      Convert a path expression such as a/b/c[predicate] into a filter expression of the form (a/b/c)[predicate]. This is possible whenever the predicate is non-positional. The conversion is useful in the case where the path expression appears inside a loop, where the predicate depends on the loop variable but a/b/c does not.
      Overrides:
        `convertToFilterExpression` in class `Optimizer`
      Parameters:
        `pathExp` - the path expression to be converted
        `th` - the type hierarchy cache
      Returns:
        the resulting filterexpression if conversion is possible, or null if not

    - #### isIndexableFilter

          public int isIndexableFilter​(Expression filter)

      Test whether a filter predicate is indexable.
      Overrides:
        `isIndexableFilter` in class `Optimizer`
      Parameters:
        `filter` - the predicate expression
      Returns:
        0 if not indexable; +1 if the predicate is in the form expression=value; -1 if it is in the form value=expression

    - #### makeIndexedValue

          public GroundedValue makeIndexedValue​(SequenceIterator iter)
                                         throws XPathException

      Create an indexed value
      Overrides:
        `makeIndexedValue` in class `Optimizer`
      Parameters:
        `iter` - the iterator that delivers the sequence of values to be indexed
      Returns:
        the indexed value
      Throws:
        `XPathException`

    - #### optimizeNodeSetPattern

          public void optimizeNodeSetPattern​(NodeSetPattern pattern)

      Overrides:
        `optimizeNodeSetPattern` in class `Optimizer`

    - #### prepareForStreaming

          public void prepareForStreaming​(Expression exp)
                                   throws XPathException

      Prepare an expression for streaming
      Overrides:
        `prepareForStreaming` in class `Optimizer`
      Parameters:
        `exp` - the expression to be prepared
      Throws:
        `XPathException`

    - #### evaluateStreamingArgument

          public Sequence evaluateStreamingArgument​(Expression expr,
                                                    XPathContext context)
                                             throws XPathException

      Evaluate the streaming (first) argument of a streamable stylesheet function
      Overrides:
        `evaluateStreamingArgument` in class `Optimizer`
      Parameters:
        `expr` - the expression supplied for the value of the streaming argument
        `context` - the XPath evaluation context of the caller
      Returns:
        the (nominal) result of the evaluation
      Throws:
        `XPathException`

    - #### makeConditionalDocumentSorter

          public Expression makeConditionalDocumentSorter​(DocumentSorter sorter,
                                                          SlashExpression path)

      Make a conditional document sorter. This optimization is attempted when a DocumentSorter is wrapped around a path expression
      Overrides:
        `makeConditionalDocumentSorter` in class `Optimizer`
      Parameters:
        `sorter` - an expression that sorts and deduplicates its operand
        `path` - the slash expression that is the operand of the sorter
      Returns:
        either the original sorter, if no optimization is possible; or a ConditionalSorter which first tests a condition, and performs the sort if the condition is true, or returns the unsorted operand if not. In practice the condition is always a test whether the first item in the path expression contains more than one item

    - #### tryInlineFunctionCall

          public Expression tryInlineFunctionCall​(UserFunctionCall functionCall,
                                                  ExpressionVisitor visitor,
                                                  ContextItemStaticInfo contextItemType)

      Replace a function call by the body of the function, assuming all conditions for inlining the function are satisfied
      Overrides:
        `tryInlineFunctionCall` in class `Optimizer`
      Parameters:
        `functionCall` - the functionCall expression
        `visitor` - the expression visitor
        `contextItemType` - the static type of the context item
      Returns:
        either the original expression unchanged, or an expression that consists of the inlined function body, with all function parameters bound as required.

    - #### trySwitch

          public Expression trySwitch​(Choose choose,
                                      ExpressionVisitor visitor)

      Try to convert a Choose expression (or an XQuery 3.0 switch) into an optimized switch
      Overrides:
        `trySwitch` in class `Optimizer`
      Parameters:
        `choose` - the Choose expression
      Returns:
        the result of optimizing this (the original expression if no optimization was possible)

    - #### gatherOrExpressions

          public int gatherOrExpressions​(int commonParts,
                                         ExpressionVisitor visitor,
                                         ContextItemStaticInfo contextItemType,
                                         java.util.HashMap<Expression,​java.util.List<Expression>> map,
                                         java.util.List<Expression> otherExps,
                                         Expression expr)

      Try to convert a collection of comparisons connected by "or" operators into a single GeneralComparison
      Parameters:
        `commonParts` - the number of common subexpressions found at this level
        `visitor` - the expression visitor
        `contextItemType` - static information about the context item type
        `map` - a map to be populated with comparison expressions, keyed on the common operand
        `otherExps` - a list to be populated with expressions in the "or" tree that are not comparison expressions, so they are retained "as is"
        `expr` - the Or expression to be optimized
      Returns:
        a tally of the common expressions so far

    - #### tryGeneralComparison

          public Expression tryGeneralComparison​(ExpressionVisitor visitor,
                                                 ContextItemStaticInfo contextItemType,
                                                 OrExpression orExpr)
                                          throws XPathException

      Try to convert an Or expression into a comparison with Literal sequence
      Overrides:
        `tryGeneralComparison` in class `Optimizer`
      Parameters:
        `visitor` - the expression visitor
        `contextItemType` - static information about the context item type
        `orExpr` - the Choose expression
      Returns:
        the result of optimizing the Or expression (the original expression if no optimization was possible)
      Throws:
        `XPathException`

    - #### promoteExpressionsToGlobal

          public Expression promoteExpressionsToGlobal​(Expression expr,
                                                       GlobalVariableManager globalVariableManager,
                                                       ExpressionVisitor visitor)
                                                throws XPathException

      Identify expressions within a function or template body that can be promoted to be evaluated as global variables.
      Overrides:
        `promoteExpressionsToGlobal` in class `Optimizer`
      Parameters:
        `expr` - the expression; either this expression or any subexpression might be promoted
        `visitor` - the expression visitor
      Returns:
        the expression after subexpressions have been promoted to global variables; or null if no action was taken
      Throws:
        `XPathException`

    - #### eliminateCommonSubexpressions

          public Expression eliminateCommonSubexpressions​(Expression in)

      Description copied from class: `Optimizer`
      Eliminate common subexpressions. Rewrites (contains(X, 'x') and contains(X, 'y')) as (let $vv:C := X return (contains($vv:C, 'x') and contains($vv:C, 'y'))). Dummy method; the optimization happens only in Saxon-EE.
      Overrides:
        `eliminateCommonSubexpressions` in class `Optimizer`
      Parameters:
        `in` - the expression to be optimized
      Returns:
        out the optimized expression (possibly the same as the input).

    - #### generateMultithreadedInstruction

          public Expression generateMultithreadedInstruction​(Expression instruction)

      Generate a multi-threaded version of an instruction. Supported in Saxon-EE only; ignored with no action in Saxon-HE and Saxon-PE
      Overrides:
        `generateMultithreadedInstruction` in class `Optimizer`
      Parameters:
        `instruction` - the instruction to be multi-threaded
      Returns:
        the multi-threaded version of the instruction

    - #### compileToByteCode

          public Expression compileToByteCode​(ICompilerService compilerService,
                                              Expression expr,
                                              java.lang.String objectName,
                                              int evaluationMethods)

      Generate Java byte code for an expression
      Overrides:
        `compileToByteCode` in class `Optimizer`
      Parameters:
        `compilerService` - the compiler service
        `expr` - the expression to be compiled
        `objectName` - the name of the object to be compiled, used as a hint for the Java class/method name
        `evaluationMethods` - The evaluation modes for which code is generated. Currently a subset of `Expression.PROCESS_METHOD`, `Expression.ITERATE_METHOD`. If no code is generated for a given evaluation method, the fallback implementation from the superclass is used.
      Returns:
        the compiled expression if possible, or null if compilation is not possible

    - #### makeByteCodeCandidate

          public Expression makeByteCodeCandidate​(ExpressionOwner owner,
                                                  Expression expr,
                                                  java.lang.String objectName,
                                                  int requiredEvaluationModes)

      Insert a ByteCodeCandidate into the expression tree. A ByteCodeCandidate monitors how many times it is executed, and after reaching a certain threshold, generates bytecode for faster evaluation of its target expression
      Overrides:
        `makeByteCodeCandidate` in class `Optimizer`
      Parameters:
        `owner` - the owning construct in the expression tree
        `expr` - the child (target) expression
        `objectName` - name to be used in forming the name of the bytecode class
        `requiredEvaluationModes` - the evaluation modes for which code should be generated
      Returns:
        a new ByteCodeCandidate if the expression is suitable for bytecode generation, or the supplied target expression otherwise.

    - #### injectByteCodeCandidates

          public void injectByteCodeCandidates​(Expression expression)

      Overrides:
        `injectByteCodeCandidates` in class `Optimizer`

    - #### optimizeNumberInstruction

          public Expression optimizeNumberInstruction​(NumberInstruction ni,
                                                      ContextItemStaticInfo contextInfo)

      Overrides:
        `optimizeNumberInstruction` in class `Optimizer`

    - #### assessFunctionStreamability

          public void assessFunctionStreamability​(XSLFunction sourceFunction,
                                                  UserFunction compiledFunction)

      Assess whether a declared-streamable function is actually streamable. This analysis takes no account of the actual function call, which is assessed later in the streaming adjunct for the UserFunctioncall class
      Overrides:
        `assessFunctionStreamability` in class `Optimizer`