X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?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;hb=21bdb94a95aa53487475bcceea70d4f0bb323efa;hp=fb429e5fd1342c0ca675040a315c1b8ad76456c7;hpb=81bbe76bd26399118d028663d08e464ce6b7d040;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 fb429e5fd1..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. - * - *
- * 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. * *
- * 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: *
@@ -60,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. * *
* 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
, 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 @@ -100,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}. * */ @@ -123,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 AsyncReadTransaction
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 @@ -169,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: *
, D, L extends AsyncDataChange * or replaced. *
* 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). @@ -207,6 +232,9 @@ public interface AsyncDataBroker
, D, L extends AsyncDataChange
* your listener using {@link ListenerRegistration#close()} to stop
* delivery of change events.
*/
- ListenerRegistration