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