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