binding/mdsal-binding-dom-codec-api/src/main/java/org/opendaylight/mdsal/binding/dom/codec/api/BindingNormalizedNodeSerializer.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.mdsal.binding.dom.codec.api;
   9
  10 import static java.util.Objects.requireNonNull;
  11
  12 import com.google.common.annotations.Beta;
  13 import com.google.common.collect.ImmutableList;
  14 import com.google.common.collect.ImmutableSet;
  15 import java.time.Instant;
  16 import java.util.Map.Entry;
  17 import org.eclipse.jdt.annotation.NonNull;
  18 import org.eclipse.jdt.annotation.Nullable;
  19 import org.opendaylight.mdsal.binding.spec.reflect.BindingReflections;
  20 import org.opendaylight.yangtools.yang.binding.Action;
  21 import org.opendaylight.yangtools.yang.binding.Augmentation;
  22 import org.opendaylight.yangtools.yang.binding.BaseNotification;
  23 import org.opendaylight.yangtools.yang.binding.DataContainer;
  24 import org.opendaylight.yangtools.yang.binding.DataObject;
  25 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  26 import org.opendaylight.yangtools.yang.binding.Notification;
  27 import org.opendaylight.yangtools.yang.binding.RpcInput;
  28 import org.opendaylight.yangtools.yang.binding.RpcOutput;
  29 import org.opendaylight.yangtools.yang.common.YangConstants;
  30 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  31 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier;
  32 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
  33 import org.opendaylight.yangtools.yang.data.api.schema.ContainerNode;
  34 import org.opendaylight.yangtools.yang.data.api.schema.DataContainerChild;
  35 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  36 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Absolute;
  37
  38 /**
  39  * Serialization service, which provides two-way serialization between Java Binding Data representation and
  40  * NormalizedNode representation.
  41  */
  42 public interface BindingNormalizedNodeSerializer {
  43     /**
  44      * Result of a {@link BindingNormalizedNodeSerializer#toNormalizedNode(InstanceIdentifier, DataObject)}. Since the
  45      * Binding {@link Augmentation} does not have an exact equivalent, there are two specializations of this class:
  46      * {@link NodeResult} and {@link AugmentationResult}.
  47      */
  48     sealed interface NormalizedResult {
  49         /**
  50          * Return the {@link YangInstanceIdentifier} path of this result.
  51          *
  52          * @return A {@link YangInstanceIdentifier}
  53          */
  54         @NonNull YangInstanceIdentifier path();
  55     }
  56
  57     /**
  58      * A {@link NormalizedResult} for an {@link Augmentation}.
  59      *
  60      * @param path A YangInstanceIdentifier identifying the parent of this augmentation
  61      * @param possibleChildren {@link PathArgument}s of each possible child
  62      * @param children Augmentation children
  63      */
  64     record AugmentationResult(
  65             @NonNull YangInstanceIdentifier path,
  66             @NonNull ImmutableSet<PathArgument> possibleChildren,
  67             @NonNull ImmutableList<DataContainerChild> children) implements NormalizedResult {
  68         public AugmentationResult {
  69             requireNonNull(path);
  70             requireNonNull(possibleChildren);
  71             requireNonNull(children);
  72         }
  73     }
  74
  75     record NodeResult(@NonNull YangInstanceIdentifier path, @NonNull NormalizedNode node) implements NormalizedResult {
  76         public NodeResult {
  77             requireNonNull(path);
  78             requireNonNull(node);
  79         }
  80     }
  81
  82     /**
  83      * Translates supplied Binding Instance Identifier into NormalizedNode instance identifier.
  84      *
  85      * @param binding Binding Instance Identifier
  86      * @return DOM Instance Identifier
  87      * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
  88      */
  89     // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
  90     @NonNull YangInstanceIdentifier toYangInstanceIdentifier(@NonNull InstanceIdentifier<?> binding);
  91
  92     /**
  93      * Translates supplied YANG Instance Identifier into Binding instance identifier.
  94      *
  95      * @param dom YANG Instance Identifier
  96      * @return Binding Instance Identifier, or null if the instance identifier is not representable.
  97      */
  98     // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
  99     <T extends DataObject> @Nullable InstanceIdentifier<T> fromYangInstanceIdentifier(
 100             @NonNull YangInstanceIdentifier dom);
 101
 102     /**
 103      * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
 104      *
 105      * @param path Binding Instance Identifier pointing to data
 106      * @param data Data object representing data
 107      * @return {@link NormalizedResult} representation
 108      * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
 109      */
 110     <T extends DataObject> @NonNull NormalizedResult toNormalizedNode(InstanceIdentifier<T> path, T data);
 111
 112     /**
 113      * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
 114      *
 115      * @param path Binding Instance Identifier pointing to data
 116      * @param data Data object representing data
 117      * @return {@link NormalizedResult} representation
 118      * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
 119      */
 120     <A extends Augmentation<?>> @NonNull AugmentationResult toNormalizedAugmentation(InstanceIdentifier<A> path,
 121         A data);
 122
 123     /**
 124      * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
 125      *
 126      * @param path Binding Instance Identifier pointing to data
 127      * @param data Data object representing data
 128      * @return {@link NormalizedResult} representation
 129      * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
 130      */
 131     <T extends DataObject> @NonNull NodeResult toNormalizedDataObject(InstanceIdentifier<T> path, T data);
 132
 133     /**
 134      * Translates supplied YANG Instance Identifier and NormalizedNode into Binding data.
 135      *
 136      * @param path Binding Instance Identifier
 137      * @param data NormalizedNode representing data
 138      * @return DOM Instance Identifier
 139      */
 140     @Nullable Entry<InstanceIdentifier<?>, DataObject> fromNormalizedNode(@NonNull YangInstanceIdentifier path,
 141             NormalizedNode data);
 142
 143     /**
 144      * Translates supplied NormalizedNode Notification into Binding data.
 145      *
 146      * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
 147      * @param data NormalizedNode representing data
 148      * @return Binding representation of Notification
 149      */
 150     @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data);
 151
 152     /**
 153      * Translates supplied NormalizedNode Notification into Binding data, optionally taking an instant
 154      * when the notification was generated.
 155      *
 156      * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
 157      * @param data NormalizedNode representing data
 158      * @param eventInstant optional instant when the event was generated
 159      * @return Binding representation of Notification
 160      */
 161     @Beta
 162     @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data,
 163             @Nullable Instant eventInstant);
 164
 165     /**
 166      * Translates supplied NormalizedNode RPC input or output into Binding data.
 167      *
 168      * @param containerPath Container path (RPC type + input/output)
 169      * @param data NormalizedNode representing data
 170      * @return Binding representation of RPC data
 171      */
 172     @Nullable DataObject fromNormalizedNodeRpcData(@NonNull Absolute containerPath, @NonNull ContainerNode data);
 173
 174     /**
 175      * Translates supplied ContainerNode action input.
 176      *
 177      * @param action Binding action class
 178      * @param input ContainerNode representing data
 179      * @return Binding representation of action input
 180      * @throws NullPointerException if any of the arguments is null
 181      */
 182     @Beta
 183     <T extends RpcInput> @NonNull T fromNormalizedNodeActionInput(
 184             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode input);
 185
 186     /**
 187      * Translates supplied ContainerNode action output.
 188      *
 189      * @param action Binding action class
 190      * @param output ContainerNode representing data
 191      * @return Binding representation of action output
 192      * @throws NullPointerException if any of the arguments is null
 193      */
 194     @Beta
 195     <T extends RpcOutput> @NonNull T fromNormalizedNodeActionOutput(
 196             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode output);
 197
 198     /**
 199      * Translates supplied Binding Notification or output into NormalizedNode notification.
 200      *
 201      * @param data {@link Notification} representing notification data
 202      * @return NormalizedNode representation of notification
 203      */
 204     @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Notification<?> data);
 205
 206     /**
 207      * Translates supplied Binding Notification or output into NormalizedNode notification.
 208      *
 209      * @param path schema node identifier of the notification
 210      * @param data {@link BaseNotification} representing notification data
 211      * @return NormalizedNode representation of notification
 212      */
 213     @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Absolute path, @NonNull BaseNotification data);
 214
 215     /**
 216      * Translates supplied Binding RPC input or output into NormalizedNode data.
 217      *
 218      * @param data NormalizedNode representing rpc data
 219      * @return NormalizedNode representation of rpc data
 220      */
 221     @NonNull ContainerNode toNormalizedNodeRpcData(@NonNull DataContainer data);
 222
 223     /**
 224      * Lazily translates supplied Binding action input into NormalizedNode data.
 225      *
 226      * @param action Binding action class
 227      * @param input Binding action input
 228      * @return NormalizedNode representation of action input
 229      * @throws NullPointerException if any of the arguments is null
 230      */
 231     @Beta
 232     @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
 233             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
 234                     @NonNull RpcInput input);
 235
 236     /**
 237      * Lazily translates supplied Binding action input into NormalizedNode data.
 238      *
 239      * @param action Binding action class
 240      * @param input Binding action input
 241      * @return NormalizedNode representation of action input
 242      * @throws NullPointerException if any of the arguments is null
 243      */
 244     @Beta default @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
 245             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
 246         return toLazyNormalizedNodeActionInput(action,
 247             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input);
 248     }
 249
 250     /**
 251      * Translates supplied Binding action input into NormalizedNode data.
 252      *
 253      * @param action Binding action class
 254      * @param input Binding action input
 255      * @return NormalizedNode representation of action input
 256      * @throws NullPointerException if any of the arguments is null
 257      */
 258     @Beta default @NonNull ContainerNode toNormalizedNodeActionInput(
 259             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
 260         return toLazyNormalizedNodeActionInput(action,
 261             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input)
 262                 .getDelegate();
 263     }
 264
 265     /**
 266      * Lazily translates supplied Binding action output into NormalizedNode data.
 267      *
 268      * @param action Binding action class
 269      * @param output Binding action output
 270      * @return NormalizedNode representation of action output
 271      */
 272     @Beta
 273     @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
 274             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
 275                     @NonNull RpcOutput output);
 276
 277     /**
 278      * Lazily translates supplied Binding action output into NormalizedNode data.
 279      *
 280      * @param action Binding action class
 281      * @param output Binding action output
 282      * @return NormalizedNode representation of action output
 283      */
 284     @Beta default @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
 285             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcOutput output) {
 286         return toLazyNormalizedNodeActionOutput(action,
 287             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), output);
 288     }
 289
 290     /**
 291      * Translates supplied Binding action output into NormalizedNode data.
 292      *
 293      * @param output Binding action output
 294      * @return NormalizedNode representation of action output
 295      */
 296     @Beta default @NonNull ContainerNode toNormalizedNodeActionOutput(
 297             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcOutput output) {
 298         return toLazyNormalizedNodeActionOutput(action,
 299             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), output)
 300                 .getDelegate();
 301     }
 302 }