Allow DataObjectModification to address grouping nodes
[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 com.google.common.collect.Collections2;
12 import java.util.Collection;
13 import javax.annotation.Nonnull;
14 import javax.annotation.Nullable;
15 import org.opendaylight.yangtools.yang.binding.Augmentation;
16 import org.opendaylight.yangtools.yang.binding.ChildOf;
17 import org.opendaylight.yangtools.yang.binding.ChoiceIn;
18 import org.opendaylight.yangtools.yang.binding.DataObject;
19 import org.opendaylight.yangtools.yang.binding.Identifiable;
20 import org.opendaylight.yangtools.yang.binding.Identifier;
21 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.IdentifiableItem;
22 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.Item;
23 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier.PathArgument;
24
25 /**
26  * Represents a modification of DataObject.
27  */
28 public interface DataObjectModification<T extends DataObject>
29         extends org.opendaylight.yangtools.concepts.Identifiable<PathArgument> {
30
31     enum ModificationType {
32         /**
33          * Child node (direct or indirect) was modified.
34          *
35          */
36         SUBTREE_MODIFIED,
37
38         /**
39          * Node was explicitly created / overwritten.
40          *
41          */
42
43         WRITE,
44         /**
45          * Node was deleted.
46          *
47          */
48         DELETE
49     }
50
51     @Override
52     PathArgument getIdentifier();
53
54     /**
55      * Returns type of modified object.
56      *
57      * @return type of modified object.
58      */
59     @Nonnull Class<T> getDataType();
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      * @return State of object before modification. Null if subtree was not present,
73      *         or the implementation cannot provide the state.
74      */
75     @Nullable T getDataBefore();
76
77     /**
78      * Returns after-state of top level container.
79      *
80      * @return State of object after modification. Null if subtree is not present.
81      */
82     @Nullable T getDataAfter();
83
84     /**
85      * Returns unmodifiable collection of modified direct children.
86      *
87      * @return unmodifiable collection of modified direct children.
88      */
89     @Nonnull Collection<? extends DataObjectModification<? extends DataObject>> getModifiedChildren();
90
91     /**
92      * Returns child list item modification if {@code child} was modified by this modification. This method should be
93      * used if the child is defined in a grouping brought into a case inside this object.
94      *
95      * @param caseType Case type class
96      * @param childType Type of list item - must be list item with key
97      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
98      * @throws IllegalArgumentException If supplied {@code childType} class is not valid child according
99      *         to generated model.
100      */
101     default <H extends ChoiceIn<? super T> & DataObject, C extends ChildOf<? super H>>
102         Collection<DataObjectModification<C>> getModifiedChildren(@Nonnull final Class<H> caseType,
103                 @Nonnull final Class<C> childType) {
104         final Item<C> item = Item.of(caseType, childType);
105         return (Collection<DataObjectModification<C>>) Collections2.filter(getModifiedChildren(),
106             mod -> item.equals(mod.getIdentifier()));
107     }
108
109     /**
110      * Returns container child modification if {@code child} was modified by this modification. This method should be
111      * used if the child is defined in a grouping brought into a case inside this object.
112      *
113      * <p>
114      * For accessing all modified list items consider iterating over {@link #getModifiedChildren()}.
115      *
116      * @param caseType Case type class
117      * @param child Type of child - must be only container
118      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
119      * @throws IllegalArgumentException If supplied {@code child} class is not valid child according
120      *         to generated model.
121      */
122     default @Nullable <H extends ChoiceIn<? super T> & DataObject, C extends ChildOf<? super H>>
123             DataObjectModification<C> getModifiedChildContainer(@Nonnull final Class<H> caseType,
124                     @Nonnull final Class<C> child) {
125         return (DataObjectModification<C>) getModifiedChild(Item.of(caseType, child));
126     }
127
128     /**
129      * Returns container child modification if {@code child} was modified by this modification.
130      *
131      * <p>
132      * For accessing all modified list items consider iterating over {@link #getModifiedChildren()}.
133      *
134      * @param child Type of child - must be only container
135      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
136      * @throws IllegalArgumentException If supplied {@code child} class is not valid child according
137      *         to generated model.
138      */
139     @Nullable <C extends ChildOf<? super T>> DataObjectModification<C> getModifiedChildContainer(
140             @Nonnull Class<C> child);
141
142     /**
143      * Returns augmentation child modification if {@code augmentation} was modified by this modification.
144      *
145      * <p>
146      * For accessing all modified list items consider iterating over {@link #getModifiedChildren()}.
147      *
148      * @param augmentation Type of augmentation - must be only container
149      * @return Modification of {@code augmentation} if {@code augmentation} was modified, null otherwise.
150      * @throws IllegalArgumentException If supplied {@code augmentation} class is not valid augmentation
151      *         according to generated model.
152      */
153     @Nullable <C extends Augmentation<T> & DataObject> DataObjectModification<C> getModifiedAugmentation(
154             @Nonnull Class<C> augmentation);
155
156     /**
157      * Returns child list item modification if {@code child} was modified by this modification.
158      *
159      * @param listItem Type of list item - must be list item with key
160      * @param listKey List item key
161      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
162      * @throws IllegalArgumentException If supplied {@code listItem} class is not valid child according
163      *         to generated model.
164      */
165     <N extends Identifiable<K> & ChildOf<? super T>, K extends Identifier<N>> DataObjectModification<N>
166             getModifiedChildListItem(@Nonnull Class<N> listItem, @Nonnull K listKey);
167
168     /**
169      * Returns child list item modification if {@code child} was modified by this modification.
170      *
171      * @param caseType Case type class
172      * @param listItem Type of list item - must be list item with key
173      * @param listKey List item key
174      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
175      * @throws IllegalArgumentException If supplied {@code listItem} class is not valid child according
176      *         to generated model.
177      */
178     default <H extends ChoiceIn<? super T> & DataObject, C extends Identifiable<K> & ChildOf<? super H>,
179             K extends Identifier<C>> DataObjectModification<C> getModifiedChildListItem(
180                     @Nonnull final Class<H> caseType, @Nonnull final Class<C> listItem, @Nonnull final K listKey) {
181         return (DataObjectModification<C>) getModifiedChild(IdentifiableItem.of(caseType, listItem, listKey));
182     }
183
184     /**
185      * Returns a child modification if a node identified by {@code childArgument} was modified by
186      * this modification.
187      *
188      * @param childArgument Path Argument of child node
189      * @return Modification of child identified by {@code childArgument} if {@code childArgument}
190      *         was modified, null otherwise.
191      * @throws IllegalArgumentException If supplied path argument is not valid child according to
192      *         generated model.
193      *
194      */
195     @Nullable DataObjectModification<? extends DataObject> getModifiedChild(PathArgument childArgument);
196 }

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