Package net.sf.saxon.trans

## Class KeyIndex

- java.lang.Object
- - net.sf.saxon.trans.KeyIndex

-     public class KeyIndex
      extends java.lang.Object

  A key index is an index maintained to support xsl:key key definitions, including both user-defined keys and keys added by the optimizer. Each key index supports one key definition (a set of xsl:key declarations with the same name) applied to one document tree.

  The index can support a mixture of atomic keys of different types; there is no error caused by comparing values of different types. This relies on the fact that XPathComparable values are identical for comparable values (e.g. integers and doubles), and distinct otherwise.

  With the XSLT xsl:key construct, untypedAtomic values are treated as strings. However, this structure is also used to support internally-generated keys with general comparison semantics, where untyped values are converted to the type of the other operand. To enable this to work, we maintain a list of all untypedAtomic keys present in the index; and if a search is made for some type like xs:date, we then go through this list converting each untypedAtomic value to a date and indexing it as such. In principle this can happen for an arbitrary number of data types, though it is unlikely in practice because not many types have overlapping lexical spaces.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `KeyIndex.Status` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `KeyIndex​(boolean isRangeKey)` |

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `buildIndex​(KeyDefinitionSet keySet, TreeInfo doc, XPathContext context)` | Build the index for a particular document for a named key
    `SequenceIterator` | `getComposite​(SequenceIterator soughtValue)` | Get the nodes with a given composite key value
    `SequenceIterator` | `getNodes​(AtomicValue soughtValue)` | Get the nodes with a given key value
    `KeyIndex.Status` | `getStatus()` | Ask if the index is under construction
    `java.util.Map<AtomicMatchKey,​java.lang.Object>` | `getUnderlyingMap()` | Get the underlying map
    `boolean` | `isCreatedInThisThread()` | Ask if the index was created in the current thread
    `boolean` | `isEmpty()` | Ask whether the index is empty
    `void` | `reindexUntypedValues​(BuiltInAtomicType type)` | Re-index untyped atomic values after conversion to a specific type.
    `void` | `setStatus​(KeyIndex.Status status)` | Say whether the index is under construction

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

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

- - ### Constructor Detail

    - #### KeyIndex

          public KeyIndex​(boolean isRangeKey)

  - ### Method Detail

    - #### getUnderlyingMap

          public java.util.Map<AtomicMatchKey,​java.lang.Object> getUnderlyingMap()

      Get the underlying map
      Returns:
        the underlying map. The "Object" in the map entry is either a @code{NodeInfo} or a `List<NodeInfo>`

    - #### isCreatedInThisThread

          public boolean isCreatedInThisThread()

      Ask if the index was created in the current thread
      Returns:
        true if this index was created in this thread

    - #### getStatus

          public KeyIndex.Status getStatus()

      Ask if the index is under construction
      Returns:
        true if the index is still under construction

    - #### setStatus

          public void setStatus​(KeyIndex.Status status)

      Say whether the index is under construction
      Parameters:
        `status` -

    - #### buildIndex

          public void buildIndex​(KeyDefinitionSet keySet,
                                 TreeInfo doc,
                                 XPathContext context)
                          throws XPathException

      Build the index for a particular document for a named key
      Parameters:
        `keySet` - The set of key definitions with this name
        `doc` - The source document in question
        `context` - The dynamic context
      Throws:
        `XPathException` - if a dynamic error is encountered

    - #### reindexUntypedValues

          public void reindexUntypedValues​(BuiltInAtomicType type)
                                    throws XPathException

      Re-index untyped atomic values after conversion to a specific type. This happens when the "convertUntypedToOther" option is set (typically because this index is used to support a general comparison), and the sought value is of a type other that string or untyped atomic. We go through the index finding all untyped atomic values, converting each one to the sought type, and adding it to the index under this type.
      Parameters:
        `type` - the type to which untyped atomic values should be converted
      Throws:
        `XPathException` - if conversion of any untyped atomic value to the requested key type fails

    - #### isEmpty

          public boolean isEmpty()

      Ask whether the index is empty
      Returns:
        true if the index is empty

    - #### getNodes

          public SequenceIterator getNodes​(AtomicValue soughtValue)
                                    throws XPathException

      Get the nodes with a given key value
      Parameters:
        `soughtValue` - The required key value
      Returns:
        an iterator over the selected nodes, always in document order with no duplicates
      Throws:
        `XPathException` - if a dynamic error is encountered

    - #### getComposite

          public SequenceIterator getComposite​(SequenceIterator soughtValue)
                                        throws XPathException

      Get the nodes with a given composite key value
      Parameters:
        `soughtValue` - The required composite key value
      Returns:
        a list of the selected nodes, always in document order with no duplicates, or null to represent an empty list
      Throws:
        `XPathException` - if a dynamic error is encountered