Package org.apache.commons.configuration2.tree

## Interface NodeKeyResolver<T>

- Type Parameters:
    `T` - the type of the nodes supported by this resolver
  All Known Implementing Classes:
    `AbstractHierarchicalConfiguration`, `AbstractYAMLBasedConfiguration`, `BaseHierarchicalConfiguration`, `CombinedConfiguration`, `DynamicCombinedConfiguration`, `INIConfiguration`, `JSONConfiguration`, `PatternSubtreeConfigurationWrapper`, `PropertyListConfiguration`, `SubnodeConfiguration`, `XMLConfiguration`, `XMLPropertyListConfiguration`, `YAMLConfiguration`

      public interface NodeKeyResolver<T>

  Definition of an interface which allows resolving a (property) key for different manipulating operations.

  This interface is used when interacting with a node model. It is an abstraction over a concrete `ExpressionEngine` instance. It also implements some functionality for creating special helper objects for the processing of complex update operations.

  Since:
    2.0

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `String` | `nodeKey​(T node, Map<T,​String> cache, NodeHandler<T> handler)` | Generates a unique key for the specified node.
    `NodeAddData<T>` | `resolveAddKey​(T root, String key, NodeHandler<T> handler)` | Resolves a key of an add operation.
    `List<QueryResult<T>>` | `resolveKey​(T root, String key, NodeHandler<T> handler)` | Performs a query for the specified key on the given root node.
    `List<T>` | `resolveNodeKey​(T root, String key, NodeHandler<T> handler)` | Performs a query for the specified key on the given root node returning only node results.
    `NodeUpdateData<T>` | `resolveUpdateKey​(T root, String key, Object newValue, NodeHandler<T> handler)` | Resolves a key for an update operation.

- - ### Method Detail

    - #### resolveKey

          List<QueryResult<T>> resolveKey​(T root,
                                          String key,
                                          NodeHandler<T> handler)

      Performs a query for the specified key on the given root node. This is a thin wrapper over the `query()` method of an `ExpressionEngine`.
      Parameters:
        `root` - the root node
        `key` - the key to be resolved
        `handler` - the `NodeHandler`
      Returns:
        a list with query results

    - #### resolveNodeKey

          List<T> resolveNodeKey​(T root,
                                 String key,
                                 NodeHandler<T> handler)

      Performs a query for the specified key on the given root node returning only node results. Some operations require results of type node and do not support attributes (e.g. for tracking nodes). This operation can be used in such cases. It works like `resolveKey()`, but filters only for results of type node.
      Parameters:
        `root` - the root node
        `key` - the key to be resolved
        `handler` - the `NodeHandler`
      Returns:
        a list with the resolved nodes

    - #### resolveAddKey

          NodeAddData<T> resolveAddKey​(T root,
                                       String key,
                                       NodeHandler<T> handler)

      Resolves a key of an add operation. Result is a `NodeAddData` object containing all information for actually performing the add operation at the specified key.
      Parameters:
        `root` - the root node
        `key` - the key to be resolved
        `handler` - the `NodeHandler`
      Returns:
        a `NodeAddData` object to be used for the add operation

    - #### resolveUpdateKey

          NodeUpdateData<T> resolveUpdateKey​(T root,
                                             String key,
                                             Object newValue,
                                             NodeHandler<T> handler)

      Resolves a key for an update operation. Result is a `NodeUpdateData` object containing all information for actually performing the update operation at the specified key using the provided new value object.
      Parameters:
        `root` - the root node
        `key` - the key to be resolved
        `newValue` - the new value for the key to be updated; this can be a single value or a container for multiple values
        `handler` - the `NodeHandler`
      Returns:
        a `NodeUpdateData` object to be used for this update operation

    - #### nodeKey

          String nodeKey​(T node,
                         Map<T,​String> cache,
                         NodeHandler<T> handler)

      Generates a unique key for the specified node. This method is used if keys have to be generated for nodes received as query results. An implementation must generate a canonical key which is compatible with the current expression engine. The passed in map can be used by an implementation as cache. It is created initially by the caller and then passed in subsequent calls. An implementation may use this to avoid that keys for nodes already encountered have to be generated again.
      Parameters:
        `node` - the node in question
        `cache` - a map serving as cache
        `handler` - the `NodeHandler`
      Returns:
        a key for the specified node