X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;ds=sidebyside;f=opendaylight%2Fmd-sal%2Fsal-common-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fcontroller%2Fmd%2Fsal%2Fcommon%2Fapi%2Fdata%2FAsyncDataBroker.java;h=dff2f8ba2fa7abfafc0d37fdfb93694bd737296c;hb=99f994b3e45963f6ef46bc2b71ab4dd8eea8b9ac;hp=3351bcaaf756ae2f198dc8ef669254e781aed711;hpb=3ce420ccd45e7530c2c2158bd57462fd5859a879;p=controller.git

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 3351bcaaf7..dff2f8ba2f 100644
--- 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
@@ -11,15 +11,11 @@ import org.opendaylight.yangtools.concepts.ListenerRegistration;
 import org.opendaylight.yangtools.concepts.Path;
 
 /**
- *
- * Provides access to a conceptual data tree store.
- *
- * <p>
- * Also provides the ability to subscribe for changes to data under a given
- * branch of the tree.
+ * 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>
- * 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()}
@@ -35,7 +31,7 @@ import org.opendaylight.yangtools.concepts.Path;
  * For a detailed explanation of how transaction are isolated and how transaction-local
  * changes are committed to global data tree, see
  * {@link AsyncReadTransaction}, {@link AsyncWriteTransaction},
- * {@link AsyncReadWriteTransaction} and {@link AsyncWriteTransaction#commit()}.
+ * {@link AsyncReadWriteTransaction} and {@link AsyncWriteTransaction#submit()}.
  *
  *
  * <p>
@@ -60,16 +56,15 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
         AsyncDataTransactionFactory<P, D> {
 
     /**
-     *
      * Scope of Data Change
      *
      * <p>
      * Represents scope of data change (addition, replacement, deletion).
-     *
      * The terminology for scope types is reused from LDAP.
      *
      * <h2>Examples</h2>
      *
+     * <p>
      * Following is an example model with comments describing what notifications
      * you would receive based on the scope you specify, when you are
      * registering for changes on container a.
@@ -86,6 +81,7 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
      *        id "b"            // scope SUBTREE
      * </pre>
      *
+     * <p>
      * Following is an example model with comments describing what notifications
      * you would receive based on the scope you specify, when you are
      * registering for changes on list list (without specifying concrete item in
@@ -100,21 +96,52 @@ 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>
+         *
+         * <p>
          * This scope is superset of {@link #BASE}.
          *
          */
@@ -123,44 +150,39 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
          * Represents a change of the node or any of or any of its child nodes,
          * direct and nested.
          *
+         * <p>
          * This scope is superset of {@link #ONE} and {@link #BASE}.
          *
          */
         SUBTREE
     }
 
-    /**
-     * {@inheritDoc}
-     */
     @Override
-    public AsyncReadOnlyTransaction<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
      * notifications when data changes under a given path in the conceptual data
      * tree.
+     *
      * <p>
      * You are able to register for notifications  for any node or subtree
      * which can be reached via the supplied path.
+     *
      * <p>
      * If path type <code>P</code> allows it, you may specify paths up to the leaf nodes
      * then it is possible to listen on leaf nodes.
+     *
      * <p>
      * You are able to register for data change notifications for a subtree even
-     * if it does not exist. You will receive notification once that node is
-     * created.
+     * if it does not exist. You will receive notification once that node is created.
+     *
      * <p>
      * If there is any preexisting data in data tree on path for which you are
      * registering, you will receive initial data change event, which will
@@ -169,6 +191,7 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
      * <p>
      * You are also able to specify the scope of the changes you want to be
      * notified.
+     *
      * <p>
      * Supported scopes are:
      * <ul>
@@ -183,10 +206,12 @@ public interface AsyncDataBroker<P extends Path<P>, D, L extends AsyncDataChange
      * or replaced.
      * </ul>
      * See {@link DataChangeScope} for examples.
+     *
      * <p>
      * This method returns a {@link ListenerRegistration} object. To
      * "unregister" your listener for changes call the "close" method on this
      * returned object.
+     *
      * <p>
      * You MUST call close when you no longer need to receive notifications
      * (such as during shutdown or for example if your bundle is shutting down).
@@ -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.");
+    }
 }