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