net.sf.saxon.functions

## Class KeyFn

- java.lang.Object
- - net.sf.saxon.expr.Expression
  - - net.sf.saxon.expr.FunctionCall
    - - net.sf.saxon.functions.SystemFunctionCall
      - - net.sf.saxon.functions.KeyFn

- All Implemented Interfaces:
    Serializable, SourceLocator, LocationProvider, SaxonLocator, Callable, InstructionInfo, Locator

      public class KeyFn
      extends SystemFunctionCall

  See Also:
    Serialized Form

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `KeyFn.SubtreeFilter` Mapping class to filter nodes that have the origin node as an ancestor-or-self

  - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.functions.SystemFunctionCall

      `operation`

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

      `argument`

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

      `EFFECTIVE_BOOLEAN_VALUE, EVALUATE_METHOD, EVENT_FEED_METHOD, INHERITED_CONTEXT, INSPECTION_CONTEXT, ITEM_FEED_METHOD, ITERATE_METHOD, locationId, MAX_SEQUENCE_LENGTH, MAX_STRING_LENGTH, NAVIGATION_CONTEXT, NODE_VALUE_CONTEXT, PROCESS_METHOD, PUSH_SELECTION, staticProperties, UNBOUNDED_LOWER, UNBOUNDED_UPPER, W3C_CONSUMING, W3C_FREE_RANGING, W3C_GROUP_CONSUMING, W3C_MOTIONLESS, WATCH_METHOD`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KeyFn()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `PathMap.PathMapNodeSet` | `addToPathMap(PathMap pathMap, PathMap.PathMapNodeSet pathMapNodeSet)` Add a representation of a doc() call or similar function to a PathMap.
    `Sequence` | `call(XPathContext context, Sequence[] arguments)` Evaluate the expression
    `void` | `checkArguments(ExpressionVisitor visitor)` Method called during static type checking
    `int` | `computeSpecialProperties()` Get the static properties of this expression (other than its type).
    `Expression` | `copy()` Copy an expression.
    `boolean` | `equals(Object o)` Determine whether two expressions are equivalent
    `ExpressionCompiler` | `getExpressionCompiler()` Return the compiler of the KeyFn expression
    `boolean` | `getInternal()`
    `NamespaceResolver` | `getNamespaceResolver()`
    `StructuredQName` | `getStaticKeyName()` Get the key name, if known statically.
    `KeyDefinitionSet` | `getStaticKeySet()`
    `static KeyFn` | `internalKeyCall(KeyDefinitionSet keySet, String name, Expression value, Expression doc)` Non-standard constructor to create an internal call on key() with a known key definition
    `SequenceIterator` | `iterate(XPathContext context)` Enumerate the results of the expression
    `Expression` | `preEvaluate(ExpressionVisitor visitor)` preEvaluate: this method suppresses compile-time evaluation by doing nothing
    `Expression` | `simplify(ExpressionVisitor visitor)` Simplify: add a third implicit argument, the context document
    `Expression` | `typeCheck(ExpressionVisitor visitor, ExpressionVisitor.ContextItemType contextItemType)` Type-check the expression.

    - ### Methods inherited from class net.sf.saxon.functions.SystemFunctionCall

      `addContextDocumentArgument, addDocToPathMap, bindStaticContext, computeCardinality, equalOrNull, getContextNode, getConvertingCallable, getDefaultArgumentNode, getDetails, getErrorCodeForTypeErrors, getFunctionItemType, getImplementationMethod, getItemType, getOperation, getRequiredType, iterateSubExpressionInfo, makeSystemFunction, optimize, setDetails, useContextItemAsDefault`

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

      `addExternalFunctionCallToPathMap, checkArgumentCount, explain, getArguments, getDisplayName, getExpressionName, getFunctionName, getNumberOfArguments, hashCode, iterateSubExpressions, promote, replaceSubExpression, setArguments, setFunctionName, simplifyArguments, toString`

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

      `adoptChildExpression, checkForUpdatingSubexpressions, checkPermittedContents, computeDependencies, computeStaticProperties, doPromotion, dynamicError, effectiveBooleanValue, evaluateAsString, evaluateItem, evaluatePendingUpdates, explain, getCardinality, getColumnNumber, getColumnNumber, getConstructType, getContainer, getDependencies, getEvaluationMethod, getExecutable, getHostLanguage, getIntegerBounds, getIntrinsicDependencies, getLineNumber, getLineNumber, getLocationId, getLocationProvider, getObjectName, getProperties, getProperty, getPublicId, getSlotsUsed, getSpecialProperties, getStreamability, getStreamingAdjunct, getSystemId, getSystemId, hasVariableBinding, implementsStaticTypeCheck, isSubtreeExpression, isUpdatingExpression, isVacuousExpression, iterateEvents, markTailFunctionCalls, process, resetLocalStaticProperties, setContainer, setEvaluationMethod, setFiltered, setFlattened, setLocationId, staticTypeCheck, suppressValidation, toPattern, toStreamingPattern, typeError`

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

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

