commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r1561334 - /commons/proper/configuration/trunk/src/main/java/org/apache/commons/configuration/tree/NodeHandler.java
Date Sat, 25 Jan 2014 16:32:07 GMT
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
+     * &quot;defined&quot; 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);
+}



Mime
View raw message