Package net.sf.saxon.expr

## Class TryCatch

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.expr.TryCatch

- All Implemented Interfaces:
    `ExportAgent`, `Locatable`, `IdentityComparable`, `Traceable`

      public class TryCatch
      extends Expression

  This class implements a try/catch expression. It consists of a try expression, and a sequence of Nametest/Catch expression pairs. If the try expression succeeds, its result is returned; otherwise the error code of the exception is matched against each of the Nametests in turn, and the first matching catch expression is evaluated.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `TryCatch.CatchClause` |

  - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.expr.Expression

      `EFFECTIVE_BOOLEAN_VALUE, EVALUATE_METHOD, ITEM_FEED_METHOD, ITERATE_METHOD, MAX_COST, MAX_SEQUENCE_LENGTH, MAX_STRING_LENGTH, PROCESS_METHOD, staticProperties, UNBOUNDED_LOWER, UNBOUNDED_UPPER, UPDATE_METHOD, WATCH_METHOD`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `TryCatch​(Expression tryExpr)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addCatchExpression​(QNameTest test, Expression catchExpr)` |
    `boolean` | `allowExtractingCommonSubexpressions()` | Ask whether common subexpressions found in the operands of this expression can be extracted and evaluated outside the expression itself.
    `int` | `computeCardinality()` | Determine the cardinality of the function.
    `int` | `computeHashCode()` | Hashcode supporting equals()
    `Expression` | `copy​(RebindingMap rebindings)` | Copy an expression.
    `boolean` | `equals​(java.lang.Object other)` | Is this expression the same as another expression?
    `Item` | `evaluateItem​(XPathContext c)` | Evaluate as a singleton item
    `void` | `export​(ExpressionPresenter out)` | Diagnostic print of expression structure.
    `java.util.List<TryCatch.CatchClause>` | `getCatchClauses()` | Get the list of catch clauses
    `java.lang.String` | `getExpressionName()` | Get a name identifying the kind of expression, in terms meaningful to a user.
    `int` | `getImplementationMethod()` | An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process().
    `ItemType` | `getItemType()` | Determine the item type of the value returned by the function
    `java.lang.String` | `getStreamerName()` | Get the (partial) name of a class that supports streaming of this kind of expression
    `Expression` | `getTryExpr()` | Get the "try" expression
    `Operand` | `getTryOperand()` | Get the "try" operand
    `boolean` | `isInstruction()` | Ask whether this expression is an instruction.
    `boolean` | `isRollbackOutput()` |
    `SequenceIterator` | `iterate​(XPathContext c)` | Iterate over the results of the function
    `java.lang.Iterable<Operand>` | `operands()` | Get the immediate sub-expressions of this expression, with information about the relationship of each expression to its parent expression.
    `Expression` | `optimize​(ExpressionVisitor visitor, ContextItemStaticInfo contextInfo)` | Perform optimisation of an expression and its subexpressions.
    `void` | `process​(Outputter output, XPathContext context)` | Process the instruction, without returning any tail calls
    `void` | `setRollbackOutput​(boolean rollback)` |

    - ### Methods inherited from class net.sf.saxon.expr.Expression

      `addToPathMap, adoptChildExpression, checkedOperands, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeSpecialProperties, computeStaticProperties, dynamicError, effectiveBooleanValue, evaluateAsString, evaluatePendingUpdates, explain, getCardinality, getConfiguration, getCost, getDependencies, getEvaluationMethod, getExtraProperty, getIntegerBounds, getInterpretedExpression, getIntrinsicDependencies, getLocalRetainedStaticContext, getLocation, getNetCost, getObjectName, getPackageData, getParentExpression, getProperties, getProperty, getRetainedStaticContext, getScopingExpression, getSlotsUsed, getSpecialProperties, getStaticBaseURI, getStaticBaseURIString, getStaticType, getStaticUType, getTracingTag, hasCompatibleStaticContext, hashCode, hasSpecialProperty, hasVariableBinding, identityHashCode, implementsStaticTypeCheck, isCallOn, isEqual, isIdentical, isLiftable, isMultiThreaded, isStaticPropertiesKnown, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, markTailFunctionCalls, operandList, operandSparseList, optimizeChildren, prepareForStreaming, resetLocalStaticProperties, restoreParentPointers, setEvaluationMethod, setExtraProperty, setFiltered, setFlattened, setLocation, setParentExpression, setRetainedStaticContext, setRetainedStaticContextLocally, setRetainedStaticContextThoroughly, setStaticProperty, simplify, simplifyChildren, staticTypeCheck, suppressValidation, toPattern, toShortString, toString, typeCheck, typeCheckChildren, typeError, unordered, verifyParentPointers`

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

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

    - ### Methods inherited from interface net.sf.saxon.trace.Traceable

      `gatherProperties`

