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