net.sf.saxon.trans

## Class KeyDefinition

- java.lang.Object
- - net.sf.saxon.expr.instruct.Procedure
  - - net.sf.saxon.trans.KeyDefinition

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

      public class KeyDefinition
      extends Procedure
      implements Serializable

  Corresponds to a single xsl:key declaration.

  Author:
    Michael H. Kay
  See Also:
    Serialized Form

- - ### Field Summary

    - ### Fields inherited from class net.sf.saxon.expr.instruct.Procedure

      `body`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KeyDefinition(PatternFinder match, Expression use, String collationName, StringCollator collation)` Constructor to create a key definition

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `StringCollator` | `getCollation()` Get the collation.
    `String` | `getCollationName()` Get the collation name for this key definition.
    `int` | `getConstructType()` Get the type of construct.
    `BuiltInAtomicType` | `getIndexedItemType()` Get the primitive item type of the values returned by the use expression
    `PatternFinder` | `getMatch()` Get the match pattern for the key definition
    `StructuredQName` | `getObjectName()` Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc.
    `Expression` | `getUse()` Get the use expression for the key definition
    `boolean` | `isBackwardsCompatible()` Test backwards compatibility mode
    `boolean` | `isConvertUntypedToOther()` Determine whether untypedAtomic values are converted to the type of the other operand.
    `boolean` | `isRangeKey()` Ask whether this key is a range key, that is, a key capable of returning (a) the values in a selected range, and (b) the keys in order
    `boolean` | `isStrictComparison()` Get whether strict comparison is needed.
    `void` | `setBackwardsCompatible(boolean bc)` Set backwards compatibility mode.
    `void` | `setBody(Expression body)` Set the body of the key (the use expression).
    `void` | `setConvertUntypedToOther(boolean convertToOther)` Indicate that untypedAtomic values should be converted to the type of the other operand, rather than to strings.
    `void` | `setIndexedItemType(BuiltInAtomicType itemType)` Set the primitive item type of the values returned by the use expression
    `void` | `setLocation(String systemId, int lineNumber)` Set the system Id and line number of the source xsl:key definition
    `void` | `setRangeKey(boolean rangeKey)` Say whether this key is a range key, that is, a key capable of returning (a) the values in a selected range, and (b) the keys in order
    `void` | `setStackFrameMap(SlotManager map)` Set the map of local variables needed while evaluating the "use" expression
    `void` | `setStrictComparison(boolean strict)` Set whether strict comparison is needed.

    - ### Methods inherited from class net.sf.saxon.expr.instruct.Procedure

      `getBody, getColumnNumber, getColumnNumber, getContainerGranularity, getExecutable, getHostLanguage, getLineNumber, getLineNumber, getLocationProvider, getProperties, getProperty, getPublicId, getStackFrameMap, getSystemId, getSystemId, setExecutable, setHostLanguage, setLineNumber, setSystemId`

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

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

- - ### Constructor Detail

    - #### KeyDefinition

          public KeyDefinition(PatternFinder match,
                       Expression use,
                       String collationName,
                       StringCollator collation)

      Constructor to create a key definition
      Parameters:
        `match` - the pattern in the xsl:key match attribute
        `use` - the expression in the xsl:key use attribute, or the expression that results from compiling the xsl:key contained instructions. Note that a KeyDefinition constructed by the XSLT or XQuery parser will always use an Expression here; however, a KeyDefinition constructed at run-time by a compiled stylesheet or XQuery might use a simple ExpressionEvaluator that lacks all the compile-time information associated with an Expression
        `collationName` - the name of the collation being used
        `collation` - the actual collation. This must be one that supports generation of collation keys.

  - ### Method Detail

    - #### setRangeKey

          public void setRangeKey(boolean rangeKey)

      Say whether this key is a range key, that is, a key capable of returning (a) the values in a selected range, and (b) the keys in order
      Parameters:
        `rangeKey` - true if this is a range key; false if not

    - #### isRangeKey

          public boolean isRangeKey()

      Ask whether this key is a range key, that is, a key capable of returning (a) the values in a selected range, and (b) the keys in order
      Returns:
        true if this is a range key; false if not

    - #### setIndexedItemType

          public void setIndexedItemType(BuiltInAtomicType itemType)

      Set the primitive item type of the values returned by the use expression
      Parameters:
        `itemType` - the primitive type of the indexed values

    - #### getIndexedItemType

          public BuiltInAtomicType getIndexedItemType()

      Get the primitive item type of the values returned by the use expression
      Returns:
        the primitive item type of the indexed values

    - #### setBackwardsCompatible

          public void setBackwardsCompatible(boolean bc)

      Set backwards compatibility mode. The key definition is backwards compatible if ANY of the xsl:key declarations has version="1.0" in scope.
      Parameters:
        `bc` - set to true if running in XSLT 2.0 backwards compatibility mode

    - #### isBackwardsCompatible

          public boolean isBackwardsCompatible()

      Test backwards compatibility mode
      Returns:
        true if running in XSLT backwards compatibility mode

    - #### setStrictComparison

          public void setStrictComparison(boolean strict)

      Set whether strict comparison is needed. Strict comparison treats non-comparable values as an error rather than a no-match. This is used for internal keys that support value comparisons in Saxon-EE, it is not used for user-defined XSLT keys.
      Parameters:
        `strict` - true if strict comparison is needed

    - #### isStrictComparison

          public boolean isStrictComparison()

      Get whether strict comparison is needed. Strict comparison treats non-comparable values as an error rather than a no-match. This is used for internal keys that support value comparisons in Saxon-EE, it is not used for user-defined XSLT keys.
      Returns:
        true if strict comparison is needed.

    - #### setConvertUntypedToOther

          public void setConvertUntypedToOther(boolean convertToOther)

      Indicate that untypedAtomic values should be converted to the type of the other operand, rather than to strings. This is used for indexes constructed internally by Saxon-EE to support filter expressions that use the "=" operator, as distinct from "eq".
      Parameters:
        `convertToOther` - true if comparisons follow the semantics of the "=" operator rather than the "eq" operator

    - #### isConvertUntypedToOther

          public boolean isConvertUntypedToOther()

      Determine whether untypedAtomic values are converted to the type of the other operand.
      Returns:
        true if comparisons follow the semantics of the "=" operator rather than the "eq" operator

    - #### setStackFrameMap

          public void setStackFrameMap(SlotManager map)

      Set the map of local variables needed while evaluating the "use" expression
      Overrides:
        `setStackFrameMap` in class `Procedure`

    - #### setLocation

          public void setLocation(String systemId,
                         int lineNumber)

      Set the system Id and line number of the source xsl:key definition
      Parameters:
        `systemId` - the URI of the module containing the key definition
        `lineNumber` - the line number of the key definition

    - #### getMatch

          public PatternFinder getMatch()

      Get the match pattern for the key definition
      Returns:
        the pattern specified in the "match" attribute of the xsl:key declaration

    - #### setBody

          public void setBody(Expression body)

      Set the body of the key (the use expression). This is held redundantly as an Expression and as a SequenceIterable (not sure why!)
      Overrides:
        `setBody` in class `Procedure`
      Parameters:
        `body` - the use expression of the key

    - #### getUse

          public Expression getUse()

      Get the use expression for the key definition
      Returns:
        the expression specified in the "use" attribute of the xsl:key declaration

    - #### getCollationName

          public String getCollationName()

      Get the collation name for this key definition.
      Returns:
        the collation name (the collation URI)

    - #### getCollation

          public StringCollator getCollation()

      Get the collation.
      Returns:
        the collation

    - #### getConstructType

          public int getConstructType()

      Get the type of construct. This will either be the fingerprint of a standard XSLT instruction name (values in `StandardNames`: all less than 1024) or it will be a constant in class `Location`.
      Specified by:
        `getConstructType` in interface `InstructionInfo`
      Returns:
        an integer identifying the kind of construct

    - #### getObjectName

          public StructuredQName getObjectName()

      Get a name identifying the object of the expression, for example a function name, template name, variable name, key name, element name, etc. This is used only where the name is known statically.
      Specified by:
        `getObjectName` in interface `InstructionInfo`
      Returns:
        the QName of the object declared or manipulated by this instruction or expression

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