Fix checkstyle violations in sal-common-api
[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 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 }

©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.