BUG-2912: Better document DataChangeScope.ONE

Provides information about the way this scope interacts with lists in and the
binding independent data tree that might be counterintuitive when compared with
a binding aware view of the same data.

Change-Id: If966331b4daa5a88be61fb2efea65a4b69495b0b
Signed-off-by: Colin Dixon <colin@colindixon.com>

diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataBroker.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataBroker.java
index 3a68092f07e27f0ffe56dc090c01a0e04b37d3fd..8b62fd25e805421462ec1dc41dfc09c0601d8d28 100644 (file)
--- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataBroker.java
+++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataBroker.java
@@ -103,14 +103,43 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
     public enum DataChangeScope {
 
         /**
     public enum DataChangeScope {
 
         /**

-         * Represents only a direct change of the node, such as replacement of a
-         * node, addition or deletion.
+         * Represents only a direct change of the node, such as replacement of a node, addition or
+         * deletion. Note that, as described in {@link #ONE}, this may have counterintuitive
+         * interactions when viewed from a <i>binding aware</i> application, in particular when it
+         * pertains to lists.

          *
          */
         BASE,
         /**
          *
          */
         BASE,
         /**

-         * Represent a change (addition,replacement,deletion) of the node or one
-         * of its direct children.
+         * Represent a change (addition,replacement,deletion) of the node or one of its direct
+         * children.
+         * <p>
+         * Note that this is done in the <i>binding independent</i> data tree and so the behavior
+         * might be counterintuitive when used with <i>binding aware</i> interfaces particularly
+         * when it comes to lists. The list itself is a node in the <i>binding independent</i> tree,
+         * which means that if you want to listen on new elements you must listen on the list itself
+         * with the scope of {@link #ONE}.
+         * <p>
+         * As an example, in the below YANG snippet, listening on <tt>node</tt> with scope
+         * {@link #ONE} would tell you if the <tt>node-connector</tt> list was created or deleted,
+         * but not when elements were added or removed from the list assuming the list itself
+         * already existed.
+         *
+         * <pre>
+         * container nodes {
+         *   list node {
+         *     key "id";
+         *     leaf id {
+         *       type string;
+         *     }
+         *     list node-connector {
+         *       leaf id {
+         *         type string;
+         *       }
+         *     }
+         *   }
+         * }
+         * </pre>

          *
          * This scope is superset of {@link #BASE}.
          *
          *
          * This scope is superset of {@link #BASE}.
          *