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 com.google.common.annotations.Beta;
  11 import java.time.Instant;
  12 import java.util.Map.Entry;
  13 import org.eclipse.jdt.annotation.NonNull;
  14 import org.eclipse.jdt.annotation.Nullable;
  15 import org.opendaylight.mdsal.binding.spec.reflect.BindingReflections;
  16 import org.opendaylight.yangtools.yang.binding.Action;
  17 import org.opendaylight.yangtools.yang.binding.BaseNotification;
  18 import org.opendaylight.yangtools.yang.binding.DataContainer;
  19 import org.opendaylight.yangtools.yang.binding.DataObject;
  20 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
  21 import org.opendaylight.yangtools.yang.binding.Notification;
  22 import org.opendaylight.yangtools.yang.binding.RpcInput;
  23 import org.opendaylight.yangtools.yang.binding.RpcOutput;
  24 import org.opendaylight.yangtools.yang.common.YangConstants;
  25 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  26 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier;
  27 import org.opendaylight.yangtools.yang.data.api.schema.ContainerNode;
  28 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
  29 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Absolute;
  30
  31 /**
  32  * Serialization service, which provides two-way serialization between Java
  33  * Binding Data representation and NormalizedNode representation.
  34  */
  35 public interface BindingNormalizedNodeSerializer {
  36     /**
  37      * Translates supplied Binding Instance Identifier into NormalizedNode instance identifier.
  38      *
  39      * @param binding Binding Instance Identifier
  40      * @return DOM Instance Identifier
  41      * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
  42      */
  43     // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
  44     @NonNull YangInstanceIdentifier toYangInstanceIdentifier(@NonNull InstanceIdentifier<?> binding);
  45
  46     /**
  47      * Translates supplied YANG Instance Identifier into Binding instance identifier.
  48      *
  49      * @param dom YANG Instance Identifier
  50      * @return Binding Instance Identifier, or null if the instance identifier is not representable.
  51      */
  52     // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
  53     <T extends DataObject> @Nullable InstanceIdentifier<T> fromYangInstanceIdentifier(
  54             @NonNull YangInstanceIdentifier dom);
  55
  56     /**
  57      * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
  58      *
  59      * @param path Binding Instance Identifier pointing to data
  60      * @param data Data object representing data
  61      * @return NormalizedNode representation
  62      * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
  63      */
  64     <T extends DataObject> @NonNull Entry<YangInstanceIdentifier, NormalizedNode> toNormalizedNode(
  65             InstanceIdentifier<T> path, T data);
  66
  67     /**
  68      * Translates supplied YANG Instance Identifier and NormalizedNode into Binding data.
  69      *
  70      * @param path Binding Instance Identifier
  71      * @param data NormalizedNode representing data
  72      * @return DOM Instance Identifier
  73      */
  74     @Nullable Entry<InstanceIdentifier<?>, DataObject> fromNormalizedNode(@NonNull YangInstanceIdentifier path,
  75             NormalizedNode data);
  76
  77     /**
  78      * Translates supplied NormalizedNode Notification into Binding data.
  79      *
  80      * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
  81      * @param data NormalizedNode representing data
  82      * @return Binding representation of Notification
  83      */
  84     @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data);
  85
  86     /**
  87      * Translates supplied NormalizedNode Notification into Binding data, optionally taking an instant
  88      * when the notification was generated.
  89      *
  90      * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
  91      * @param data NormalizedNode representing data
  92      * @param eventInstant optional instant when the event was generated
  93      * @return Binding representation of Notification
  94      */
  95     @Beta
  96     @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data,
  97             @Nullable Instant eventInstant);
  98
  99     /**
 100      * Translates supplied NormalizedNode RPC input or output into Binding data.
 101      *
 102      * @param containerPath Container path (RPC type + input/output)
 103      * @param data NormalizedNode representing data
 104      * @return Binding representation of RPC data
 105      */
 106     @Nullable DataObject fromNormalizedNodeRpcData(@NonNull Absolute containerPath, @NonNull ContainerNode data);
 107
 108     /**
 109      * Translates supplied ContainerNode action input.
 110      *
 111      * @param action Binding action class
 112      * @param input ContainerNode representing data
 113      * @return Binding representation of action input
 114      * @throws NullPointerException if any of the arguments is null
 115      */
 116     @Beta
 117     <T extends RpcInput> @NonNull T fromNormalizedNodeActionInput(
 118             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode input);
 119
 120     /**
 121      * Translates supplied ContainerNode action output.
 122      *
 123      * @param action Binding action class
 124      * @param output ContainerNode representing data
 125      * @return Binding representation of action output
 126      * @throws NullPointerException if any of the arguments is null
 127      */
 128     @Beta
 129     <T extends RpcOutput> @NonNull T fromNormalizedNodeActionOutput(
 130             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode output);
 131
 132     /**
 133      * Translates supplied Binding Notification or output into NormalizedNode notification.
 134      *
 135      * @param data {@link Notification} representing notification data
 136      * @return NormalizedNode representation of notification
 137      */
 138     @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Notification<?> data);
 139
 140     /**
 141      * Translates supplied Binding Notification or output into NormalizedNode notification.
 142      *
 143      * @param path schema node identifier of the notification
 144      * @param data {@link BaseNotification} representing notification data
 145      * @return NormalizedNode representation of notification
 146      */
 147     @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Absolute path, @NonNull BaseNotification data);
 148
 149     /**
 150      * Translates supplied Binding RPC input or output into NormalizedNode data.
 151      *
 152      * @param data NormalizedNode representing rpc data
 153      * @return NormalizedNode representation of rpc data
 154      */
 155     @NonNull ContainerNode toNormalizedNodeRpcData(@NonNull DataContainer data);
 156
 157     /**
 158      * Lazily translates supplied Binding action input into NormalizedNode data.
 159      *
 160      * @param action Binding action class
 161      * @param input Binding action input
 162      * @return NormalizedNode representation of action input
 163      * @throws NullPointerException if any of the arguments is null
 164      */
 165     @Beta
 166     @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
 167             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
 168                     @NonNull RpcInput input);
 169
 170     /**
 171      * Lazily translates supplied Binding action input into NormalizedNode data.
 172      *
 173      * @param action Binding action class
 174      * @param input Binding action input
 175      * @return NormalizedNode representation of action input
 176      * @throws NullPointerException if any of the arguments is null
 177      */
 178     @Beta default @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
 179             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
 180         return toLazyNormalizedNodeActionInput(action,
 181             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input);
 182     }
 183
 184     /**
 185      * Translates supplied Binding action input into NormalizedNode data.
 186      *
 187      * @param action Binding action class
 188      * @param input Binding action input
 189      * @return NormalizedNode representation of action input
 190      * @throws NullPointerException if any of the arguments is null
 191      */
 192     @Beta default @NonNull ContainerNode toNormalizedNodeActionInput(
 193             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
 194         return toLazyNormalizedNodeActionInput(action,
 195             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input)
 196                 .getDelegate();
 197     }
 198
 199     /**
 200      * Lazily translates supplied Binding action output into NormalizedNode data.
 201      *
 202      * @param action Binding action class
 203      * @param output Binding action output
 204      * @return NormalizedNode representation of action output
 205      */
 206     @Beta
 207     @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
 208             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
 209                     @NonNull RpcOutput output);
 210
 211     /**
 212      * Lazily translates supplied Binding action output into NormalizedNode data.
 213      *
 214      * @param action Binding action class
 215      * @param output Binding action output
 216      * @return NormalizedNode representation of action output
 217      */
 218     @Beta default @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
 219             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcOutput output) {
 220         return toLazyNormalizedNodeActionOutput(action,
 221             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), output);
 222     }
 223
 224     /**
 225      * Translates supplied Binding action output into NormalizedNode data.
 226      *
 227      * @param output Binding action output
 228      * @return NormalizedNode representation of action output
 229      */
 230     @Beta default @NonNull ContainerNode toNormalizedNodeActionOutput(
 231             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcOutput output) {
 232         return toLazyNormalizedNodeActionOutput(action,
 233             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), output)
 234                 .getDelegate();
 235     }
 236 }