public class KeyManager
extends Object
implements Serializable
The memory management in this class is subtle, with extensive use of weak references. The idea is that an index should continue to exist in memory so long as both the compiled stylesheet and the source document exist in memory: if either is removed, the index should go too. The document itself holds no reference to the index. The compiled stylesheet (which owns the KeyManager) holds a weak reference to the index. The index, of course, holds strong references to the nodes in the document. The Controller holds a strong reference to the list of indexes used for each document, so that indexes remain in memory for the duration of a transformation even if the documents themselves are garbage collected.
Potentially there is a need for more than one index for a given key name, depending on the primitive type of the value provided to the key() function. An index is built corresponding to the type of the requested value; if subsequently the key() function is called with the same name and a different type of value, then a new index is built.
For XSLT-defined keys, equality matching follows the rules of the eq operator, which means that untypedAtomic values are treated as strings. In backwards compatibility mode, all values are converted to strings.
This class is also used for internal indexes constructed (a) to support the idref() function, and (b) (in Saxon-SA only) to support filter expressions of the form /a/b/c[d=e], where the path expression being filtered must be a single-document context-free path rooted at a document node, where exactly one of d and e must be dependent on the focus, and where certain other conditions apply such as the filter predicate not being positional. The operator in this case may be either "=" or "eq". If it is "eq", then the semantics are very similar to xsl:key indexes, except that use of non-comparable types gives an error rather than a non-match. If the operator is "=", however, then the rules for handling untypedAtomic values are different: these must be converted to the type of the other operand. In this situation the following rules apply. Assume that the predicate is [use=value], where use is dependent on the focus (the indexed value), and value is the sought value.
Modifier and Type | Field and Description |
---|---|
private WeakHashMap |
docIndexes |
IntHashMap |
keyList |
Constructor and Description |
---|
KeyManager(Configuration config)
create a KeyManager and initialise variables
|
Modifier and Type | Method and Description |
---|---|
void |
addKeyDefinition(int fingerprint,
KeyDefinition keydef,
Configuration config)
Register a key definition.
|
Map |
buildIndex(int keyNameFingerprint,
BuiltInAtomicType itemType,
Set foundItemTypes,
DocumentInfo doc,
XPathContext context)
Build the index for a particular document for a named key
|
protected void |
constructIndex(DocumentInfo doc,
Map index,
KeyDefinition keydef,
BuiltInAtomicType soughtItemType,
Set foundItemTypes,
XPathContext context,
boolean isFirst)
Process one key definition to add entries to an index
|
void |
explainKeys(Configuration config,
PrintStream out)
Diagnostic output explaining the keys
|
private static Object |
getCollationKey(AtomicValue value,
BuiltInAtomicType itemType,
StringCollator collation,
Platform platform) |
private Object |
getIndex(DocumentInfo doc,
int keyFingerprint,
AtomicType itemType)
Get the index associated with a particular key, a particular source document,
and a particular primitive item type
|
List |
getKeyDefinitions(int fingerprint)
Get all the key definitions that match a particular fingerprint
|
private void |
processKeyNode(NodeInfo curr,
BuiltInAtomicType soughtItemType,
Set foundItemTypes,
KeyDefinition keydef,
Map index,
XPathContext xc,
boolean isFirst)
Process one matching node, adding entries to the index if appropriate
|
private void |
putIndex(DocumentInfo doc,
int keyFingerprint,
AtomicType itemType,
Object index,
XPathContext context)
Save the index associated with a particular key, a particular item type,
and a particular document.
|
private void |
registerIdrefKey(Configuration config)
An internal key definition is used to support the idref() function.
|
SequenceIterator |
selectByKey(int keyNameFingerprint,
DocumentInfo doc,
AtomicValue soughtValue,
XPathContext context)
Get the nodes with a given key value
|
public KeyManager(Configuration config)
private void registerIdrefKey(Configuration config)
config
- The configuration. This is needed because the patterns that are
generated need access to schema information.public void addKeyDefinition(int fingerprint, KeyDefinition keydef, Configuration config) throws StaticError
fingerprint
- Integer representing the name of the keykeydef
- The details of the key's definitionconfig
- The configurationStaticError
- if this key definition is inconsistent with existing key definitions having the same namepublic List getKeyDefinitions(int fingerprint)
fingerprint
- The fingerprint of the name of the required keypublic Map buildIndex(int keyNameFingerprint, BuiltInAtomicType itemType, Set foundItemTypes, DocumentInfo doc, XPathContext context) throws XPathException
keyNameFingerprint
- The fingerprint of the name of the required keyitemType
- the type of the values to be indexed.doc
- The source document in questioncontext
- The dynamic contextXPathException
protected void constructIndex(DocumentInfo doc, Map index, KeyDefinition keydef, BuiltInAtomicType soughtItemType, Set foundItemTypes, XPathContext context, boolean isFirst) throws XPathException
XPathException
private void processKeyNode(NodeInfo curr, BuiltInAtomicType soughtItemType, Set foundItemTypes, KeyDefinition keydef, Map index, XPathContext xc, boolean isFirst) throws XPathException
curr
- the node being processedsoughtItemType
- the primitive item type of the argument to the key() function that triggered
this index to be builtkeydef
- the key definitionindex
- the index being constructedxc
- the context for evaluating expressionsisFirst
- indicates whether this is the first key definition with a given key name (which means
no sort of the resulting key entries is required)XPathException
public SequenceIterator selectByKey(int keyNameFingerprint, DocumentInfo doc, AtomicValue soughtValue, XPathContext context) throws XPathException
keyNameFingerprint
- The fingerprint of the name of the required keydoc
- The source document in questionsoughtValue
- The required key valuecontext
- The dynamic context, needed only the first time when the key is being builtXPathException
private static Object getCollationKey(AtomicValue value, BuiltInAtomicType itemType, StringCollator collation, Platform platform)
private void putIndex(DocumentInfo doc, int keyFingerprint, AtomicType itemType, Object index, XPathContext context)
private Object getIndex(DocumentInfo doc, int keyFingerprint, AtomicType itemType)
public void explainKeys(Configuration config, PrintStream out)