Package org.apache.commons.configuration2.tree

## Interface NodeHandler<T>

- Type Parameters:
    `T` - the type of the nodes this handler deals with
  All Known Subinterfaces:
    `ReferenceNodeHandler`
  All Known Implementing Classes:
    `NodeHandlerDecorator`

      public interface NodeHandler<T>

  Definition of an interface for accessing the data of a configuration node.

  Hierarchical configurations can deal with arbitrary node structures. In order to obtain information about a specific node object, a so-called `NodeHandler` is used. The handler provides a number of methods for querying the internal state of a node in a read-only way.

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `Set<String>` | `getAttributes​(T node)` | Gets an unmodifiable set with the names of all attributes of the specified node.
    `Object` | `getAttributeValue​(T node, String name)` | Gets the value of the specified attribute from the given node.
    `T` | `getChild​(T node, int index)` | Gets the child with the given index of the specified node.
    `List<T>` | `getChildren​(T node)` | Gets an unmodifiable list with all children of the specified node.
    `List<T>` | `getChildren​(T node, String name)` | Gets an unmodifiable list of all children of the specified node with the given name.
    `int` | `getChildrenCount​(T node, String name)` | Gets the number of children of the specified node with the given name.
    `<C> List<T>` | `getMatchingChildren​(T node, NodeMatcher<C> matcher, C criterion)` | Gets an unmodifiable list of all children of the specified node which are matched by the passed in `NodeMatcher` against the provided criterion.
    `<C> int` | `getMatchingChildrenCount​(T node, NodeMatcher<C> matcher, C criterion)` | Gets the number of children of the specified node which are matched by the given `NodeMatcher`.
    `T` | `getParent​(T node)` | Gets the parent of the specified node.
    `T` | `getRootNode()` | Gets the root node of the underlying hierarchy.
    `Object` | `getValue​(T node)` | Gets the value of the specified node.
    `boolean` | `hasAttributes​(T node)` | Returns a flag whether the passed in node has any attributes.
    `int` | `indexOfChild​(T parent, T child)` | Returns the index of the given child node in the list of children of its parent.
    `boolean` | `isDefined​(T node)` | Checks whether the specified node is defined.
    `String` | `nodeName​(T node)` | Returns the name of the specified node

- - ### Method Detail

    - #### nodeName

          String nodeName​(T node)

      Returns the name of the specified node
      Parameters:
        `node` - the node
      Returns:
        the name of this node

    - #### getValue

          Object getValue​(T node)

      Gets the value of the specified node.
      Parameters:
        `node` - the node
      Returns:
        the value of this node

    - #### getParent

          T getParent​(T node)

      Gets the parent of the specified node.
      Parameters:
        `node` - the node
      Returns:
        the parent node

    - #### getChildren

          List<T> getChildren​(T node)

      Gets an unmodifiable list with all children of the specified node.
      Parameters:
        `node` - the node
      Returns:
        a list with the child nodes of this node

    - #### getChildren

          List<T> getChildren​(T node,
                              String name)

      Gets an unmodifiable list of all children of the specified node with the given name.
      Parameters:
        `node` - the node
        `name` - the name of the desired child nodes
      Returns:
        a list with all children with the given name

    - #### getMatchingChildren

          <C> List<T> getMatchingChildren​(T node,
                                          NodeMatcher<C> matcher,
                                          C criterion)

      Gets an unmodifiable list of all children of the specified node which are matched by the passed in `NodeMatcher` against the provided criterion. This method allows for advanced queries on a node's children.
      Type Parameters:
        `C` - the type of the criterion
      Parameters:
        `node` - the node
        `matcher` - the `NodeMatcher` defining filter criteria
        `criterion` - the criterion to be matched against; this object is passed to the `NodeMatcher`
      Returns:
        a list with all children matched by the matcher

    - #### getChild

          T getChild​(T node,
                     int index)

      Gets the child with the given index of the specified node.
      Parameters:
        `node` - the node
        `index` - the index (0-based)
      Returns:
        the child with the given index

    - #### indexOfChild

          int indexOfChild​(T parent,
                           T child)

      Returns the index of the given child node in the list of children of its parent. This method is the opposite operation of `getChild(Object, int)`. This method returns 0 if the given node is the first child node with this name, 1 for the second child node and so on. If the node has no parent node or if it is an attribute, -1 is returned.
      Parameters:
        `parent` - the parent node
        `child` - a child node whose index is to be retrieved
      Returns:
        the index of this child node

    - #### getChildrenCount

          int getChildrenCount​(T node,
                               String name)

      Gets the number of children of the specified node with the given name. This method exists for performance reasons: for some node implementations it may be by far more efficient to count the children than to query a list of all children and determine its size. A concrete implementation can choose the most efficient way to determine the number of children. If a child name is passed in, only the children with this name are taken into account. If the name null is passed, the total number of children must be returned.
      Parameters:
        `node` - the node
        `name` - the name of the children in question (can be null for all children)
      Returns:
        the number of the selected children

    - #### getMatchingChildrenCount

          <C> int getMatchingChildrenCount​(T node,
                                           NodeMatcher<C> matcher,
                                           C criterion)

      Gets the number of children of the specified node which are matched by the given `NodeMatcher`. This is a more generic version of `getChildrenCount(Object, String)`. It allows checking for arbitrary filter conditions.
      Type Parameters:
        `C` - the type of the criterion
      Parameters:
        `node` - the node
        `matcher` - the `NodeMatcher`
        `criterion` - the criterion to be passed to the `NodeMatcher`
      Returns:
        the number of matched children

    - #### getAttributes

          Set<String> getAttributes​(T node)

      Gets an unmodifiable set with the names of all attributes of the specified node.
      Parameters:
        `node` - the node
      Returns:
        a set with the names of all attributes of this node

    - #### hasAttributes

          boolean hasAttributes​(T node)

      Returns a flag whether the passed in node has any attributes.
      Parameters:
        `node` - the node
      Returns:
        a flag whether this node has any attributes

    - #### getAttributeValue

          Object getAttributeValue​(T node,
                                   String name)

      Gets the value of the specified attribute from the given node. If a concrete `NodeHandler` supports attributes with multiple values, result might be a collection.
      Parameters:
        `node` - the node
        `name` - the name of the attribute
      Returns:
        the value of this attribute

    - #### isDefined

          boolean isDefined​(T node)

      Checks whether the specified node is defined. Nodes are "defined" if they contain any data, e.g. a value, or attributes, or defined children.
      Parameters:
        `node` - the node to test
      Returns:
        a flag whether the passed in node is defined

    - #### getRootNode

          T getRootNode()

      Gets the root node of the underlying hierarchy.
      Returns:
        the current root node