opendaylight/md-sal/sal-common-api/src/main/java/org/opendaylight/controller/md/sal/common/api/data/AsyncDataChangeEvent.java

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   4  * This program and the accompanying materials are made available under the
   5  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   6  * and is available at http://www.eclipse.org/legal/epl-v10.html
   7  */
   8 package org.opendaylight.controller.md.sal.common.api.data;
   9
  10 import java.util.Map;
  11 import java.util.Set;
  12
  13 import org.opendaylight.yangtools.concepts.Immutable;
  14 import org.opendaylight.yangtools.concepts.Path;
  15
  16 /**
  17  *
  18  * An event which contains a capture of changes in a data subtree
  19  *
  20  * <p>
  21  * Represents a notification indicating that some data at or under a particular
  22  * path has changed. The notification contains a capture of the changes in the data
  23  * subtree. This event is triggered by successful application of modifications
  24  * from a transaction on the global data tree. Use the
  25  * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, AsyncDataBroker.DataChangeScope)}
  26  * method to register a listener for data change events.
  27  *
  28  * <p>
  29  * A listener will only receive notifications for changes to data under the path
  30  * they register for. See
  31  * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener, AsyncDataBroker.DataChangeScope)}
  32  * to learn more about registration scopes.
  33  *
  34  * <p>
  35  * The entire subtree under the path will be provided via instance methods of Data
  36  * Change Event even if just a leaf node changes.
  37  *
  38  * <p>
  39  * <b>Implementation Note:</b> This interface is not intended to be implemented
  40  * by users of MD-SAL, but only to be consumed by them.
  41  *
  42  * @param <P>
  43  *            Type of path (subtree identifier), which represents location in
  44  *            tree
  45  * @param <D>
  46  *            Type of data (payload), which represents data payload
  47  */
  48 public interface AsyncDataChangeEvent<P extends Path<P>, D> extends Immutable {
  49     /**
  50      * Returns a map of paths and newly created objects, which were introduced by
  51      * this change into conceptual data tree, if no new objects were introduced
  52      * this map will be empty.
  53      *<p>
  54      * This map contains all data tree nodes (and paths to them) which were created
  55      * and are in  the scope of listener registration. The data tree nodes
  56      * contain their whole subtree with their current state.
  57      *
  58      * @return map of paths and newly created objects
  59      */
  60     Map<P, D> getCreatedData();
  61
  62     /**
  63      * Returns a map of paths and objects which were updated by this change in the
  64      * conceptual data tree if no existing objects were updated
  65      * this map will be empty.
  66      *<p>
  67      * This map contains all data tree nodes (and paths to them) which were updated
  68      * and are in the scope of listener registration. The data tree nodes
  69      * contain their whole subtree with their current state.
  70      *<p>
  71      * A Node is considered updated if it contents were replaced or one of its
  72      * children was created, removed or updated.
  73      *<p>
  74      * Original state of the updated data tree nodes is in
  75      * {@link #getOriginalData()} stored with same path.
  76      *
  77      * @return map of paths and newly created objects
  78      */
  79     Map<P, D> getUpdatedData();
  80
  81     /**
  82      * Returns an immutable set of removed paths.
  83      *<p>
  84      * This set contains the paths to the data tree nodes which are in the scope
  85      * of the listener registration that have been removed.
  86      *<p>
  87      * Original state of the removed data tree nodes is in
  88      * {@link #getOriginalData()} stored with same path.
  89      *
  90      * @return set of removed paths
  91      */
  92     Set<P> getRemovedPaths();
  93
  94     /**
  95      * Returns an immutable map of updated or removed paths and their original
  96      * states prior to this change.
  97      *
  98      *<p>
  99      * This map contains the original version of the data tree nodes (and paths
 100      * to them), which are in the scope of the listener registration.
 101      *
 102      * @return map of paths and original state of updated and removed objects.
 103      */
 104     Map<P, ? extends D> getOriginalData();
 105
 106     /**
 107      * Returns an immutable stable view of data state, which captures the state of
 108      * data store before the reported change.
 109      *
 110      *<p>
 111      * The view is rooted at the point where the listener, to which the event is
 112      * being delivered, was registered.
 113      *<p>
 114      * If listener used a wildcarded path (if supported by path type) during
 115      * registration for change listeners this method returns null, and original
 116      * state can be accessed only via {@link #getOriginalData()}
 117      *
 118      * @return Stable view of data before the change happened, rooted at the
 119      *         listener registration path.
 120      *
 121      */
 122     D getOriginalSubtree();
 123
 124     /**
 125      * Returns an immutable stable view of data, which captures the state of data
 126      * store after the reported change.
 127      *<p>
 128      * The view is rooted at the point where the listener, to which the event is
 129      * being delivered, was registered.
 130      *<p>
 131      * If listener used a wildcarded path (if supported by path type) during
 132      * registration for change listeners this method returns null, and state
 133      * can be accessed only via {@link #getCreatedData()},
 134      * {@link #getUpdatedData()}, {@link #getRemovedPaths()}
 135      *
 136      * @return Stable view of data after the change happened, rooted at the
 137      *         listener registration path.
 138      */
 139     D getUpdatedSubtree();
 140 }