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.BaseNotification;
18 import org.opendaylight.yangtools.yang.binding.DataContainer;
19 import org.opendaylight.yangtools.yang.binding.DataObject;
20 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
21 import org.opendaylight.yangtools.yang.binding.Notification;
22 import org.opendaylight.yangtools.yang.binding.RpcInput;
23 import org.opendaylight.yangtools.yang.binding.RpcOutput;
24 import org.opendaylight.yangtools.yang.common.YangConstants;
25 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
26 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier;
27 import org.opendaylight.yangtools.yang.data.api.schema.ContainerNode;
28 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
29 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Absolute;
32 * Serialization service, which provides two-way serialization between Java
33 * Binding Data representation and NormalizedNode representation.
35 public interface BindingNormalizedNodeSerializer {
37 * Translates supplied Binding Instance Identifier into NormalizedNode instance identifier.
39 * @param binding Binding Instance Identifier
40 * @return DOM Instance Identifier
41 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
43 // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
44 @NonNull YangInstanceIdentifier toYangInstanceIdentifier(@NonNull InstanceIdentifier<?> binding);
47 * Translates supplied YANG Instance Identifier into Binding instance identifier.
49 * @param dom YANG Instance Identifier
50 * @return Binding Instance Identifier, or null if the instance identifier is not representable.
52 // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
53 <T extends DataObject> @Nullable InstanceIdentifier<T> fromYangInstanceIdentifier(
54 @NonNull YangInstanceIdentifier dom);
57 * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
59 * @param path Binding Instance Identifier pointing to data
60 * @param data Data object representing data
61 * @return NormalizedNode representation
62 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
64 <T extends DataObject> @NonNull Entry<YangInstanceIdentifier, NormalizedNode> toNormalizedNode(
65 InstanceIdentifier<T> path, T data);
68 * Translates supplied YANG Instance Identifier and NormalizedNode into Binding data.
70 * @param path Binding Instance Identifier
71 * @param data NormalizedNode representing data
72 * @return DOM Instance Identifier
74 @Nullable Entry<InstanceIdentifier<?>, DataObject> fromNormalizedNode(@NonNull YangInstanceIdentifier path,
78 * Translates supplied NormalizedNode Notification into Binding data.
80 * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
81 * @param data NormalizedNode representing data
82 * @return Binding representation of Notification
84 @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data);
87 * Translates supplied NormalizedNode Notification into Binding data, optionally taking an instant
88 * when the notification was generated.
90 * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
91 * @param data NormalizedNode representing data
92 * @param eventInstant optional instant when the event was generated
93 * @return Binding representation of Notification
96 @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data,
97 @Nullable Instant eventInstant);
100 * Translates supplied NormalizedNode RPC input or output into Binding data.
102 * @param containerPath Container path (RPC type + input/output)
103 * @param data NormalizedNode representing data
104 * @return Binding representation of RPC data
106 @Nullable DataObject fromNormalizedNodeRpcData(@NonNull Absolute containerPath, @NonNull ContainerNode data);
109 * Translates supplied ContainerNode action input.
111 * @param action Binding action class
112 * @param input ContainerNode representing data
113 * @return Binding representation of action input
114 * @throws NullPointerException if any of the arguments is null
117 <T extends RpcInput> @NonNull T fromNormalizedNodeActionInput(
118 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode input);
121 * Translates supplied ContainerNode action output.
123 * @param action Binding action class
124 * @param output ContainerNode representing data
125 * @return Binding representation of action output
126 * @throws NullPointerException if any of the arguments is null
129 <T extends RpcOutput> @NonNull T fromNormalizedNodeActionOutput(
130 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode output);
133 * Translates supplied Binding Notification or output into NormalizedNode notification.
135 * @param data {@link Notification} representing notification data
136 * @return NormalizedNode representation of notification
138 @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Notification<?> data);
141 * Translates supplied Binding Notification or output into NormalizedNode notification.
143 * @param path schema node identifier of the notification
144 * @param data {@link BaseNotification} representing notification data
145 * @return NormalizedNode representation of notification
147 @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Absolute path, @NonNull BaseNotification data);
150 * Translates supplied Binding RPC input or output into NormalizedNode data.
152 * @param data NormalizedNode representing rpc data
153 * @return NormalizedNode representation of rpc data
155 @NonNull ContainerNode toNormalizedNodeRpcData(@NonNull DataContainer data);
158 * Lazily translates supplied Binding action input into NormalizedNode data.
160 * @param action Binding action class
161 * @param input Binding action input
162 * @return NormalizedNode representation of action input
163 * @throws NullPointerException if any of the arguments is null
166 @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
167 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
168 @NonNull RpcInput input);
171 * Lazily translates supplied Binding action input into NormalizedNode data.
173 * @param action Binding action class
174 * @param input Binding action input
175 * @return NormalizedNode representation of action input
176 * @throws NullPointerException if any of the arguments is null
178 @Beta default @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
179 @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
180 return toLazyNormalizedNodeActionInput(action,
181 new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input);
185 * Translates supplied Binding action input into NormalizedNode data.
187 * @param action Binding action class
188 * @param input Binding action input
189 * @return NormalizedNode representation of action input
190 * @throws NullPointerException if any of the arguments is null
192 @Beta default @NonNull ContainerNode toNormalizedNodeActionInput(
193 @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
194 return toLazyNormalizedNodeActionInput(action,
195 new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input)
200 * Lazily translates supplied Binding action output into NormalizedNode data.
202 * @param action Binding action class
203 * @param output Binding action output
204 * @return NormalizedNode representation of action output
207 @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
208 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
209 @NonNull RpcOutput output);
212 * Lazily translates supplied Binding action output into NormalizedNode data.
214 * @param action Binding action class
215 * @param output Binding action output
216 * @return NormalizedNode representation of action output
218 @Beta default @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
219 @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcOutput output) {
220 return toLazyNormalizedNodeActionOutput(action,
221 new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), output);
225 * Translates supplied Binding action output into NormalizedNode data.
227 * @param output Binding action output
228 * @return NormalizedNode representation of action output
230 @Beta default @NonNull ContainerNode toNormalizedNodeActionOutput(
231 @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcOutput output) {
232 return toLazyNormalizedNodeActionOutput(action,
233 new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), output)