ExpressionEngine (Apache Commons Configuration 2.15.1 API)
Description: declaration: package: org.apache.commons.configuration2.tree, interface: ExpressionEngine

Package org.apache.commons.configuration2.tree

# Interface ExpressionEngine

All Known Implementing Classes:
  `DefaultExpressionEngine`, `XPathExpressionEngine`

public interface ExpressionEngine

Definition of an interface for evaluating keys for hierarchical configurations.

An expression engine knows how to map a key for a configuration's property to a single or a set of configuration nodes. Thus it defines the way how properties are addressed in this configuration. Methods of a configuration that have to handle property keys (for example `getProperty()` or `addProperty()` do not interpret the passed in keys on their own, but delegate this task to an associated expression engine. This expression engine will then find out, which configuration nodes are addressed by the key.

Separating the task of evaluating property keys from the configuration object has the advantage that multiple different expression languages (i.e. ways for querying or setting properties) can be supported. Just set a suitable implementation of this interface as the configuration's expression engine, and you can use the syntax provided by this implementation.

An `ExpressionEngine` can deal with nodes of different types. To achieve this, a `NodeHandler` for the desired type must be passed to the methods.

Since:
  1.3

- ## Method Summary

  Modifier and Type
  Method
  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.

- ## Method Details

  - ### attributeKey

    String attributeKey(String parentKey, String attributeName)
    Returns the key of an attribute. The passed in `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.
    Parameters:
      `parentKey` - the key to the node owning this attribute
      `attributeName` - the name of the attribute in question
    Returns:
      the resulting key referencing this attribute

  - ### canonicalKey

    <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. This means that always a unique key if generated pointing to this specific node. For most concrete implementations, this means that an index is added to the node name to ensure that there are no ambiguities with child nodes having the same names.
    Type Parameters:
      `T` - the type of the node to be processed
    Parameters:
      `node` - the node, for which the key must be constructed
      `parentKey` - the key of this node's parent (can be null for the root node)
      `handler` - the `NodeHandler` for accessing the node
    Returns:
      the canonical key of this node

  - ### nodeKey

    <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. This method is called whenever a property key for a node has to be constructed, for example by the `getKeys()` method.
    Type Parameters:
      `T` - the type of the node to be processed
    Parameters:
      `node` - the node, for which the key must be constructed
      `parentKey` - the key of this node's parent (can be null for the root node)
      `handler` - the `NodeHandler` for accessing the node
    Returns:
      this node's key

  - ### prepareAdd

    <T> NodeAddData<T> prepareAdd(T root, String key, NodeHandler<T> handler)
    Returns information needed for an add operation. This method gets called when new properties are to be added to a configuration. An implementation has to interpret the specified key, find the parent node for the new elements, and provide all information about new nodes to be added.
    Type Parameters:
      `T` - the type of the node to be processed
    Parameters:
      `root` - the root node
      `key` - the key for the new property
      `handler` - the `NodeHandler` for accessing the node
    Returns:
      an object with all information needed for the add operation

  - ### query

    <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. This is the main method for interpreting property keys. An implementation must traverse the given root node and its children to find all results that are matched by the given key. If the key is not correct in the syntax provided by that implementation, it is free to throw a (runtime) exception indicating this error condition. The passed in `NodeHandler` can be used to gather the required information from the node object.
    Type Parameters:
      `T` - the type of the node to be processed
    Parameters:
      `root` - the root node of a hierarchy of nodes
      `key` - the key to be evaluated
      `handler` - the `NodeHandler` for accessing the node
    Returns:
      a list with the results that are matched by the key (should never be null)