com.saxonica.expr.ee

## Class OptimizerEE

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

- All Implemented Interfaces:
    Serializable

      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.
  See Also:
    Serialized Form

- - ### Field Summary

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

      `config, FULL_OPTIMIZATION, NO_OPTIMIZATION`

  - ### Constructor Summary

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

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `checkStreamability(XSLTemplate sourceTemplate, Template compiledTemplate)` Check the streamability of a template
    `Expression` | `compileToByteCode(Expression expr, 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` | `extractGlobalVariables(Expression body, ExpressionVisitor visitor, PromotionOffer offer)` Extract subexpressions from the body of a function that can be evaluated as global variables
    `Expression` | `generateMultithreadedInstruction(Expression instruction)` Generate a multi-threaded version of an instruction.
    `int` | `isIndexableFilter(Expression filter)` Test whether a filter predicate is indexable.
    `Expression` | `makeCastableToList(Expression operand, SchemaType targetType, boolean allowsEmpty)` Make an expression castable check to a union type.
    `Expression` | `makeCastableToUnion(Expression operand, SchemaType targetType, boolean allowsEmpty)` Make an expression castable check to a union type.
    `Expression` | `makeCastToUnion(Expression operand, SchemaType targetType, boolean allowsEmpty)` Make an expression that casts to a union type.
    `FunctionItem` | `makeCastToUnion(UnionType type, NamespaceResolver resolver)`
    `Expression` | `makeConditionalDocumentSorter(DocumentSorter sorter, SlashExpression path)` Make a conditional document sorter.
    `void` | `makeCopyOperationsExplicit(Expression parent, Expression child)` In streaming mode, make the copy operation applied to subexpressions of a complex-content sequence constructor into explicit copy-of operations.
    `Sequence` | `makeIndexedValue(SequenceIterator iter)` Create an indexed value
    `RuleTarget` | `makeInversion(Pattern pattern, Template template, NodeTest nodeTest)` Generate the inversion of the expression comprising the body of a template rules.
    `Expression` | `makeStreamingApplyTemplates(ApplyTemplates inst, List<String> reasonsForFailure)` Make a streaming applyTemplates instruction.
    `Expression` | `optimizeCopy(Expression select)` Attempt to optimize a copy operation.
    `Expression` | `optimizeForExpressionForStreaming(ForExpression expr)` In streaming mode, optimizer a ForExpression for streaming.
    `BinaryExpression` | `optimizeGeneralComparison(GeneralComparison gc, boolean backwardsCompatible)` Simplify a GeneralComparison expression
    `Expression` | `optimizeQuantifiedExpressionForStreaming(QuantifiedExpression expr)` In streaming mode, optimize a QuantifiedExpression for streaming.
    `Expression` | `optimizeStreamingCopy(Expression select)` Given a select expression, determine whether it is a candidate for sequential processing, and if so, return a StreamingCopy expression that does the work.
    `boolean` | `processSwitchCondition(Expression condition, Expression action, com.saxonica.expr.ee.OptimizerEE.SwitchCaseInfo switchCaseInfo)`
    `Expression` | `promoteExpressionsToGlobal(Expression body, ExpressionVisitor visitor)` Identify expressions within a function or template body that can be promoted to be evaluated as global variables.
    `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, ExpressionVisitor.ContextItemType contextItemType)` Replace a function call by the body of the function, assuming all conditions for inlining the function are satisfied
    `Expression` | `trySwitch(Choose choose, StaticContext env)` 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, getOptimizationLevel, isVariableReplaceableByDot, makeCastToList, setOptimizationLevel, 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

    - #### makeCastToUnion

          public FunctionItem makeCastToUnion(UnionType type,
                                     NamespaceResolver resolver)

      Overrides:
        `makeCastToUnion` in class `Optimizer`

    - #### optimizeGeneralComparison

          public BinaryExpression optimizeGeneralComparison(GeneralComparison gc,
                                                   boolean backwardsCompatible)

      Simplify a GeneralComparison expression
      Overrides:
        `optimizeGeneralComparison` in class `Optimizer`
      Parameters:
        `gc` - the GeneralComparison to be simplified
        `backwardsCompatible` - true if in 1.0 compatibility mode
      Returns:
        the simplified expression

    - #### optimizeCopy

          public Expression optimizeCopy(Expression select)
                                  throws XPathException

      Attempt to optimize a copy operation. Return null if no optimization is possible.
      Overrides:
        `optimizeCopy` 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`

    - #### optimizeStreamingCopy

          public Expression optimizeStreamingCopy(Expression select)
                                           throws XPathException

      Given a select expression, determine whether it is a candidate for sequential processing, and if so, return a StreamingCopy expression that does the work.

      To qualify, the select expression must be a path expression that starts with a call on doc() or document(), and whose subsequent steps are all axis steps using the child, descendant, and attribute axes only; there must be no predicates; it must match either elements only, or attributes only
      Parameters:
        `select` - the select expression to be examined
      Returns:
        either null if no optimization is possible, or a StreamingCopy expression
      Throws:
        `XPathException` - if called for an expression that does not qualify for this optimization

    - #### makeCopyOperationsExplicit

          public void makeCopyOperationsExplicit(Expression parent,
                                        Expression child)
                                          throws XPathException

      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 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.
        `child` - The expression that is to be wrapped in an implicit copy-of, if it is suitable.
      Throws:
        `XPathException`

    - #### checkStreamability

          public void checkStreamability(XSLTemplate sourceTemplate,
                                Template 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

    - #### makeCastToUnion

          public Expression makeCastToUnion(Expression operand,
                                   SchemaType targetType,
                                   boolean allowsEmpty)

      Make an expression that casts to a union type. Not available in Saxon-HE
      Overrides:
        `makeCastToUnion` in class `Optimizer`

    - #### makeCastableToUnion

          public Expression makeCastableToUnion(Expression operand,
                                       SchemaType targetType,
                                       boolean allowsEmpty)

      Make an expression castable check to a union type. Not available in Saxon-HE
      Overrides:
        `makeCastableToUnion` in class `Optimizer`

    - #### makeCastableToList

          public Expression makeCastableToList(Expression operand,
                                      SchemaType targetType,
                                      boolean allowsEmpty)

      Make an expression castable check to a union type. Not available in Saxon-HE
      Overrides:
        `makeCastableToList` in class `Optimizer`

    - #### optimizeForExpressionForStreaming

          public Expression optimizeForExpressionForStreaming(ForExpression expr)
                                                       throws XPathException

      In streaming mode, optimizer 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.
      Throws:
        `XPathException`

    - #### 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)
                                                throws XPathException

      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
      Throws:
        `XPathException`

    - #### 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

    - #### convertToFilterExpression

          public FilterExpression convertToFilterExpression(SlashExpression pathExp,
                                                   TypeHierarchy th)
                                                     throws XPathException

      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
      Throws:
        `XPathException`

    - #### 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 Sequence 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`

    - #### 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,
                                         ExpressionVisitor.ContextItemType 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.

    - #### promoteExpressionsToGlobal

          public Expression promoteExpressionsToGlobal(Expression body,
                                              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:
        `body` - the body of the template or function
        `visitor` - the expression visitor
      Returns:
        the expression after subexpressions have been promoted to global variables
      Throws:
        `XPathException`

    - #### trySwitch

          public Expression trySwitch(Choose choose,
                             StaticContext env)

      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
        `env` - the static context
      Returns:
        the result of optimizing this (the original expression if no optimization was possible)

    - #### processSwitchCondition

          public boolean processSwitchCondition(Expression condition,
                                       Expression action,
                                       com.saxonica.expr.ee.OptimizerEE.SwitchCaseInfo switchCaseInfo)

    - #### extractGlobalVariables

          public Expression extractGlobalVariables(Expression body,
                                          ExpressionVisitor visitor,
                                          PromotionOffer offer)
                                            throws XPathException

      Extract subexpressions from the body of a function that can be evaluated as global variables
      Overrides:
        `extractGlobalVariables` in class `Optimizer`
      Parameters:
        `body` - an expression with no dependencies other than on global variables (already checked by the caller)
        `offer` - The PromotionOffer. Will be marked to indicate whether any action was taken
      Returns:
        a reference to the new global variable if a variable has been created, or null if not
      Throws:
        `XPathException`

    - #### makeStreamingApplyTemplates

          public Expression makeStreamingApplyTemplates(ApplyTemplates inst,
                                               List<String> reasonsForFailure)
                                                 throws XPathException

      Make a streaming applyTemplates instruction. Supported in Saxon-EE only
      Overrides:
        `makeStreamingApplyTemplates` in class `Optimizer`
      Parameters:
        `inst` - the unoptimized applyTemplates instruction
        `reasonsForFailure` - a list to which diagnostic messages will be added
      Returns:
        the expression converted for streaming
      Throws:
        `XPathException` - if an error is detected

    - #### makeInversion

          public RuleTarget makeInversion(Pattern pattern,
                                 Template template,
                                 NodeTest nodeTest)
                                   throws XPathException

      Generate the inversion of the expression comprising the body of a template rules. Supported in Saxon-EE only
      Overrides:
        `makeInversion` in class `Optimizer`
      Parameters:
        `pattern` - the match pattern of this template rule
        `template` - the template to be inverted
        `nodeTest` - the static item type of the context node of the template
      Throws:
        `XPathException`

    - #### 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(Expression expr,
                                     String objectName,
                                     int evaluationMethods)

      Generate Java byte code for an expression
      Overrides:
        `compileToByteCode` in class `Optimizer`
      Parameters:
        `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

Copyright (c) 2004-2013 Saxonica Limited. All rights reserved.