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 import org.opendaylight.yangtools.concepts.Immutable;
  13 import org.opendaylight.yangtools.concepts.Path;
  14
  15 /**
  16  * An event which contains a capture of changes in a data subtree.
  17  *
  18  * <p>
  19  * Represents a notification indicating that some data at or under a particular
  20  * path has changed. The notification contains a capture of the changes in the data
  21  * subtree. This event is triggered by successful application of modifications
  22  * from a transaction on the global data tree. Use the
  23  * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener,
  24  *     AsyncDataBroker.DataChangeScope)}
  25  * method to register a listener for data change events.
  26  *
  27  * <p>
  28  * A listener will only receive notifications for changes to data under the path
  29  * they register for. See
  30  * {@link AsyncDataBroker#registerDataChangeListener(LogicalDatastoreType, Path, AsyncDataChangeListener,
  31  *     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      *
  54      * <p>
  55      * This map contains all data tree nodes (and paths to them) which were created
  56      * and are in  the scope of listener registration. The data tree nodes
  57      * contain their whole subtree with their current state.
  58      *
  59      * @return map of paths and newly created objects
  60      */
  61     Map<P, D> getCreatedData();
  62
  63     /**
  64      * Returns a map of paths and objects which were updated by this change in the
  65      * conceptual data tree if no existing objects were updated
  66      * this map will be empty.
  67      *
  68      * <p>
  69      * This map contains all data tree nodes (and paths to them) which were updated
  70      * and are in the scope of listener registration. The data tree nodes
  71      * contain their whole subtree with their current state.
  72      *
  73      * <p>
  74      * A Node is considered updated if it contents were replaced or one of its
  75      * children was created, removed or updated.
  76      *
  77      * <p>
  78      * Original state of the updated data tree nodes is in
  79      * {@link #getOriginalData()} stored with same path.
  80      *
  81      * @return map of paths and newly created objects
  82      */
  83     Map<P, D> getUpdatedData();
  84
  85     /**
  86      * Returns an immutable set of removed paths.
  87      *
  88      * <p>
  89      * This set contains the paths to the data tree nodes which are in the scope
  90      * of the listener registration that have been removed.
  91      *
  92      * <p>
  93      * Original state of the removed data tree nodes is in
  94      * {@link #getOriginalData()} stored with same path.
  95      *
  96      * @return set of removed paths
  97      */
  98     Set<P> getRemovedPaths();
  99
 100     /**
 101      * Returns an immutable map of updated or removed paths and their original
 102      * states prior to this change.
 103      *
 104      *<p>
 105      * This map contains the original version of the data tree nodes (and paths
 106      * to them), which are in the scope of the listener registration.
 107      *
 108      * @return map of paths and original state of updated and removed objects.
 109      */
 110     Map<P, D> getOriginalData();
 111
 112     /**
 113      * Returns an immutable stable view of data state, which captures the state of
 114      * data store before the reported change.
 115      *
 116      *<p>
 117      * The view is rooted at the point where the listener, to which the event is
 118      * being delivered, was registered.
 119      *
 120      * <p>
 121      * If listener used a wildcarded path (if supported by path type) during
 122      * registration for change listeners this method returns null, and original
 123      * state can be accessed only via {@link #getOriginalData()}
 124      *
 125      * @return Stable view of data before the change happened, rooted at the
 126      *         listener registration path.
 127      *
 128      */
 129     D getOriginalSubtree();
 130
 131     /**
 132      * Returns an immutable stable view of data, which captures the state of data
 133      * store after the reported change.
 134      *
 135      * <p>
 136      * The view is rooted at the point where the listener, to which the event is
 137      * being delivered, was registered.
 138      *
 139      * <p>
 140      * If listener used a wildcarded path (if supported by path type) during
 141      * registration for change listeners this method returns null, and state
 142      * can be accessed only via {@link #getCreatedData()},
 143      * {@link #getUpdatedData()}, {@link #getRemovedPaths()}
 144      *
 145      * @return Stable view of data after the change happened, rooted at the
 146      *         listener registration path.
 147      */
 148     D getUpdatedSubtree();
 149 }