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