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%2FAsyncDataChangeEvent.java;h=29c9bae31f76e2b1a1269116c2b3438cfa572172;hb=44a86821d69cd804b6b23b437e0b27136eaac2b5;hp=f612e51747aa4cb5e066cb00b6fd85bea74ed0a3;hpb=9fda938ef6dc037ef1c5a9fbed25469d4a532150;p=controller.git diff --git a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeEvent.java b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeEvent.java index f612e51747..29c9bae31f 100644 --- a/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeEvent.java +++ b/opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeEvent.java @@ -13,63 +13,128 @@ import java.util.Set; import org.opendaylight.yangtools.concepts.Immutable; import org.opendaylight.yangtools.concepts.Path; -public interface AsyncDataChangeEvent
,D> extends Immutable { +/** + * + * An event which contains a capture of changes in a data subtree + * + *
+ * Represents a notification indicating that some data at or under a particular + * path has changed. The notification contains a capture of the changes in the data + * subtree. This event is triggered by successful application of modifications + * from a transaction on the global data tree. Use the + * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, AsyncDataBroker.DataChangeScope)} + * method to register a listener for data change events. + * + *
+ * A listener will only receive notifications for changes to data under the path + * they register for. See + * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, AsyncDataBroker.DataChangeScope)} + * to learn more about registration scopes. + * + *
+ * The entire subtree under the path will be provided via instance methods of Data + * Change Event even if just a leaf node changes. + * + *
+ * Implementation Note: This interface is not intended to be implemented + * by users of MD-SAL, but only to be consumed by them. + * + * @param
+ * Type of path (subtree identifier), which represents location in
+ * tree
+ * @param , D> extends Immutable {
/**
- * Returns a immutable map of paths and newly created objects
+ * Returns a map of paths and newly created objects, which were introduced by
+ * this change into conceptual data tree, if no new objects were introduced
+ * this map will be empty.
+ *
+ * This map contains all data tree nodes (and paths to them) which were created
+ * and are in the scope of listener registration. The data tree nodes
+ * contain their whole subtree with their current state.
*
* @return map of paths and newly created objects
*/
Map getCreatedData();
/**
- * Returns a immutable map of paths and respective updated objects after update.
- *
- * Original state of the object is in
- * {@link #getOriginalData()}
+ * Returns a map of paths and objects which were updated by this change in the
+ * conceptual data tree if no existing objects were updated
+ * this map will be empty.
+ *
+ * This map contains all data tree nodes (and paths to them) which were updated
+ * and are in the scope of listener registration. The data tree nodes
+ * contain their whole subtree with their current state.
+ *
+ * A Node is considered updated if it contents were replaced or one of its
+ * children was created, removed or updated.
+ *
+ * Original state of the updated data tree nodes is in
+ * {@link #getOriginalData()} stored with same path.
*
* @return map of paths and newly created objects
*/
Map getUpdatedData();
/**
- * Returns a immutable set of removed paths.
- *
- * Original state of the object is in
- * {@link #getOriginalData()}
+ * Returns an immutable set of removed paths.
+ *
+ * This set contains the paths to the data tree nodes which are in the scope
+ * of the listener registration that have been removed.
+ *
+ * Original state of the removed data tree nodes is in
+ * {@link #getOriginalData()} stored with same path.
*
* @return set of removed paths
*/
Set getRemovedPaths();
/**
- * Return a immutable map of paths and original state of updated and removed objects.
+ * Returns an immutable map of updated or removed paths and their original
+ * states prior to this change.
*
- * This map is populated if at changed path was previous object, and captures
- * state of previous object.
+ *
+ * This map contains the original version of the data tree nodes (and paths
+ * to them), which are in the scope of the listener registration.
*
* @return map of paths and original state of updated and removed objects.
*/
Map getOriginalData();
/**
- * Returns a immutable stable view of data state, which
- * captures state of data store before the reported change.
+ * Returns an immutable stable view of data state, which captures the state of
+ * data store before the reported change.
*
+ *
+ * The view is rooted at the point where the listener, to which the event is
+ * being delivered, was registered.
+ *
+ * If listener used a wildcarded path (if supported by path type) during
+ * registration for change listeners this method returns null, and original
+ * state can be accessed only via {@link #getOriginalData()}
*
- * The view is rooted at the point where the listener, to which the event is being delivered, was registered.
- *
- * @return Stable view of data before the change happened, rooted at the listener registration path.
+ * @return Stable view of data before the change happened, rooted at the
+ * listener registration path.
*
*/
D getOriginalSubtree();
/**
- * Returns a immutable stable view of data, which captures state of data store
- * after the reported change.
- *
- * The view is rooted at the point where the listener, to which the event is being delivered, was registered.
+ * Returns an immutable stable view of data, which captures the state of data
+ * store after the reported change.
+ *
+ * The view is rooted at the point where the listener, to which the event is
+ * being delivered, was registered.
+ *
+ * If listener used a wildcarded path (if supported by path type) during
+ * registration for change listeners this method returns null, and state
+ * can be accessed only via {@link #getCreatedData()},
+ * {@link #getUpdatedData()}, {@link #getRemovedPaths()}
*
- * @return Stable view of data after the change happened, rooted at the listener registration path.
+ * @return Stable view of data after the change happened, rooted at the
+ * listener registration path.
*/
D getUpdatedSubtree();
}