X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?p=controller.git;a=blobdiff_plain;f=opendaylight%2Fmd-sal%2Fsal-common-api%2Fsrc%2Fmain%2Fjava%2Forg%2Fopendaylight%2Fcontroller%2Fmd%2Fsal%2Fcommon%2Fapi%2Fdata%2FAsyncDataBroker.java;h=dff2f8ba2fa7abfafc0d37fdfb93694bd737296c;hp=3a68092f07e27f0ffe56dc090c01a0e04b37d3fd;hb=99f994b3e45963f6ef46bc2b71ab4dd8eea8b9ac;hpb=5135f2d97f0886632f3ad3b7160a3be54909810f 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 3a68092f07..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,7 +11,6 @@ import org.opendaylight.yangtools.concepts.ListenerRegistration; import org.opendaylight.yangtools.concepts.Path; /** - * * 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. * @@ -32,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()}. * * *

@@ -57,16 +56,15 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange AsyncDataTransactionFactory { /** - * * Scope of Data Change * *

* Represents scope of data change (addition, replacement, deletion). - * * The terminology for scope types is reused from LDAP. * *

Examples

* + *

* 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. @@ -83,6 +81,7 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange * id "b" // scope SUBTREE * * + *

* 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 @@ -97,21 +96,52 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange * * * - * @see http://www.idevelopment.info/data/LDAP/LDAP_Resources/ - * SEARCH_Setting_the_SCOPE_Parameter.shtml + * @see LDAP */ - 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 binding aware 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. + * + *

+ * Note that this is done in the binding independent data tree and so the behavior + * might be counterintuitive when used with binding aware interfaces particularly + * when it comes to lists. The list itself is a node in the binding independent 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}. * + *

+ * As an example, in the below YANG snippet, listening on node with scope + * {@link #ONE} would tell you if the node-connector list was created or deleted, + * but not when elements were added or removed from the list assuming the list itself + * already existed. + * + * 

+         * container nodes {
+         *   list node {
+         *     key "id";
+         *     leaf id {
+         *       type string;
+         *     }
+         *     list node-connector {
+         *       leaf id {
+         *         type string;
+         *       }
+         *     }
+         *   }
+         * }
+         *
+ * + *

* This scope is superset of {@link #BASE}. * */ @@ -120,44 +150,39 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange * Represents a change of the node or any of or any of its child nodes, * direct and nested. * + *

* This scope is superset of {@link #ONE} and {@link #BASE}. * */ SUBTREE } - /** - * {@inheritDoc} - */ @Override - public AsyncReadOnlyTransaction newReadOnlyTransaction(); + AsyncReadOnlyTransaction newReadOnlyTransaction(); - /** - * {@inheritDoc} - */ @Override - public AsyncReadWriteTransaction newReadWriteTransaction(); + AsyncReadWriteTransaction newReadWriteTransaction(); - /** - * {@inheritDoc} - */ @Override - public AsyncWriteTransaction newWriteOnlyTransaction(); + AsyncWriteTransaction newWriteOnlyTransaction(); /** * Registers a {@link AsyncDataChangeListener} to receive * notifications when data changes under a given path in the conceptual data * tree. + * *

* You are able to register for notifications for any node or subtree * which can be reached via the supplied path. + * *

* If path type P allows it, you may specify paths up to the leaf nodes * then it is possible to listen on leaf nodes. + * *

* 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. + * *

* 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 @@ -166,6 +191,7 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange *

* You are also able to specify the scope of the changes you want to be * notified. + * *

* Supported scopes are: *

* See {@link DataChangeScope} for examples. + * *

* This method returns a {@link ListenerRegistration} object. To * "unregister" your listener for changes call the "close" method on this * returned object. + * *

* 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). @@ -204,6 +232,9 @@ public interface AsyncDataBroker

, D, L extends AsyncDataChange * your listener using {@link ListenerRegistration#close()} to stop * delivery of change events. */ - ListenerRegistration registerDataChangeListener(LogicalDatastoreType store, P path, L listener, - DataChangeScope triggeringScope); + @Deprecated + default ListenerRegistration registerDataChangeListener(LogicalDatastoreType store, P path, L listener, + DataChangeScope triggeringScope) { + throw new UnsupportedOperationException("Data change listeners are no longer supported."); + } }