data/yang-data-tree-api/src/main/java/org/opendaylight/yangtools/yang/data/tree/api/DataTreeCandidateNode.java

   1 /*
   2  * Copyright (c) 2014 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.yangtools.yang.data.tree.api;
   9
  10 import static com.google.common.base.Verify.verifyNotNull;
  11
  12 import com.google.common.base.VerifyException;
  13 import java.util.Collection;
  14 import java.util.Optional;
  15 import org.eclipse.jdt.annotation.NonNull;
  16 import org.eclipse.jdt.annotation.Nullable;
  17 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
  18 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  19
  20 /**
  21  * A single node within a {@link DataTreeCandidate}. The nodes are organized in tree hierarchy, reflecting
  22  * the modification from which this candidate was created. The node itself exposes the before- and after-image
  23  * of the tree restricted to the modified nodes.
  24  */
  25 public interface DataTreeCandidateNode {
  26     /**
  27      * Get the node underlying {@link NormalizedNode#name()}.
  28      *
  29      * @return The node identifier.
  30      */
  31     @NonNull PathArgument name();
  32
  33     /**
  34      * Get an unmodifiable collection of modified child nodes. Note that the collection may include
  35      * {@link ModificationType#UNMODIFIED} nodes, which the caller is expected to handle as if they were not present.
  36      *
  37      * @return Unmodifiable collection of modified child nodes.
  38      */
  39     @NonNull Collection<DataTreeCandidateNode> childNodes();
  40
  41     /**
  42      * Returns modified child or empty. Note that this method may return an {@link ModificationType#UNMODIFIED} node
  43      * when there is evidence of the node or its parent being involved in modification which has turned out not to
  44      * modify the node's contents.
  45      *
  46      * @param childName Identifier of child node
  47      * @return Modified child or {@code null} if the specified child has not been modified
  48      * @throws NullPointerException if {@code childNamez} is {@code null}
  49      */
  50     @Nullable DataTreeCandidateNode modifiedChild(PathArgument childName);
  51
  52     /**
  53      * Returns modified child or empty. Note that this method may return an {@link ModificationType#UNMODIFIED} node
  54      * when there is evidence of the node or its parent being involved in modification which has turned out not to
  55      * modify the node's contents.
  56      *
  57      * @implSpec Default implementation defers to {@link Optional#ofNullable(Object)} based on
  58      *           {@link #modifiedChild(PathArgument)}.
  59      * @param childName Identifier of child node
  60      * @return Modified child or empty.
  61      * @throws NullPointerException if {@code childIdentifier} is {@code null}
  62      */
  63     default @NonNull Optional<DataTreeCandidateNode> findModifiedChild(final PathArgument childName) {
  64         return Optional.ofNullable(modifiedChild(childName));
  65     }
  66
  67     /**
  68      * Returns modified child or empty. Note that this method may return an {@link ModificationType#UNMODIFIED} node
  69      * when there is evidence of the node or its parent being involved in modification which has turned out not to
  70      * modify the node's contents.
  71      *
  72      * @implSpec Default implementation defers to {@link #modifiedChild(PathArgument)}.
  73      * @param childName Identifier of child node
  74      * @return Modified child
  75      * @throws NullPointerException if {@code childName} is {@code null}
  76      * @throws VerifyException if no modified child with specified name is found
  77      */
  78     default @NonNull DataTreeCandidateNode getModifiedChild(final PathArgument childName) {
  79         return verifyNotNull(modifiedChild(childName), "No modified child named %s", childName);
  80     }
  81
  82     /**
  83      * Return the type of modification this node is undergoing.
  84      *
  85      * @return Node modification type.
  86      */
  87     @NonNull ModificationType modificationType();
  88
  89     /**
  90      * Return the before-image of data corresponding to the node.
  91      *
  92      * @return Node data as they were present in the tree before the modification was applied.
  93      */
  94     @Nullable NormalizedNode dataBefore();
  95
  96     /**
  97      * Return the before-image of data corresponding to the node.
  98      *
  99      * @implSpec Default implementation defers to {@link Optional#ofNullable(Object)} based on {@link #dataBefore()}.
 100      * @return Node data as they were present in the tree before the modification was applied, or empty.
 101      */
 102     default @NonNull Optional<NormalizedNode> findDataBefore() {
 103         return Optional.ofNullable(dataBefore());
 104     }
 105
 106     /**
 107      * Return the before-image of data corresponding to the node.
 108      *
 109      * @implSpec Default implementation defers to {@link #dataBefore()}.
 110      * @return Node data as they were present in the tree before the modification was applied.
 111      * @throws VerifyException if no before-image is present
 112      */
 113     default @NonNull NormalizedNode getDataBefore() {
 114         return verifyNotNull(dataBefore(), "No before-image available");
 115     }
 116
 117     /**
 118      * Return the after-image of data corresponding to the node.
 119      *
 120      * @return Node data as they will be present in the tree after the modification is applied
 121      */
 122     @Nullable NormalizedNode dataAfter();
 123
 124     /**
 125      * Return the after-image of data corresponding to the node.
 126      *
 127      * @implSpec Default implementation defers to {@link Optional#ofNullable(Object)} based on {@link #dataAfter()}.
 128      * @return Node data as they will be present in the tree after the modification is applied, or empty
 129      */
 130     default @NonNull Optional<NormalizedNode> findDataAfter() {
 131         return Optional.ofNullable(dataAfter());
 132     }
 133
 134     /**
 135      * Return the after-image of data corresponding to the node.
 136      *
 137      * @implSpec Default implementation defers to {@link #dataAfter()}.
 138      * @return Node data as they will be present in the tree after the modification is applied.
 139      * @throws VerifyException if no after-image is present
 140      */
 141     default @NonNull NormalizedNode getDataAfter() {
 142         return verifyNotNull(dataAfter(), "No after-image available");
 143     }
 144 }