Deprecate DCL in favor of DTCL
[controller.git] / opendaylight / md-sal / sal-binding-api / src / main / java / org / opendaylight / controller / md / sal / binding / api / DataObjectModification.java
1 /*
2  * Copyright (c) 2015 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
9 package org.opendaylight.controller.md.sal.binding.api;
10
11 import java.util.Collection;
12 import javax.annotation.Nonnull;
13 import javax.annotation.Nullable;
14 import org.opendaylight.yangtools.yang.binding.Augmentation;
15 import org.opendaylight.yangtools.yang.binding.ChildOf;
16 import org.opendaylight.yangtools.yang.binding.DataObject;
17 import org.opendaylight.yangtools.yang.binding.Identifiable;
18 import org.opendaylight.yangtools.yang.binding.Identifier;
19 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.PathArgument;
20
21 /**
22  * Modified Data Object.
23  *
24  * Represents modification of Data Object.
25  *
26  */
27 public interface DataObjectModification<T extends DataObject> extends org.opendaylight.yangtools.concepts.Identifiable<PathArgument> {
28
29     enum ModificationType {
30         /**
31          *
32          * Child node (direct or indirect) was modified.
33          *
34          */
35         SUBTREE_MODIFIED,
36         /**
37          *
38          * Node was explicitly created / overwritten.
39          *
40          */
41         WRITE,
42         /**
43          *
44          * Node was deleted.
45          *
46          */
47         DELETE
48     }
49
50     @Override
51     PathArgument getIdentifier();
52
53     /**
54      * Returns type of modified object.
55      *
56      * @return type of modified object.
57      */
58     @Nonnull Class<T> getDataType();
59
60     /**
61      *
62      * Returns type of modification
63      *
64      * @return type Type of performed modification.
65      */
66     @Nonnull ModificationType getModificationType();
67
68     /**
69      * Returns before-state of top level container. Implementations are encouraged,
70      * but not required to provide this state.
71      *
72      * @param root Class representing data container
73      * @return State of object before modification. Null if subtree was not present,
74      *         or the implementation cannot provide the state.
75      */
76     @Nullable T getDataBefore();
77
78     /**
79      * Returns after-state of top level container.
80      *
81      * @param root Class representing data container
82      * @return State of object after modification. Null if subtree is not present.
83      */
84     @Nullable T getDataAfter();
85
86     /**
87      * Returns unmodifiable collection of modified direct children.
88      *
89      * @return unmodifiable collection of modified direct children.
90      */
91     @Nonnull Collection<DataObjectModification<? extends DataObject>> getModifiedChildren();
92
93     /**
94      * Returns container child modification if {@code child} was modified by this
95      * modification.
96      *
97      * For accessing all modified list items consider iterating over {@link #getModifiedChildren()}.
98      *
99      * @param child Type of child - must be only container
100      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
101      * @throws IllegalArgumentException If supplied {@code child} class is not valid child according
102      *         to generated model.
103      */
104     @Nullable <C extends ChildOf<? super T>> DataObjectModification<C> getModifiedChildContainer(@Nonnull Class<C> child);
105
106     /**
107      * Returns augmentation child modification if {@code augmentation} was modified by this
108      * modification.
109      *
110      * For accessing all modified list items consider iterating over {@link #getModifiedChildren()}.
111      *
112      * @param augmentation Type of augmentation - must be only container
113      * @return Modification of {@code augmentation} if {@code augmentation} was modified, null otherwise.
114      * @throws IllegalArgumentException If supplied {@code augmentation} class is not valid augmentation
115      *         according to generated model.
116      */
117     @Nullable <C extends Augmentation<T> & DataObject> DataObjectModification<C> getModifiedAugmentation(@Nonnull Class<C> augmentation);
118
119
120     /**
121      * Returns child list item modification if {@code child} was modified by this modification.
122      *
123      * @param listItem Type of list item - must be list item with key
124      * @param listKey List item key
125      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
126      * @throws IllegalArgumentException If supplied {@code listItem} class is not valid child according
127      *         to generated model.
128      */
129     <C extends Identifiable<K> & ChildOf<? super T>, K extends Identifier<C>> DataObjectModification<C> getModifiedChildListItem(
130             @Nonnull Class<C> listItem,@Nonnull  K listKey);
131
132     /**
133      * Returns a child modification if a node identified by {@code childArgument} was modified by
134      * this modification.
135      *
136      * @param childArgument Path Argument of child node
137      * @return Modification of child identified by {@code childArgument} if {@code childArgument}
138      *         was modified, null otherwise.
139      * @throws IllegalArgumentException If supplied path argument is not valid child according to
140      *         generated model.
141      *
142      */
143     @Nullable DataObjectModification<? extends DataObject> getModifiedChild(PathArgument childArgument);
144
145 }