Class XPathExpressionEngine
- java.lang.Object
-
- org.apache.commons.configuration.tree.xpath.XPathExpressionEngine
-
- All Implemented Interfaces:
ExpressionEngine
public class XPathExpressionEngine extends java.lang.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:
- An XPATH expression selecting a single node, to which the new element(s) are to be added. This can be an arbitrary complex expression, but it must select exactly one node, otherwise an exception will be thrown.
- The name of the new element(s) to be added below this parent node. Here either a single node name or a complete path of nodes (separated by the "/" character or "@" for an attribute) can be specified.
addProperty()
method follow:"/tables/table[1] type"
This will add a new
type
node as a child of the firsttable
element."/tables/table[1] @type"
Similar to the example above, but this time a new attribute named
type
will be added to the firsttable
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 nodestable
,fields
,field
, andname
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 thesetProperty()
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.- Since:
- 1.3
- Version:
- $Id: XPathExpressionEngine.java 1206563 2011-11-26 19:47:26Z oheger $
- Author:
- Commons Configuration team
-
-
Constructor Summary
Constructors Constructor Description XPathExpressionEngine()
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description protected org.apache.commons.jxpath.JXPathContext
createContext(ConfigurationNode root, java.lang.String key)
Creates theJXPathContext
used for executing a query.protected void
initNodeAddData(NodeAddData data, java.lang.String path)
Initializes most properties of aNodeAddData
object.java.lang.String
nodeKey(ConfigurationNode node, java.lang.String parentKey)
Returns a (canonical) key for the given node based on the parent's key.NodeAddData
prepareAdd(ConfigurationNode root, java.lang.String key)
Prepares an add operation for a configuration property.java.util.List<ConfigurationNode>
query(ConfigurationNode root, java.lang.String key)
Executes a query.
-
-
-
Method Detail
-
query
public java.util.List<ConfigurationNode> query(ConfigurationNode root, java.lang.String key)
Executes a query. The passed in property key is directly passed to a JXPath context.- Specified by:
query
in interfaceExpressionEngine
- Parameters:
root
- the configuration root nodekey
- the query to be executed- Returns:
- a list with the nodes that are selected by the query
-
nodeKey
public java.lang.String nodeKey(ConfigurationNode node, java.lang.String parentKey)
Returns a (canonical) key for the given node based on the parent's key. This implementation will create an XPATH expression that selects the given node (under the assumption that the passed in parent key is valid). As thenodeKey()
implementation ofDefaultExpressionEngine
this method will not return indices for nodes. So all child nodes of a given parent with the same name will have the same key.- Specified by:
nodeKey
in interfaceExpressionEngine
- Parameters:
node
- the node for which a key is to be constructedparentKey
- the key of the parent node- Returns:
- the key for the given node
-
prepareAdd
public NodeAddData prepareAdd(ConfigurationNode root, java.lang.String key)
Prepares an add operation for a configuration property. The expected format of the passed in key is explained in the class comment.- Specified by:
prepareAdd
in interfaceExpressionEngine
- Parameters:
root
- the configuration's root nodekey
- the key describing the target of the add operation and the path of the new node- Returns:
- a data object to be evaluated by the calling configuration object
-
createContext
protected org.apache.commons.jxpath.JXPathContext createContext(ConfigurationNode root, java.lang.String key)
Creates theJXPathContext
used for executing a query. This method will create a new context and ensure that it is correctly initialized.- Parameters:
root
- the configuration root nodekey
- the key to be queried- Returns:
- the new context
-
initNodeAddData
protected void initNodeAddData(NodeAddData data, java.lang.String path)
Initializes most properties of aNodeAddData
object. This method is called byprepareAdd()
after the parent node has been found. Its task is to interpret the passed in path of the new node.- Parameters:
data
- the data object to initializepath
- the path of the new node
-
-