- - ### Constructor Detail

    - #### TryCatch

          public TryCatch​(Expression tryExpr)

  - ### Method Detail

    - #### addCatchExpression

          public void addCatchExpression​(QNameTest test,
                                         Expression catchExpr)

    - #### setRollbackOutput

          public void setRollbackOutput​(boolean rollback)

    - #### isRollbackOutput

          public boolean isRollbackOutput()

    - #### getTryOperand

          public Operand getTryOperand()

      Get the "try" operand
      Returns:
        the primary operand to be evaluated

    - #### getTryExpr

          public Expression getTryExpr()

      Get the "try" expression
      Returns:
        the primary expression to be evaluated

    - #### getCatchClauses

          public java.util.List<TryCatch.CatchClause> getCatchClauses()

      Get the list of catch clauses
      Returns:
        the list of catch clauses

    - #### isInstruction

          public boolean isInstruction()

      Ask whether this expression is an instruction. In XSLT streamability analysis this is used to distinguish constructs corresponding to XSLT instructions from other constructs, typically XPath expressions.
      Overrides:
        `isInstruction` in class `Expression`
      Returns:
        true (if this construct exists at all in an XSLT environment, then it represents an instruction)

    - #### allowExtractingCommonSubexpressions

          public boolean allowExtractingCommonSubexpressions()

      Ask whether common subexpressions found in the operands of this expression can be extracted and evaluated outside the expression itself. The result is irrelevant in the case of operands evaluated with a different focus, which will never be extracted in this way, even if they have no focus dependency.
      Overrides:
        `allowExtractingCommonSubexpressions` in class `Expression`
      Returns:
        false for this kind of expression

    - #### computeCardinality

          public int computeCardinality()

      Determine the cardinality of the function.
      Specified by:
        `computeCardinality` in class `Expression`
      Returns:
        the computed cardinality, as one of the values `StaticProperty.ALLOWS_ZERO_OR_ONE`, `StaticProperty.EXACTLY_ONE`, `StaticProperty.ALLOWS_ONE_OR_MORE`, `StaticProperty.ALLOWS_ZERO_OR_MORE`. May also return `StaticProperty.ALLOWS_ZERO` if the result is known to be an empty sequence, or `StaticProperty.ALLOWS_MANY` if if is known to return a sequence of length two or more.

    - #### getItemType

          public ItemType getItemType()

      Determine the item type of the value returned by the function
      Specified by:
        `getItemType` in class `Expression`
      Returns:
        a value such as Type.STRING, Type.BOOLEAN, Type.NUMBER, Type.NODE, or Type.ITEM (meaning not known at compile time)

    - #### operands

          public java.lang.Iterable<Operand> operands()

      Get the immediate sub-expressions of this expression, with information about the relationship of each expression to its parent expression. Default implementation returns a zero-length array, appropriate for an expression that has no sub-expressions.
      Overrides:
        `operands` in class `Expression`
      Returns:
        an iterator containing the sub-expressions of this expression

    - #### optimize

          public Expression optimize​(ExpressionVisitor visitor,
                                     ContextItemStaticInfo contextInfo)
                              throws XPathException

      Description copied from class: `Expression`
      Perform optimisation of an expression and its subexpressions. This is the third and final phase of static optimization.

      This method is called after all references to functions and variables have been resolved to the declaration of the function or variable, and after all type checking has been done.

      Overrides:
        `optimize` in class `Expression`
      Parameters:
        `visitor` - an expression visitor
        `contextInfo` - the static type of "." at the point where this expression is invoked. The parameter is set to null if it is known statically that the context item will be undefined. If the type of the context item is not known statically, the argument is set to `Type.ITEM_TYPE`
      Returns:
        the original expression, rewritten if appropriate to optimize execution
      Throws:
        `XPathException` - if an error is discovered during this phase (typically a type error)

    - #### getImplementationMethod

          public int getImplementationMethod()

      An implementation of Expression must provide at least one of the methods evaluateItem(), iterate(), or process(). This method indicates which of these methods is provided directly. The other methods will always be available indirectly, using an implementation that relies on one of the other methods.
      Specified by:
        `getImplementationMethod` in class `Expression`
      Returns:
        the implementation method, for example `Expression.ITERATE_METHOD` or `Expression.EVALUATE_METHOD` or `Expression.PROCESS_METHOD`

    - #### equals

          public boolean equals​(java.lang.Object other)

      Is this expression the same as another expression?
      Overrides:
        `equals` in class `Expression`
      Parameters:
        `other` - the expression to be compared with this one
      Returns:
        true if the two expressions are statically equivalent

    - #### computeHashCode

          public int computeHashCode()

      Hashcode supporting equals()
      Overrides:
        `computeHashCode` in class `Expression`
      Returns:
        a computed hash code

    - #### copy

          public Expression copy​(RebindingMap rebindings)

      Copy an expression. This makes a deep copy.
      Specified by:
        `copy` in class `Expression`
      Parameters:
        `rebindings` - variables that need to be re-bound
      Returns:
        the copy of the original expression

    - #### evaluateItem

          public Item evaluateItem​(XPathContext c)
                            throws XPathException

      Evaluate as a singleton item
      Overrides:
        `evaluateItem` in class `Expression`
      Parameters:
        `c` - the dynamic XPath evaluation context
      Returns:
        the node or atomic value that results from evaluating the expression; or null to indicate that the result is an empty sequence
      Throws:
        `XPathException` - if any dynamic error occurs evaluating the expression

    - #### iterate

          public SequenceIterator iterate​(XPathContext c)
                                   throws XPathException

      Iterate over the results of the function
      Overrides:
        `iterate` in class `Expression`
      Parameters:
        `c` - supplies the context for evaluation
      Returns:
        a SequenceIterator that can be used to iterate over the result of the expression
      Throws:
        `XPathException` - if any dynamic error occurs evaluating the expression

    - #### process

          public void process​(Outputter output,
                              XPathContext context)
                       throws XPathException

      Description copied from class: `Expression`
      Process the instruction, without returning any tail calls
      Overrides:
        `process` in class `Expression`
      Parameters:
        `output` - the destination for the result
        `context` - The dynamic context, giving access to the current node, the current variables, etc.
      Throws:
        `XPathException` - if a dynamic error occurs

    - #### getExpressionName

          public java.lang.String getExpressionName()

      Get a name identifying the kind of expression, in terms meaningful to a user.
      Overrides:
        `getExpressionName` in class `Expression`
      Returns:
        a name identifying the kind of expression, in terms meaningful to a user. The name will always be in the form of a lexical XML QName, and should match the name used in explain() output displaying the expression.

    - #### export

          public void export​(ExpressionPresenter out)
                      throws XPathException

      Diagnostic print of expression structure. The abstract expression tree is written to the supplied output destination.
      Specified by:
        `export` in interface `ExportAgent`
      Specified by:
        `export` in class `Expression`
      Parameters:
        `out` - the expression presenter used to display the structure
      Throws:
        `XPathException` - if the export fails, for example if an expression is found that won't work in the target environment.

    - #### getStreamerName

          public java.lang.String getStreamerName()

      Get the (partial) name of a class that supports streaming of this kind of expression
      Overrides:
        `getStreamerName` in class `Expression`
      Returns:
        the partial name of a class that can be instantiated to provide streaming support in Saxon-EE, or null if there is no such class