commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ohe...@apache.org
Subject svn commit: r1578581 - in /commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration: BaseHierarchicalConfiguration.java HierarchicalConfiguration.java
Date Mon, 17 Mar 2014 21:11:31 GMT
Author: oheger
Date: Mon Mar 17 21:11:30 2014
New Revision: 1578581

URL: http://svn.apache.org/r1578581
Log:
Changed the HierarchicalConfiguration interface regarding sub configurations.

The configurationAt() methods no longer return SubnodeConfiguration objects.
Rather, the type was made more general to HierarchicalConfiguration<T>.

Modified:
    commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java
    commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/HierarchicalConfiguration.java

Modified: commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java?rev=1578581&r1=1578580&r2=1578581&view=diff
==============================================================================
--- commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java
(original)
+++ commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/BaseHierarchicalConfiguration.java
Mon Mar 17 21:11:30 2014
@@ -356,7 +356,7 @@ public class BaseHierarchicalConfigurati
      * configuration represents one of the nodes selected by the passed in key
      * @since 1.3
      */
-    public List<SubnodeConfiguration> configurationsAt(String key)
+    public List<HierarchicalConfiguration<ImmutableNode>> configurationsAt(String
key)
     {
         beginWrite(false);
         try
@@ -396,7 +396,7 @@ public class BaseHierarchicalConfigurati
      * given key. If not a single node is selected, an empty list is returned.
      * Otherwise, sub configurations for each child of the node are created.
      */
-    public List<SubnodeConfiguration> childConfigurationsAt(String key)
+    public List<HierarchicalConfiguration<ImmutableNode>> childConfigurationsAt(String
key)
     {
         beginWrite(false);
         try

Modified: commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/HierarchicalConfiguration.java
URL: http://svn.apache.org/viewvc/commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/HierarchicalConfiguration.java?rev=1578581&r1=1578580&r2=1578581&view=diff
==============================================================================
--- commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/HierarchicalConfiguration.java
(original)
+++ commons/proper/configuration/branches/immutableNodes/src/main/java/org/apache/commons/configuration/HierarchicalConfiguration.java
Mon Mar 17 21:11:30 2014
@@ -93,7 +93,7 @@ public interface HierarchicalConfigurati
 
     /**
      * <p>
-     * Returns a hierarchical subnode configuration object that wraps the
+     * Returns a hierarchical sub configuration object that wraps the
      * configuration node specified by the given key. This method provides an
      * easy means of accessing sub trees of a hierarchical configuration. In the
      * returned configuration the sub tree can directly be accessed, it becomes
@@ -107,37 +107,32 @@ public interface HierarchicalConfigurati
      * {@code subset()} supports arbitrary subsets of configuration nodes
      * while {@code configurationAt()} only returns a single sub tree.
      * Please refer to the documentation of the
-     * {@code SubnodeConfiguration} class to obtain further information
-     * about subnode configurations and when they should be used.
+     * {@link SubnodeConfiguration} class to obtain further information
+     * about sub configurations and when they should be used.
      * </p>
      * <p>
      * With the {@code supportUpdate} flag the behavior of the returned
-     * {@code SubnodeConfiguration} regarding updates of its parent
-     * configuration can be determined. A subnode configuration operates on the
-     * same nodes as its parent, so changes at one configuration are normally
-     * directly visible for the other configuration. There are however changes
-     * of the parent configuration, which are not recognized by the subnode
-     * configuration per default. An example for this is a reload operation (for
-     * file-based configurations): Here the complete node set of the parent
-     * configuration is replaced, but the subnode configuration still references
-     * the old nodes. If such changes should be detected by the subnode
-     * configuration, the {@code supportUpdates} flag must be set to
-     * <b>true</b>. This causes the subnode configuration to reevaluate the key
-     * used for its creation each time it is accessed. This guarantees that the
-     * subnode configuration always stays in sync with its key, even if the
-     * parent configuration's data significantly changes. If such a change
-     * makes the key invalid - because it now no longer points to exactly one
-     * node -, the subnode configuration is not reconstructed, but keeps its
-     * old data. It is then quasi detached from its parent.
+     * sub configuration regarding updates of its parent
+     * configuration can be determined. If set to <b>false</b>, the configurations
+     * return on independent nodes structures. So changes made on one configuration
+     * cannot be seen by the other one. A value of <b>true</b> in contrast creates
+     * a direct connection between both configurations - they are then using the
+     * same underlying data structures as much as possible. There are however changes
+     * which break this connection; for instance, if the sub tree the sub configuration
+     * belongs to is completely removed from the parent configuration. If such a
+     * change happens, the sub configuration becomes detached from its parent.
+     * It can still be used in a normal way, but changes on it are not reflected
+     * by the parent and vice verse. Also, it is not possible to reattach a once
+     * detached sub configuration.
      * </p>
      *
      * @param key the key that selects the sub tree
-     * @param supportUpdates a flag whether the returned subnode configuration
-     * should be able to handle updates of its parent
+     * @param supportUpdates a flag whether the returned sub configuration
+     * should be directly connected to its parent
      * @return a hierarchical configuration that contains this sub tree
      * @see SubnodeConfiguration
      */
-    SubnodeConfiguration configurationAt(String key, boolean supportUpdates);
+    HierarchicalConfiguration<T> configurationAt(String key, boolean supportUpdates);
 
     /**
      * Returns a hierarchical subnode configuration for the node specified by
@@ -148,12 +143,12 @@ public interface HierarchicalConfigurati
      * @return a hierarchical configuration that contains this sub tree
      * @see SubnodeConfiguration
      */
-    SubnodeConfiguration configurationAt(String key);
+    HierarchicalConfiguration<T> configurationAt(String key);
 
     /**
      * Returns a list of sub configurations for all configuration nodes selected
      * by the given key. This method will evaluate the passed in key (using the
-     * current {@code ExpressionEngine}) and then create a subnode
+     * current {@code ExpressionEngine}) and then create a sub
      * configuration for each returned node (like
      * {@link #configurationAt(String)}}). This is especially
      * useful when dealing with list-like structures. As an example consider the
@@ -176,7 +171,7 @@ public interface HierarchicalConfigurati
      * @return a list with hierarchical configuration objects; each
      * configuration represents one of the nodes selected by the passed in key
      */
-    List<SubnodeConfiguration> configurationsAt(String key);
+    List<HierarchicalConfiguration<T>> configurationsAt(String key);
 
     /**
      * Returns a list with sub configurations for all child nodes of the node
@@ -188,7 +183,7 @@ public interface HierarchicalConfigurati
      * @return a collection with {@code SubnodeConfiguration} objects for all
      *         child nodes of the selected parent node
      */
-    List<SubnodeConfiguration> childConfigurationsAt(String key);
+    List<HierarchicalConfiguration<T>> childConfigurationsAt(String key);
 
     /**
      * Removes all values of the property with the given name and of keys that



Mime
View raw message