ac4a0ffc331226504b47b5f1cf45b996b0522b5c
[controller.git] / 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, 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 }

©2013 OpenDaylight, A Linux Foundation Collaborative Project. All Rights Reserved.
OpenDaylight is a registered trademark of The OpenDaylight Project, Inc.
Linux Foundation and OpenDaylight are registered trademarks of the Linux Foundation.
Linux is a registered trademark of Linus Torvalds.