- - ### Constructor Detail

    - #### KeyFn

          public KeyFn()

  - ### Method Detail

    - #### getStaticKeyName

          public StructuredQName getStaticKeyName()

      Get the key name, if known statically. If not known statically, return null.
      Returns:
        the key name if known, otherwise null

    - #### getStaticKeySet

          public KeyDefinitionSet getStaticKeySet()

    - #### getInternal

          public boolean getInternal()

    - #### getNamespaceResolver

          public NamespaceResolver getNamespaceResolver()

    - #### typeCheck

          public Expression typeCheck(ExpressionVisitor visitor,
                             ExpressionVisitor.ContextItemType contextItemType)
                               throws XPathException

      Type-check the expression. This also calls preEvaluate() to evaluate the function if all the arguments are constant; functions that do not require this behavior can override the preEvaluate method.
      Overrides:
        `typeCheck` in class `FunctionCall`
      Parameters:
        `visitor` - an expression visitor
        `contextItemType` - 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 to perform necessary run-time type checks, and to perform other type-related optimizations
      Throws:
        `XPathException` - if an error is discovered during this phase (typically a type error)

    - #### internalKeyCall

          public static KeyFn internalKeyCall(KeyDefinitionSet keySet,
                              String name,
                              Expression value,
                              Expression doc)

      Non-standard constructor to create an internal call on key() with a known key definition
      Parameters:
        `keySet` - the set of KeyDefinitions (always a single KeyDefinition)
        `name` - the name allocated to the key (first argument of the function)
        `value` - the value being searched for (second argument of the function)
        `doc` - the document being searched (third argument)
      Returns:
        a call on the key() function

    - #### simplify

          public Expression simplify(ExpressionVisitor visitor)
                              throws XPathException

      Simplify: add a third implicit argument, the context document
      Overrides:
        `simplify` in class `FunctionCall`
      Parameters:
        `visitor` - the expression visitor
      Returns:
        the simplified expression
      Throws:
        `XPathException` - if an error is discovered during expression rewriting

    - #### checkArguments

          public void checkArguments(ExpressionVisitor visitor)
                              throws XPathException

      Description copied from class: `SystemFunctionCall`
      Method called during static type checking
      Overrides:
        `checkArguments` in class `SystemFunctionCall`
      Parameters:
        `visitor` - the expression visitor
      Throws:
        `XPathException` - if the arguments are incorrect

    - #### computeSpecialProperties

          public int computeSpecialProperties()

      Get the static properties of this expression (other than its type). The result is bit-signficant. These properties are used for optimizations. In general, if a property bit is set, it is true, but if it is unset, the value is unknown.
      Overrides:
        `computeSpecialProperties` in class `SystemFunctionCall`
      Returns:
        the special properties, as a bit-significant integer

    - #### preEvaluate

          public Expression preEvaluate(ExpressionVisitor visitor)

      preEvaluate: this method suppresses compile-time evaluation by doing nothing
      Overrides:
        `preEvaluate` in class `FunctionCall`
      Parameters:
        `visitor` - the expression visitor
      Returns:
        the result of the early evaluation, or the original expression, or potentially a simplified expression

    - #### addToPathMap

          public PathMap.PathMapNodeSet addToPathMap(PathMap pathMap,
                                            PathMap.PathMapNodeSet pathMapNodeSet)

      Add a representation of a doc() call or similar function to a PathMap. This is a convenience method called by the addToPathMap() methods for doc(), document(), collection() and similar functions. These all create a new root expression in the path map.
      Overrides:
        `addToPathMap` in class `Expression`
      Parameters:
        `pathMap` - the PathMap to which the expression should be added
        `pathMapNodeSet` - the PathMapNodeSet to which the paths embodied in this expression should be added
      Returns:
        the pathMapNode representing the focus established by this expression, in the case where this expression is the first operand of a path expression or filter expression

    - #### copy

          public Expression copy()

      Copy an expression. This makes a deep copy.
      Overrides:
        `copy` in class `SystemFunctionCall`
      Returns:
        the copy of the original expression

    - #### equals

          public boolean equals(Object o)

      Determine whether two expressions are equivalent
      Overrides:
        `equals` in class `SystemFunctionCall`

    - #### iterate

          public SequenceIterator iterate(XPathContext context)
                                   throws XPathException

      Enumerate the results of the expression
      Overrides:
        `iterate` in class `Expression`
      Parameters:
        `context` - 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

    - #### getExpressionCompiler

          public ExpressionCompiler getExpressionCompiler()

      Return the compiler of the KeyFn expression
      Overrides:
        `getExpressionCompiler` in class `Expression`
      Returns:
        the relevant ExpressionCompiler

    - #### call

          public Sequence call(XPathContext context,
                      Sequence[] arguments)
                        throws XPathException

      Evaluate the expression
      Parameters:
        `context` - the dynamic evaluation context
        `arguments` - the values of the arguments, supplied as Sequences
      Returns:
        the result of the evaluation, in the form of a Sequence
      Throws:
        `XPathException` - if a dynamic error occurs during the evaluation of the expression

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