You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@commons.apache.org by oh...@apache.org on 2014/01/25 17:32:07 UTC
svn commit: r1561334 -
/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/NodeHandler.java
Author: oheger
Date: Sat Jan 25 16:32:07 2014
New Revision: 1561334
URL: http://svn.apache.org/r1561334
Log:
Added NodeHandler interface.
In future we are going to support different types of hierarchical configuration
nodes. The purpose of the NodeHanlder interface is allowing (read-only) access
to the data of a specific node type.
Added:
commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/NodeHandler.java
Added: commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/NodeHandler.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/NodeHandler.java?rev=1561334&view=auto
==============================================================================
--- commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/NodeHandler.java (added)
+++ commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/NodeHandler.java Sat Jan 25 16:32:07 2014
@@ -0,0 +1,156 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.apache.commons.configuration.tree;
+
+import java.util.List;
+
+/**
+ * <p>
+ * Definition of an interface for accessing the data of a configuration node.
+ * </p>
+ * <p>
+ * Hierarchical configurations can deal with arbitrary node structures. In order
+ * to obtain information about a specific node object, a so-called
+ * {@code NodeHandler} is used. The handler provides a number of methods for
+ * querying the internal state of a node in a read-only way.
+ * </p>
+ *
+ * @version $Id$
+ * @param T the type of the nodes this handler deals with
+ */
+public interface NodeHandler<T>
+{
+ /**
+ * Returns the name of the specified node
+ *
+ * @param node the node
+ * @return the name of this node
+ */
+ String nodeName(T node);
+
+ /**
+ * Returns the value of the specified node.
+ *
+ * @param node the node
+ * @return the value of this node
+ */
+ Object getValue(T node);
+
+ /**
+ * Returns the parent of the specified node.
+ *
+ * @param node the node
+ * @return the parent node
+ */
+ T getParent(T node);
+
+ /**
+ * Returns an unmodifiable list with all children of the specified node.
+ *
+ * @param node the node
+ * @return a list with the child nodes of this node
+ */
+ List<T> getChildren(T node);
+
+ /**
+ * Returns an unmodifiable list of all children of the specified node with
+ * the given name.
+ *
+ * @param node the node
+ * @param name the name of the desired child nodes
+ * @return a list with all children with the given name
+ */
+ List<T> getChildren(T node, String name);
+
+ /**
+ * Returns the child with the given index of the specified node.
+ *
+ * @param node the node
+ * @param index the index (0-based)
+ * @return the child with the given index
+ */
+ T getChild(T node, int index);
+
+ /**
+ * Returns the index of the given child node relative to its name. This
+ * method can be called when a unique identifier for a specific node is
+ * needed. The node name alone might not be sufficient because there may be
+ * multiple child nodes with the same name. 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.
+ *
+ * @param node a child node whose index is to be retrieved
+ * @return the index of this child node
+ */
+ int indexOfChild(T node);
+
+ /**
+ * 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 <b>null</b> is passed, the total number of
+ * children must be returned.
+ *
+ * @param node the node
+ * @param name the name of the children in question (can be <b>null</b> for
+ * all children)
+ * @return the number of the selected children
+ */
+ int getChildrenCount(T node, String name);
+
+ /**
+ * Returns an unmodifiable list with the names of all attributes of the
+ * specified node.
+ *
+ * @param node the node
+ * @return a list with the names of all attributes of this node
+ */
+ List<String> getAttributes(T node);
+
+ /**
+ * Returns a flag whether the passed in node has any attributes.
+ *
+ * @param node the node
+ * @return a flag whether this node has any attributes
+ */
+ boolean hasAttributes(T node);
+
+ /**
+ * Returns the value of the specified attribute from the given node. If a
+ * concrete {@code NodeHandler} supports attributes with multiple values,
+ * result might be a collection.
+ *
+ * @param node the node
+ * @param name the name of the attribute
+ * @return the value of this attribute
+ */
+ Object getAttributeValue(T node, String name);
+
+ /**
+ * Checks whether the specified node is defined. Nodes are
+ * "defined" if they contain any data, e.g. a value, or
+ * attributes, or defined children.
+ *
+ * @param node the node to test
+ * @return a flag whether the passed in node is defined
+ */
+ boolean isDefined(T node);
+}