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.SchemaPath;
  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     YangInstanceIdentifier toYangInstanceIdentifier(@NonNull InstanceIdentifier<?> binding);
  43
  44     /**
  45      * Translates supplied YANG Instance Identifier into Binding instance identifier.
  46      *
  47      * @param dom YANG Instance Identifier
  48      * @return Binding Instance Identifier, or null if the instance identifier is not representable.
  49      */
  50     <T extends DataObject> @Nullable InstanceIdentifier<T> fromYangInstanceIdentifier(
  51             @NonNull YangInstanceIdentifier dom);
  52
  53     /**
  54      * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
  55      *
  56      * @param path Binding Instance Identifier pointing to data
  57      * @param data Data object representing data
  58      * @return NormalizedNode representation
  59      * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
  60      */
  61     <T extends DataObject> Entry<YangInstanceIdentifier, NormalizedNode<?, ?>> toNormalizedNode(
  62             InstanceIdentifier<T> path, T data);
  63
  64     /**
  65      * Translates supplied YANG Instance Identifier and NormalizedNode into Binding data.
  66      *
  67      * @param path Binding Instance Identifier
  68      * @param data NormalizedNode representing data
  69      * @return DOM Instance Identifier
  70      */
  71     @Nullable Entry<InstanceIdentifier<?>, DataObject> fromNormalizedNode(@NonNull YangInstanceIdentifier path,
  72             NormalizedNode<?, ?> data);
  73
  74     /**
  75      * Translates supplied NormalizedNode Notification into Binding data.
  76      *
  77      * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
  78      * @param data NormalizedNode representing data
  79      * @return Binding representation of Notification
  80      */
  81     @Nullable Notification fromNormalizedNodeNotification(@NonNull SchemaPath path, @NonNull ContainerNode data);
  82
  83     /**
  84      * Translates supplied NormalizedNode Notification into Binding data, optionally taking an instant
  85      * when the notification was generated.
  86      *
  87      * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
  88      * @param data NormalizedNode representing data
  89      * @param eventInstant optional instant when the event was generated
  90      * @return Binding representation of Notification
  91      */
  92     @Beta
  93     @Nullable Notification fromNormalizedNodeNotification(@NonNull SchemaPath path, @NonNull ContainerNode data,
  94             @Nullable Instant eventInstant);
  95
  96     /**
  97      * Translates supplied NormalizedNode RPC input or output into Binding data.
  98      *
  99      * @param path Schema path of RPC data, Schema path consists of rpc QName and input / output QName.
 100      * @param data NormalizedNode representing data
 101      * @return Binding representation of RPC data
 102      */
 103     @Nullable DataObject fromNormalizedNodeRpcData(@NonNull SchemaPath path, @NonNull ContainerNode data);
 104
 105     /**
 106      * Translates supplied ContainerNode action input.
 107      *
 108      * @param action Binding action class
 109      * @param input ContainerNode representing data
 110      * @return Binding representation of action input
 111      * @throws NullPointerException if any of the arguments is null
 112      */
 113     @Beta
 114     <T extends RpcInput> @NonNull T fromNormalizedNodeActionInput(
 115             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode input);
 116
 117     /**
 118      * Translates supplied ContainerNode action output.
 119      *
 120      * @param action Binding action class
 121      * @param output ContainerNode representing data
 122      * @return Binding representation of action output
 123      * @throws NullPointerException if any of the arguments is null
 124      */
 125     @Beta
 126     <T extends RpcOutput> @NonNull T fromNormalizedNodeActionOutput(
 127             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode output);
 128
 129     /**
 130      * Translates supplied Binding Notification or output into NormalizedNode notification.
 131      *
 132      * @param data NormalizedNode representing notification data
 133      * @return NormalizedNode representation of notification
 134      */
 135     @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Notification data);
 136
 137     /**
 138      * Translates supplied Binding RPC input or output into NormalizedNode data.
 139      *
 140      * @param data NormalizedNode representing rpc data
 141      * @return NormalizedNode representation of rpc data
 142      */
 143     @NonNull ContainerNode toNormalizedNodeRpcData(@NonNull DataContainer data);
 144
 145     /**
 146      * Lazily translates supplied Binding action input into NormalizedNode data.
 147      *
 148      * @param action Binding action class
 149      * @param input Binding action input
 150      * @return NormalizedNode representation of action input
 151      * @throws NullPointerException if any of the arguments is null
 152      */
 153     @Beta
 154     @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
 155             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
 156                     @NonNull RpcInput input);
 157
 158     /**
 159      * Lazily translates supplied Binding action input into NormalizedNode data.
 160      *
 161      * @param action Binding action class
 162      * @param input Binding action input
 163      * @return NormalizedNode representation of action input
 164      * @throws NullPointerException if any of the arguments is null
 165      */
 166     @Beta default @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
 167             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
 168         return toLazyNormalizedNodeActionInput(action,
 169             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input);
 170     }
 171
 172     /**
 173      * Translates supplied Binding action input into NormalizedNode data.
 174      *
 175      * @param action Binding action class
 176      * @param input Binding action input
 177      * @return NormalizedNode representation of action input
 178      * @throws NullPointerException if any of the arguments is null
 179      */
 180     @Beta default @NonNull ContainerNode toNormalizedNodeActionInput(
 181             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
 182         return toLazyNormalizedNodeActionInput(action,
 183             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input)
 184                 .getDelegate();
 185     }
 186
 187     /**
 188      * Lazily translates supplied Binding action output into NormalizedNode data.
 189      *
 190      * @param action Binding action class
 191      * @param output Binding action output
 192      * @return NormalizedNode representation of action output
 193      */
 194     @Beta
 195     @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
 196             @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
 197                     @NonNull RpcOutput output);
 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 default @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
 207             @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcOutput output) {
 208         return toLazyNormalizedNodeActionOutput(action,
 209             new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), output);
 210     }
 211
 212     /**
 213      * Translates supplied Binding action output into NormalizedNode data.
 214      *
 215      * @param output Binding action output
 216      * @return NormalizedNode representation of action output
 217      */
 218     @Beta default @NonNull ContainerNode toNormalizedNodeActionOutput(
 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                 .getDelegate();
 223     }
 224 }