public class XPathExpressionEngine extends Object implements ExpressionEngine
A specialized implementation of the ExpressionEngine
interface that is able to evaluate XPATH expressions.
This class makes use of Commons JXPath for handling XPath expressions and mapping them to the nodes of a hierarchical configuration. This makes the rich and powerful XPATH syntax available for accessing properties from a configuration object.
For selecting properties arbitrary XPATH expressions can be used, which select single or multiple configuration
nodes. The associated Configuration
instance will directly pass the specified property keys into this engine.
If a key is not syntactically correct, an exception will be thrown.
For adding new properties, this expression engine uses a specific syntax: the "key" of a new property must consist of two parts that are separated by whitespace:
Some examples for valid keys that can be passed into the configuration's addProperty()
method follow:
"/tables/table[1] type"
This will add a new type
node as a child of the first table
element.
"/tables/table[1] @type"
Similar to the example above, but this time a new attribute named type
will be added to the first
table
element.
"/tables table/fields/field/name"
This example shows how a complex path can be added. Parent node is the tables
element. Here a new branch
consisting of the nodes table
, fields
, field
, and name
will be added.
"/tables table/fields/field@type"
This is similar to the last example, but in this case a complex path ending with an attribute is defined.
Note: This extended syntax for adding properties only works with the addProperty()
method.
setProperty()
does not support creating new nodes this way.
From version 1.7 on, it is possible to use regular keys in calls to addProperty()
(i.e. keys that do not have
to contain a whitespace as delimiter). In this case the key is evaluated, and the biggest part pointing to an
existing node is determined. The remaining part is then added as new path. As an example consider the key
"tables/table[last()]/fields/field/name"
If the key does not point to an existing node, the engine will check the paths
"tables/table[last()]/fields/field"
, "tables/table[last()]/fields"
, "tables/table[last()]"
,
and so on, until a key is found which points to a node. Let's assume that the last key listed above can be resolved
in this way. Then from this key the following key is derived: "tables/table[last()] fields/field/name"
by
appending the remaining part after a whitespace. This key can now be processed using the original algorithm. Keys of
this form can also be used with the setProperty()
method. However, it is still recommended to use the old
format because it makes explicit at which position new nodes should be added. For keys without a whitespace delimiter
there may be ambiguities.
Constructor and Description |
---|
XPathExpressionEngine()
Creates a new instance of
XPathExpressionEngine with default settings. |
Modifier and Type | Method and Description |
---|---|
String |
attributeKey(String parentKey,
String attributeName)
Returns the key of an attribute.
|
<T> String |
canonicalKey(T node,
String parentKey,
NodeHandler<T> handler)
Determines a "canonical" key for the specified node in the expression language supported by this
implementation.
|
<T> String |
nodeKey(T node,
String parentKey,
NodeHandler<T> handler)
Returns the key for the specified node in the expression language supported by an implementation.
|
<T> NodeAddData<T> |
prepareAdd(T root,
String key,
NodeHandler<T> handler)
Returns information needed for an add operation.
|
<T> List<QueryResult<T>> |
query(T root,
String key,
NodeHandler<T> handler)
Finds the nodes and/or attributes that are matched by the specified key.
|
public XPathExpressionEngine()
XPathExpressionEngine
with default settings.public <T> List<QueryResult<T>> query(T root, String key, NodeHandler<T> handler)
NodeHandler
can be used to gather
the required information from the node object. This implementation interprets the passed in key as an XPATH expression.query
in interface ExpressionEngine
T
- the type of the node to be processedroot
- the root node of a hierarchy of nodeskey
- the key to be evaluatedhandler
- the NodeHandler
for accessing the nodepublic <T> String nodeKey(T node, String parentKey, NodeHandler<T> handler)
getKeys()
method. This implementation creates an XPATH expression that selects the given node (under the assumption that
the passed in parent key is valid). As the nodeKey()
implementation of
DefaultExpressionEngine
this method does not
return indices for nodes. So all child nodes of a given parent with the same name have the same key.nodeKey
in interface ExpressionEngine
T
- the type of the node to be processednode
- the node, for which the key must be constructedparentKey
- the key of this node's parent (can be null for the root node)handler
- the NodeHandler
for accessing the nodepublic String attributeKey(String parentKey, String attributeName)
ExpressionEngine
parentKey
must reference the parent node of the attribute. A
concrete implementation must concatenate this parent key with the attribute name to a valid key for this attribute.attributeKey
in interface ExpressionEngine
parentKey
- the key to the node owning this attributeattributeName
- the name of the attribute in questionpublic <T> String canonicalKey(T node, String parentKey, NodeHandler<T> handler)
nodeKey()
, but always adds an index expression to the
resulting key.canonicalKey
in interface ExpressionEngine
T
- the type of the node to be processednode
- the node, for which the key must be constructedparentKey
- the key of this node's parent (can be null for the root node)handler
- the NodeHandler
for accessing the nodepublic <T> NodeAddData<T> prepareAdd(T root, String key, NodeHandler<T> handler)
prepareAdd
in interface ExpressionEngine
T
- the type of the node to be processedroot
- the root nodekey
- the key for the new propertyhandler
- the NodeHandler
for accessing the nodeCopyright © 2001–2022 The Apache Software Foundation. All rights reserved.