Add default implementation of registerDataChangeListener

[controller.git] / opendaylight / md-sal / sal-common-api / src / main / java / org / opendaylight / controller / md / sal / common / api / data / AsyncDataBroker.java

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 fb429e5fd1342c0ca675040a315c1b8ad76456c7..528324151710fdf8abd1c670c05f3de38744a04d 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
@@ -12,14 +12,11 @@ import org.opendaylight.yangtools.concepts.Path;
 
 /**
  *
- * Provides access to a conceptual data tree store.
+ * Base interface that provides access to a conceptual data tree store and also provides the ability to
+ * subscribe for changes to data under a given branch of the tree.
  *
  * <p>
- * Also provides the ability to subscribe for changes to data under a given
- * branch of the tree.
- *
- * <p>
- * All operations on data tree are performed via one of the transactions:
+ * All operations on the data tree are performed via one of the transactions:
  * <ul>
  * <li>Read-Only - allocated using {@link #newReadOnlyTransaction()}
  * <li>Write-Only - allocated using {@link #newWriteOnlyTransaction()}
@@ -100,20 +97,48 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
      * </pre>
      *
      *
-     * @see http://www.idevelopment.info/data/LDAP/LDAP_Resources/
-     *      SEARCH_Setting_the_SCOPE_Parameter.shtml
+     * @see <a href="http://www.idevelopment.info/data/LDAP/LDAP_Resources/SEARCH_Setting_the_SCOPE_Parameter.shtml">LDAP</a>
      */
-    public enum DataChangeScope {
+    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}.
          *
@@ -133,19 +158,19 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
      * {@inheritDoc}
      */
     @Override
-    public AsyncReadTransaction<P, D> newReadOnlyTransaction();
+    AsyncReadOnlyTransaction<P, D> newReadOnlyTransaction();
 
     /**
      * {@inheritDoc}
      */
     @Override
-    public AsyncReadWriteTransaction<P, D> newReadWriteTransaction();
+    AsyncReadWriteTransaction<P, D> newReadWriteTransaction();
 
     /**
      * {@inheritDoc}
      */
     @Override
-    public AsyncWriteTransaction<P, D> newWriteOnlyTransaction();
+    AsyncWriteTransaction<P, D> newWriteOnlyTransaction();
 
     /**
      * Registers a {@link AsyncDataChangeListener} to receive
@@ -207,6 +232,9 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
      *         your listener using {@link ListenerRegistration#close()} to stop
      *         delivery of change events.
      */
-    ListenerRegistration<L> registerDataChangeListener(LogicalDatastoreType store, P path, L listener,
-            DataChangeScope triggeringScope);
+    @Deprecated
+    default ListenerRegistration<L> registerDataChangeListener(LogicalDatastoreType store, P path, L listener,
+            DataChangeScope triggeringScope) {
+        throw new UnsupportedOperationException("Data change listeners are no longer supported.");
+    }
 }