2 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
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
8 package org.opendaylight.mdsal.binding.dom.codec.api;
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;
31 * Serialization service, which provides two-way serialization between Java
32 * Binding Data representation and NormalizedNode representation.
34 public interface BindingNormalizedNodeSerializer {
36 * Translates supplied Binding Instance Identifier into NormalizedNode instance identifier.
38 * @param binding Binding Instance Identifier
39 * @return DOM Instance Identifier
40 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
42 // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
43 @NonNull YangInstanceIdentifier toYangInstanceIdentifier(@NonNull InstanceIdentifier<?> binding);
46 * Translates supplied YANG Instance Identifier into Binding instance identifier.
48 * @param dom YANG Instance Identifier
49 * @return Binding Instance Identifier, or null if the instance identifier is not representable.
51 // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
52 <T extends DataObject> @Nullable InstanceIdentifier<T> fromYangInstanceIdentifier(
53 @NonNull YangInstanceIdentifier dom);
56 * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
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.
63 <T extends DataObject> @NonNull Entry<YangInstanceIdentifier, NormalizedNode<?, ?>> toNormalizedNode(
64 InstanceIdentifier<T> path, T data);
67 * Translates supplied YANG Instance Identifier and NormalizedNode into Binding data.
69 * @param path Binding Instance Identifier
70 * @param data NormalizedNode representing data
71 * @return DOM Instance Identifier
73 @Nullable Entry<InstanceIdentifier<?>, DataObject> fromNormalizedNode(@NonNull YangInstanceIdentifier path,
74 NormalizedNode<?, ?> data);
77 * Translates supplied NormalizedNode Notification into Binding data.
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
83 @Nullable Notification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data);
86 * Translates supplied NormalizedNode Notification into Binding data, optionally taking an instant
87 * when the notification was generated.
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
95 @Nullable Notification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data,
96 @Nullable Instant eventInstant);
99 * Translates supplied NormalizedNode RPC input or output into Binding data.
101 * @param containerPath Container path (RPC type + input/output)
102 * @param data NormalizedNode representing data
103 * @return Binding representation of RPC data
105 @Nullable DataObject fromNormalizedNodeRpcData(@NonNull Absolute containerPath, @NonNull ContainerNode data);
108 * Translates supplied ContainerNode action input.
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
116 <T extends RpcInput> @NonNull T fromNormalizedNodeActionInput(
117 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode input);
120 * Translates supplied ContainerNode action output.
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
128 <T extends RpcOutput> @NonNull T fromNormalizedNodeActionOutput(
129 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode output);
132 * Translates supplied Binding Notification or output into NormalizedNode notification.
134 * @param data NormalizedNode representing notification data
135 * @return NormalizedNode representation of notification
137 @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Notification data);
140 * Translates supplied Binding RPC input or output into NormalizedNode data.
142 * @param data NormalizedNode representing rpc data
143 * @return NormalizedNode representation of rpc data
145 @NonNull ContainerNode toNormalizedNodeRpcData(@NonNull DataContainer data);
148 * Lazily translates supplied Binding action input into NormalizedNode data.
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
156 @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
157 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
158 @NonNull RpcInput input);
161 * Lazily translates supplied Binding action input into NormalizedNode data.
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
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);
175 * Translates supplied Binding action input into NormalizedNode data.
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
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)
190 * Lazily translates supplied Binding action output into NormalizedNode data.
192 * @param action Binding action class
193 * @param output Binding action output
194 * @return NormalizedNode representation of action output
197 @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
198 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
199 @NonNull RpcOutput output);
202 * Lazily translates supplied Binding action output into NormalizedNode data.
204 * @param action Binding action class
205 * @param output Binding action output
206 * @return NormalizedNode representation of action output
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);
215 * Translates supplied Binding action output into NormalizedNode data.
217 * @param output Binding action output
218 * @return NormalizedNode representation of action output
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)