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

  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 Details

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

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

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

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

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

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

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

  - ### getParent

    T getParent(T node)
    Gets the parent of the specified node.
    Parameters:
      `node` - the node
    Returns:
      the parent node

  - ### getRootNode

    T getRootNode()
    Gets the root node of the underlying hierarchy.
    Returns:
      the current root node

  - ### getValue

    Object getValue(T node)
    Gets the value of the specified node.
    Parameters:
      `node` - the node
    Returns:
      the value 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

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

  - ### isDefined

    boolean isDefined(T node)
    Checks whether the specified node is defined. Nodes are "defined" if they contain any data, for example a value, or attributes, or defined children.
    Parameters:
      `node` - the node to test
    Returns:
      a flag whether the passed in node is defined

  - ### nodeName

    String nodeName(T node)
    Returns the name of the specified node
    Parameters:
      `node` - the node
    Returns:
      the name of this node