BUG-2912: Better document DataChangeScope.ONE 11/34911/4
authorColin Dixon <colin@colindixon.com>
Tue, 16 Feb 2016 18:06:50 +0000 (13:06 -0500)
committerTom Pantelis <tpanteli@brocade.com>
Sun, 21 Feb 2016 16:02:15 +0000 (16:02 +0000)
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>
opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataBroker.java

index 3a68092..8b62fd2 100644 (file)
@@ -103,14 +103,43 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
     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,
         /**
-         * 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}.
          *