data/yang-data-tree-ri/src/main/java/org/opendaylight/yangtools/yang/data/tree/impl/ModificationApplyOperation.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.impl;
   9
  10 import com.google.common.base.MoreObjects;
  11 import com.google.common.base.MoreObjects.ToStringHelper;
  12 import java.util.Optional;
  13 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
  14 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  15 import org.opendaylight.yangtools.yang.data.api.schema.tree.StoreTreeNode;
  16 import org.opendaylight.yangtools.yang.data.tree.api.DataValidationFailedException;
  17 import org.opendaylight.yangtools.yang.data.tree.impl.node.TreeNode;
  18 import org.opendaylight.yangtools.yang.data.tree.impl.node.Version;
  19
  20 /**
  21  * An operation responsible for applying {@link ModifiedNode} on tree. The operation is a hierachical composite -
  22  * the operation on top level node consists of suboperations on child nodes. This allows to walk operation hierarchy and
  23  * invoke suboperations independently.
  24  *
  25  * <p>
  26  * <b>Implementation notes</b>
  27  * <ul>
  28  *   <li>Implementations MUST expose all nested suboperations which operates on child nodes expose via
  29  *       {@link #findChildByArg(PathArgument)} method.</li>
  30  *   <li>Same suboperations SHOULD be used when invoked via {@link #apply(ModifiedNode, Optional, Version)},
  31  *       if applicable.</li>
  32  *   <li>There are exactly two base implementations:
  33  *     <ul>
  34  *       <li>{@link SchemaAwareApplyOperation}, which serves as the base class for stateful mutators -- directly
  35  *           impacting the layout and transitions of the {@link TreeNode} hierarchy.
  36  *       <li>{@link AbstractValidation}, which serves as the base class for stateless checks, which work purely on top
  37  *           of the {@link TreeNode} hierarchy. These are always overlaid on top of some other
  38  *           {@link ModificationApplyOperation}, ultimately leading to a {@link SchemaAwareApplyOperation}.
  39  *     </ul>
  40  *     This allows baseline invocations from {@link OperationWithModification} to be bimorphic in the first line of
  41  *     dispatch.
  42  *   </li>
  43  * </ul>
  44  */
  45 abstract sealed class ModificationApplyOperation implements StoreTreeNode<ModificationApplyOperation>
  46         permits AbstractValidation, SchemaAwareApplyOperation {
  47     /**
  48      * Implementation of this operation must be stateless and must not change state of this object.
  49      *
  50      * @param modification
  51      *            NodeModification to be applied
  52      * @param storeMeta
  53      *            Store Metadata Node on which NodeModification should be
  54      *            applied
  55      * @param version New subtree version of parent node
  56      * @return new {@link TreeNode} if operation resulted in updating
  57      *         node, {@link Optional#absent()} if {@link ModifiedNode}
  58      *         resulted in deletion of this node.
  59      * @throws IllegalArgumentException
  60      *             If it is not possible to apply Operation on provided Metadata
  61      *             node
  62      */
  63     abstract Optional<? extends TreeNode> apply(ModifiedNode modification, Optional<? extends TreeNode> storeMeta,
  64             Version version);
  65
  66     /**
  67      * Checks if provided node modification could be applied to current metadata node.
  68      *
  69      * @param path Path to modification
  70      * @param modification Modification
  71      * @param current Metadata Node to which modification should be applied
  72      * @param version Metadata version
  73      * @throws DataValidationFailedException if the modification is not applicable
  74      */
  75     abstract void checkApplicable(ModificationPath path, NodeModification modification,
  76             Optional<? extends TreeNode> current, Version version) throws DataValidationFailedException;
  77
  78     /**
  79      * Performs a quick structural verification of NodeModification, such as written values / types uses right
  80      * structural elements.
  81      *
  82      * @param modification data to be verified.
  83      * @throws IllegalArgumentException If provided NodeModification does not adhere to the
  84      *         structure.
  85      */
  86     abstract void quickVerifyStructure(NormalizedNode modification);
  87
  88     /**
  89      * Performs a full structural verification of NodeModification, such as written values / types uses right
  90      * structural elements. Unlike {@link #quickVerifyStructure(NormalizedNode)} this includes recursively checking
  91      * children, too.
  92      *
  93      * @param modification data to be verified.
  94      * @throws IllegalArgumentException If provided NodeModification does not adhere to the
  95      *         structure.
  96      */
  97     abstract void fullVerifyStructure(NormalizedNode modification);
  98
  99     /**
 100      * Return the tracking policy for this node's children.
 101      *
 102      * @return Tracking policy, may not be null.
 103      */
 104     abstract ChildTrackingPolicy getChildPolicy();
 105
 106     /**
 107      * Stage a merge operation into a {@link ModifiedNode} such that it will be processed correctly by
 108      * {@link #apply(ModifiedNode, Optional, Version)}. This method is the context which is introducing this operation,
 109      * and so any overheads are charged to whoever is in control of the access pattern.
 110      *
 111      * @param modification Original modification node
 112      * @param value Value which should be merge into the modification
 113      * @param version Data version as carried in the containing {@link InMemoryDataTreeModification}
 114      */
 115     abstract void mergeIntoModifiedNode(ModifiedNode modification, NormalizedNode value, Version version);
 116
 117     /**
 118      * {@inheritDoc}
 119      *
 120      * @return Reference to suboperation for specified tree node, {@code null} if suboperation is not supported for
 121      *         specified tree node.
 122      */
 123     @Override
 124     public abstract ModificationApplyOperation childByArg(PathArgument arg);
 125
 126     abstract void recursivelyVerifyStructure(NormalizedNode value);
 127
 128     abstract ToStringHelper addToStringAttributes(ToStringHelper helper);
 129
 130     @Override
 131     public final String toString() {
 132         return addToStringAttributes(MoreObjects.toStringHelper(this)).toString();
 133     }
 134 }