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 and Description
    --- | ---
    `Set<String>` | `getAttributes(T node)` Returns an unmodifiable set with the names of all attributes of the specified node.
    `Object` | `getAttributeValue(T node, String name)` Returns the value of the specified attribute from the given node.
    `T` | `getChild(T node, int index)` Returns the child with the given index of the specified node.
    `List<T>` | `getChildren(T node)` Returns an unmodifiable list with all children of the specified node.
    `List<T>` | `getChildren(T node, String name)` Returns an unmodifiable list of all children of the specified node with the given name.
    `int` | `getChildrenCount(T node, String name)` Returns the number of children of the specified node with the given name.
    `<C> List<T>` | `getMatchingChildren(T node, NodeMatcher<C> matcher, C criterion)` Returns 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)` Returns the number of children of the specified node which are matched by the given `NodeMatcher`.
    `T` | `getParent(T node)` Returns the parent of the specified node.
    `T` | `getRootNode()` Returns the root node of the underlying hierarchy.
    `Object` | `getValue(T node)` Returns 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)

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

    - #### getParent

          T getParent(T node)

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

    - #### getChildren

          List<T> getChildren(T node)

      Returns 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)

      Returns 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)

      Returns 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)

      Returns 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)

      Returns 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)

      Returns 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)

      Returns 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)

      Returns 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()

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

Copyright © 2001–2022 The Apache Software Foundation. All rights reserved.