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