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