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