org.apache.commons.configuration.tree.xpath

Class XPathExpressionEngine

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 powerfull 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:

  1. 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.
  2. 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) can be specified.
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.

Since: 1.3

Version: $Id: XPathExpressionEngine.java 466413 2006-10-21 15:23:45Z oheger $

Author: Oliver Heger

Field Summary
static StringATTR_DELIMITER
Constant for the attribute delimiter.
static StringNODE_PATH_DELIMITERS
Constant for the delimiters for splitting node paths.
static StringPATH_DELIMITER
Constant for the path delimiter.
Method Summary
protected JXPathContextcreateContext(ConfigurationNode root, String key)
Creates the JXPathContext used for executing a query.
protected voidinitNodeAddData(NodeAddData data, String path)
Initializes most properties of a NodeAddData object.
voidinvalidPath(String path, String msg)
Helper method for throwing an exception about an invalid path.
StringnodeKey(ConfigurationNode node, String parentKey)
Returns a (canonic) key for the given node based on the parent's key.
NodeAddDataprepareAdd(ConfigurationNode root, String key)
Prepares an add operation for a configuration property.
Listquery(ConfigurationNode root, String key)
Executes a query.

Field Detail

ATTR_DELIMITER

static final String ATTR_DELIMITER
Constant for the attribute delimiter.

NODE_PATH_DELIMITERS

private static final String NODE_PATH_DELIMITERS
Constant for the delimiters for splitting node paths.

PATH_DELIMITER

static final String PATH_DELIMITER
Constant for the path delimiter.

Method Detail

createContext

protected JXPathContext createContext(ConfigurationNode root, String key)
Creates the JXPathContext used for executing a query. This method will create a new context and ensure that it is correctly initialized.

Parameters: root the configuration root node key the key to be queried

Returns: the new context

initNodeAddData

protected void initNodeAddData(NodeAddData data, String path)
Initializes most properties of a NodeAddData object. This method is called by prepareAdd() after the parent node has been found. Its task is to interprete the passed in path of the new node.

Parameters: data the data object to initialize path the path of the new node

invalidPath

private void invalidPath(String path, String msg)
Helper method for throwing an exception about an invalid path.

Parameters: path the invalid path msg the exception message

nodeKey

public String nodeKey(ConfigurationNode node, String parentKey)
Returns a (canonic) 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 the nodeKey() implementation of DefaultExpressionEngine this method will not return indices for nodes. So all child nodes of a given parent whith the same name will have the same key.

Parameters: node the node for which a key is to be constructed parentKey the key of the parent node

Returns: the key for the given node

prepareAdd

public NodeAddData prepareAdd(ConfigurationNode root, String key)
Prepares an add operation for a configuration property. The expected format of the passed in key is explained in the class comment.

Parameters: root the configuration's root node key 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

query

public List query(ConfigurationNode root, String key)
Executes a query. The passed in property key is directly passed to a JXPath context.

Parameters: root the configuration root node key the query to be executed

Returns: a list with the nodes that are selected by the query