[06/28] brooklyn-server git commit: document better config inheritance semantics

[he...@apache.org]

document better config inheritance semantics


Project: http://git-wip-us.apache.org/repos/asf/brooklyn-server/repo
Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-server/commit/aef2c7c5
Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-server/tree/aef2c7c5
Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-server/diff/aef2c7c5

Branch: refs/heads/master
Commit: aef2c7c55f854027bc79bf9ec3ada336ff86955f
Parents: 53ae1c6
Author: Alex Heneveld <al...@cloudsoftcorp.com>
Authored: Thu Nov 24 16:29:21 2016 +0000
Committer: Alex Heneveld <al...@Alexs-MacBook-Pro.local>
Committed: Tue Dec 6 10:05:21 2016 +0000

----------------------------------------------------------------------
 .../brooklyn/config/ConfigInheritance.java      | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/brooklyn-server/blob/aef2c7c5/utils/common/src/main/java/org/apache/brooklyn/config/ConfigInheritance.java
----------------------------------------------------------------------
diff --git a/utils/common/src/main/java/org/apache/brooklyn/config/ConfigInheritance.java b/utils/common/src/main/java/org/apache/brooklyn/config/ConfigInheritance.java
index 3100c8c..203348e 100644
--- a/utils/common/src/main/java/org/apache/brooklyn/config/ConfigInheritance.java
+++ b/utils/common/src/main/java/org/apache/brooklyn/config/ConfigInheritance.java
@@ -61,14 +61,18 @@ public interface ConfigInheritance extends Serializable {
 
     /** Returns whether any value from the given node or ancestors can be considered 
      * for inheritance by descendants, according to the {@link ConfigInheritance} defined there.
-     * Implementations should not normally consider the value here
-     * as there may be other ancestors whose values have not yet been considered and are not supplied.
+     * The implementation of this method is usually a constant depending on the inheritance in effect;
+     * in particular it will not normally consider any values or inform whether something should be inherited:
+     * it is only advising whether inheritance is permitted <i>from</i> a given point in the inheritance hierarchy.
      * <p> 
      * If there is a {@link ConfigInheritance} defined at this node,
      * this method must be called on that instance and that instance only.
      * In that case it is an error to invoke this method on any other {@link ConfigInheritance} instance. 
-     * If there is not one, the config generally should be considered reinheritable;
-     * callers will typically not invoke this method from a descendant inheritance context.
+     * If there is not one, the config generally should be considered reinheritable.
+     * <p>
+     * Key inference (continuing from the above): Callers should not try to infer any descendant key and look at 
+     * what it says about reinheritability;
+     * if a container does not define a key it would be pointless for it not to be reinheritable).
      * <p>
      * Consumers will typically find the methods in {@link ConfigInheritances} more convenient. */
     public <TContainer,TValue> boolean isReinheritable(
@@ -85,7 +89,10 @@ public interface ConfigInheritance extends Serializable {
      * <p>
      * If there is a {@link ConfigInheritance} defined at the local container,
      * this method must be called on that instance and that instance only.
-     * In that case it is an error to invoke this method on any other {@link ConfigInheritance} instance. 
+     * In that case it is an error to invoke this method on any other {@link ConfigInheritance} instance.
+     * <p>
+     * Key inference: if a container does not define a key, the inheritance in the key definition in the nearest descendant
+     * of that container should be used.
      * <p>
      * Consumers should consider this in conjuction with the 
      * {@link #isReinheritable(ConfigValueAtContainer, ConfigInheritanceContext)}
@@ -112,6 +119,9 @@ public interface ConfigInheritance extends Serializable {
      * this method must be called on that instance and that instance only.
      * In that case it is an error to invoke this method on any other {@link ConfigInheritance} instance. 
      * <p>
+     * Key inference: if a container does not define a key, the inheritance in the key definition in the nearest descendant
+     * of that container should be used.
+     * <p>
      * Consumers will typically find the methods in {@link ConfigInheritances} more convenient. */
     public <TContainer,TValue> ReferenceWithError<ConfigValueAtContainer<TContainer,TValue>> resolveWithParent(
         @Nonnull ConfigValueAtContainer<TContainer,TValue> local,