net.sf.saxon.trans

Class KeyIndex

java.lang.Object

net.sf.saxon.trans.KeyIndex

public class KeyIndex
extends 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 and Description
static class	KeyIndex.Status

Constructor Summary

Constructors

Constructor and Description
KeyIndex(boolean isRangeKey)

Method Summary

Modifier and Type	Method and Description
void	buildIndex(KeyDefinitionSet keySet, TreeInfo doc, XPathContext context) Build the index for a particular document for a named key
List<NodeInfo>	get(AtomicValue soughtValue) Get the nodes with a given key value
List<NodeInfo>	getComposite(SequenceIterator<?> soughtValue) Get the nodes with a given composite key value
KeyIndex.Status	getStatus() Ask if the index is under construction
Map<AtomicMatchKey,List<NodeInfo>>	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 Map<AtomicMatchKey,List<NodeInfo>> getUnderlyingMap()

Get the underlying map

Returns:

the underlying map

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

get

public List<NodeInfo> get(AtomicValue soughtValue)
                   throws XPathException

Get the nodes with a given key value

Parameters:

soughtValue - The required 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

getComposite

public List<NodeInfo> 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