## org.apache.commons.configuration.tree.xpath
Class XPathExpressionEngine

    java.lang.Object
      org.apache.commons.configuration.tree.xpath.XPathExpressionEngine

All Implemented Interfaces:
  ExpressionEngine

    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 439648 2006-09-02 20:42:10Z oheger $
Author:
  Oliver Heger

Field Summary
`(package private) static String` `ATTR_DELIMITER` Constant for the attribute delimiter.
`(package private) static String` `PATH_DELIMITER` Constant for the path delimiter.

Constructor Summary
`XPathExpressionEngine()`

Method Summary
`protected org.apache.commons.jxpath.JXPathContext` `createContext(ConfigurationNode root, String key)` Creates the `JXPathContext` used for executing a query.
`protected void` `initNodeAddData(NodeAddData data, String path)` Initializes most properties of a `NodeAddData` object.
`String` `nodeKey(ConfigurationNode node, String parentKey)` Returns a (canonic) key for the given node based on the parent's key.
`NodeAddData` `prepareAdd(ConfigurationNode root, String key)` Prepares an add operation for a configuration property.
`List` `query(ConfigurationNode root, String key)` Executes a query.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### PATH_DELIMITER

    static final String PATH_DELIMITER

  Constant for the path delimiter.

  See Also:
    Constant Field Values

### ATTR_DELIMITER

    static final String ATTR_DELIMITER

  Constant for the attribute delimiter.

  See Also:
    Constant Field Values

Constructor Detail

### XPathExpressionEngine

    public XPathExpressionEngine()

Method Detail

### query

    public List query(ConfigurationNode root,
                      String key)

  Executes a query. The passed in property key is directly passed to a JXPath context.

  Specified by:
    `query` in interface `ExpressionEngine`
  Parameters:
    `root` - the configuration root node
    `key` - the query to be executed
  Returns:
    a list with the nodes that are selected by the query

### 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.

  Specified by:
    `nodeKey` in interface `ExpressionEngine`
  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.

  Specified by:
    `prepareAdd` in interface `ExpressionEngine`
  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

### createContext

    protected org.apache.commons.jxpath.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

Copyright © 2001-2006 The Apache Software Foundation. All Rights Reserved.