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 }