binding/mdsal-binding-api/src/main/java/org/opendaylight/mdsal/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 package org.opendaylight.mdsal.binding.api;
   9
  10 import java.util.Collection;
  11 import org.eclipse.jdt.annotation.NonNull;
  12 import org.eclipse.jdt.annotation.Nullable;
  13 import org.opendaylight.yangtools.yang.binding.Augmentation;
  14 import org.opendaylight.yangtools.yang.binding.ChildOf;
  15 import org.opendaylight.yangtools.yang.binding.ChoiceIn;
  16 import org.opendaylight.yangtools.yang.binding.DataObject;
  17 import org.opendaylight.yangtools.yang.binding.ExactDataObjectStep;
  18 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  19 import org.opendaylight.yangtools.yang.binding.Key;
  20 import org.opendaylight.yangtools.yang.binding.KeyAware;
  21
  22 /**
  23  * Modified Data Object. Represents a modification of DataObject, which has a few kinds as indicated by
  24  * {@link #getModificationType()}.
  25  *
  26  * @param <T> Type of modified object
  27  */
  28 public interface DataObjectModification<T extends DataObject> {
  29     /**
  30      * Represents type of modification which has occurred.
  31      */
  32     enum ModificationType {
  33         /**
  34          * Child node (direct or indirect) was modified.
  35          */
  36         SUBTREE_MODIFIED,
  37         /**
  38          * Node was explicitly created / overwritten.
  39          */
  40         WRITE,
  41         /**
  42          * Node was deleted.
  43          */
  44         DELETE
  45     }
  46
  47     @Deprecated(since = "13.0.0", forRemoval = true)
  48     default @NonNull ExactDataObjectStep<T> getIdentifier() {
  49         return step();
  50     }
  51
  52     /**
  53      * Return the {@link InstanceIdentifier} step this modification corresponds to.
  54      *
  55      * @return the {@link InstanceIdentifier} step this modification corresponds to
  56      */
  57     @NonNull ExactDataObjectStep<T> step();
  58
  59     /**
  60      * Returns type of modified object.
  61      *
  62      * @return type of modified object.
  63      */
  64     default @NonNull Class<T> dataType() {
  65         return step().type();
  66     }
  67
  68     /**
  69      * Returns type of modified object.
  70      *
  71      * @return type of modified object.
  72      * @deprecated Use {@link #dataType()} instead.
  73      */
  74     @Deprecated(since = "13.0.0", forRemoval = true)
  75     default @NonNull Class<T> getDataType() {
  76         return dataType();
  77     }
  78
  79     /**
  80      * Returns type of modification.
  81      *
  82      * @return type of performed modification.
  83      */
  84     @NonNull ModificationType modificationType();
  85
  86     /**
  87      * Returns type of modification.
  88      *
  89      * @return type Type of performed modification.
  90      */
  91     @Deprecated(since = "13.0.0", forRemoval = true)
  92     default @NonNull ModificationType getModificationType() {
  93         return modificationType();
  94     }
  95
  96     /**
  97      * Returns before-state of top level container. Implementations are encouraged, but not required to provide this
  98      *  state.
  99      *
 100      * @return State of object before modification. Null if subtree was not present, or the implementation cannot
 101      *         provide the state.
 102      */
 103     @Nullable T dataBefore();
 104
 105     /**
 106      * Returns before-state of top level container. Implementations are encouraged, but not required to provide this
 107      *  state.
 108      *
 109      * @return State of object before modification. Null if subtree was not present, or the implementation cannot
 110      *         provide the state.
 111      * @deprecated Use {@link #dataBefore()} instead.
 112      */
 113     @Deprecated(since = "13.0.0", forRemoval = true)
 114     default @Nullable T getDataBefore() {
 115         return dataBefore();
 116     }
 117
 118     /**
 119      * Returns after-state of top level container.
 120      *
 121      * @return State of object after modification. Null if subtree is not present.
 122      */
 123     @Nullable T dataAfter();
 124
 125     /**
 126      * Returns after-state of top level container.
 127      *
 128      * @return State of object after modification. Null if subtree is not present.
 129      * @deprecated Use {@link #dataAfter()} instead.
 130      */
 131     @Deprecated(since = "13.0.0", forRemoval = true)
 132     default @Nullable T getDataAfter() {
 133         return dataAfter();
 134     }
 135
 136     /**
 137      * Returns unmodifiable collection of modified direct children.
 138      *
 139      * @return unmodifiable collection of modified direct children.
 140      */
 141     @NonNull Collection<? extends DataObjectModification<? extends DataObject>> modifiedChildren();
 142
 143     /**
 144      * Returns unmodifiable collection of modified direct children.
 145      *
 146      * @return unmodifiable collection of modified direct children.
 147      * @deprecated Use {@link #modifiedChildren()} instead.
 148      */
 149     @Deprecated(since = "13.0.0", forRemoval = true)
 150     default @NonNull Collection<? extends DataObjectModification<? extends DataObject>> getModifiedChildren() {
 151         return modifiedChildren();
 152     }
 153
 154     /**
 155      * Returns child list item modification if {@code child} was modified by this modification.
 156      *
 157      * @param childType Type of list item - must be list item with key
 158      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
 159      * @throws IllegalArgumentException If supplied {@code childType} class is not valid child according
 160      *         to generated model.
 161      */
 162     <C extends ChildOf<? super T>> Collection<DataObjectModification<C>> getModifiedChildren(
 163             @NonNull Class<C> childType);
 164
 165     /**
 166      * Returns child list item modification if {@code child} was modified by this modification. This method should be
 167      * used if the child is defined in a grouping brought into a case inside this object.
 168      *
 169      * @param caseType Case type class
 170      * @param childType Type of list item - must be list item with key
 171      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
 172      * @throws IllegalArgumentException If supplied {@code childType} class is not valid child according
 173      *         to generated model.
 174      */
 175     <H extends ChoiceIn<? super T> & DataObject, C extends ChildOf<? super H>> Collection<DataObjectModification<C>>
 176             getModifiedChildren(@NonNull Class<H> caseType, @NonNull Class<C> childType);
 177
 178     /**
 179      * Returns container child modification if {@code child} was modified by this modification. This method should be
 180      * used if the child is defined in a grouping brought into a case inside this object.
 181      *
 182      * <p>
 183      * For accessing all modified list items consider iterating over {@link #getModifiedChildren()}.
 184      *
 185      * @param caseType Case type class
 186      * @param child Type of child - must be only container
 187      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
 188      * @throws IllegalArgumentException If supplied {@code child} class is not valid child according
 189      *         to generated model.
 190      */
 191     <H extends ChoiceIn<? super T> & DataObject, C extends ChildOf<? super H>> @Nullable DataObjectModification<C>
 192             getModifiedChildContainer(@NonNull Class<H> caseType, @NonNull Class<C> child);
 193
 194     /**
 195      * Returns container child modification if {@code child} was modified by this
 196      * modification.
 197      *
 198      * <p>
 199      * For accessing all modified list items consider iterating over {@link #getModifiedChildren()}.
 200      *
 201      * @param child Type of child - must be only container
 202      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
 203      * @throws IllegalArgumentException If supplied {@code child} class is not valid child according
 204      *         to generated model.
 205      */
 206     <C extends ChildOf<? super T>> @Nullable DataObjectModification<C> getModifiedChildContainer(
 207             @NonNull Class<C> child);
 208
 209     /**
 210      * Returns augmentation child modification if {@code augmentation} was modified by this modification.
 211      *
 212      * <p>
 213      * For accessing all modified list items consider iterating over {@link #getModifiedChildren()}.
 214      *
 215      * @param augmentation Type of augmentation - must be only container
 216      * @return Modification of {@code augmentation} if {@code augmentation} was modified, null otherwise.
 217      * @throws IllegalArgumentException If supplied {@code augmentation} class is not valid augmentation
 218      *         according to generated model.
 219      */
 220     <C extends Augmentation<T> & DataObject> @Nullable DataObjectModification<C> getModifiedAugmentation(
 221             @NonNull Class<C> augmentation);
 222
 223     /**
 224      * Returns child list item modification if {@code child} was modified by this modification.
 225      *
 226      * @param listItem Type of list item - must be list item with key
 227      * @param listKey List item key
 228      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
 229      * @throws IllegalArgumentException If supplied {@code listItem} class is not valid child according
 230      *         to generated model.
 231      */
 232     <N extends KeyAware<K> & ChildOf<? super T>, K extends Key<N>> @Nullable DataObjectModification<N>
 233             getModifiedChildListItem(@NonNull Class<N> listItem, @NonNull K listKey);
 234
 235     /**
 236      * Returns child list item modification if {@code child} was modified by this modification.
 237      *
 238      * @param listItem Type of list item - must be list item with key
 239      * @param listKey List item key
 240      * @return Modification of {@code child} if {@code child} was modified, null otherwise.
 241      * @throws IllegalArgumentException If supplied {@code listItem} class is not valid child according
 242      *         to generated model.
 243      */
 244     <H extends ChoiceIn<? super T> & DataObject, C extends KeyAware<K> & ChildOf<? super H>,
 245             K extends Key<C>> @Nullable DataObjectModification<C> getModifiedChildListItem(
 246                     @NonNull Class<H> caseType, @NonNull Class<C> listItem, @NonNull K listKey);
 247
 248     /**
 249      * Returns a child modification if a node identified by {@code childArgument} was modified by this modification.
 250      *
 251      * @param childArgument {@link ExactDataObjectStep} of child node
 252      * @return Modification of child identified by {@code childArgument} if {@code childArgument} was modified,
 253      *         {@code null} otherwise
 254      * @throws IllegalArgumentException If supplied step is not valid child according to generated model
 255      */
 256     @Nullable DataObjectModification<? extends DataObject> getModifiedChild(ExactDataObjectStep<?> childArgument);
 257 }