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 static java.util.Objects.requireNonNull;
12 import com.google.common.annotations.Beta;
13 import com.google.common.collect.ImmutableList;
14 import com.google.common.collect.ImmutableSet;
15 import java.time.Instant;
16 import java.util.Map.Entry;
17 import org.eclipse.jdt.annotation.NonNull;
18 import org.eclipse.jdt.annotation.Nullable;
19 import org.opendaylight.mdsal.binding.spec.reflect.BindingReflections;
20 import org.opendaylight.yangtools.yang.binding.Action;
21 import org.opendaylight.yangtools.yang.binding.Augmentation;
22 import org.opendaylight.yangtools.yang.binding.BaseNotification;
23 import org.opendaylight.yangtools.yang.binding.DataContainer;
24 import org.opendaylight.yangtools.yang.binding.DataObject;
25 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
26 import org.opendaylight.yangtools.yang.binding.Notification;
27 import org.opendaylight.yangtools.yang.binding.RpcInput;
28 import org.opendaylight.yangtools.yang.binding.RpcOutput;
29 import org.opendaylight.yangtools.yang.common.YangConstants;
30 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
31 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier;
32 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.PathArgument;
33 import org.opendaylight.yangtools.yang.data.api.schema.ContainerNode;
34 import org.opendaylight.yangtools.yang.data.api.schema.DataContainerChild;
35 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
36 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Absolute;
39 * Serialization service, which provides two-way serialization between Java Binding Data representation and
40 * NormalizedNode representation.
42 public interface BindingNormalizedNodeSerializer {
44 * Result of a {@link BindingNormalizedNodeSerializer#toNormalizedNode(InstanceIdentifier, DataObject)}. Since the
45 * Binding {@link Augmentation} does not have an exact equivalent, there are two specializations of this class:
46 * {@link NodeResult} and {@link AugmentationResult}.
48 sealed interface NormalizedResult {
50 * Return the {@link YangInstanceIdentifier} path of this result.
52 * @return A {@link YangInstanceIdentifier}
54 @NonNull YangInstanceIdentifier path();
58 * A {@link NormalizedResult} for an {@link Augmentation}.
60 * @param path A YangInstanceIdentifier identifying the parent of this augmentation
61 * @param possibleChildren {@link PathArgument}s of each possible child
62 * @param children Augmentation children
64 record AugmentationResult(
65 @NonNull YangInstanceIdentifier path,
66 @NonNull ImmutableSet<PathArgument> possibleChildren,
67 @NonNull ImmutableList<DataContainerChild> children) implements NormalizedResult {
68 public AugmentationResult {
70 requireNonNull(possibleChildren);
71 requireNonNull(children);
75 record NodeResult(@NonNull YangInstanceIdentifier path, @NonNull NormalizedNode node) implements NormalizedResult {
83 * Translates supplied Binding Instance Identifier into NormalizedNode instance identifier.
85 * @param binding Binding Instance Identifier
86 * @return DOM Instance Identifier
87 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
89 // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
90 @NonNull YangInstanceIdentifier toYangInstanceIdentifier(@NonNull InstanceIdentifier<?> binding);
93 * Translates supplied YANG Instance Identifier into Binding instance identifier.
95 * @param dom YANG Instance Identifier
96 * @return Binding Instance Identifier, or null if the instance identifier is not representable.
98 // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
99 <T extends DataObject> @Nullable InstanceIdentifier<T> fromYangInstanceIdentifier(
100 @NonNull YangInstanceIdentifier dom);
103 * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
105 * @param path Binding Instance Identifier pointing to data
106 * @param data Data object representing data
107 * @return {@link NormalizedResult} representation
108 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
110 <T extends DataObject> @NonNull NormalizedResult toNormalizedNode(InstanceIdentifier<T> path, T data);
113 * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
115 * @param path Binding Instance Identifier pointing to data
116 * @param data Data object representing data
117 * @return {@link NormalizedResult} representation
118 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
120 <A extends Augmentation<?>> @NonNull AugmentationResult toNormalizedAugmentation(InstanceIdentifier<A> path,
124 * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
126 * @param path Binding Instance Identifier pointing to data
127 * @param data Data object representing data
128 * @return {@link NormalizedResult} representation
129 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
131 <T extends DataObject> @NonNull NodeResult toNormalizedDataObject(InstanceIdentifier<T> path, T data);
134 * Translates supplied YANG Instance Identifier and NormalizedNode into Binding data.
136 * @param path Binding Instance Identifier
137 * @param data NormalizedNode representing data
138 * @return DOM Instance Identifier
140 @Nullable Entry<InstanceIdentifier<?>, DataObject> fromNormalizedNode(@NonNull YangInstanceIdentifier path,
141 NormalizedNode data);
144 * Translates supplied NormalizedNode Notification into Binding data.
146 * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
147 * @param data NormalizedNode representing data
148 * @return Binding representation of Notification
150 @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data);
153 * Translates supplied NormalizedNode Notification into Binding data, optionally taking an instant
154 * when the notification was generated.
156 * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
157 * @param data NormalizedNode representing data
158 * @param eventInstant optional instant when the event was generated
159 * @return Binding representation of Notification
162 @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data,
163 @Nullable Instant eventInstant);
166 * Translates supplied NormalizedNode RPC input or output into Binding data.
168 * @param containerPath Container path (RPC type + input/output)
169 * @param data NormalizedNode representing data
170 * @return Binding representation of RPC data
172 @Nullable DataObject fromNormalizedNodeRpcData(@NonNull Absolute containerPath, @NonNull ContainerNode data);
175 * Translates supplied ContainerNode action input.
177 * @param action Binding action class
178 * @param input ContainerNode representing data
179 * @return Binding representation of action input
180 * @throws NullPointerException if any of the arguments is null
183 <T extends RpcInput> @NonNull T fromNormalizedNodeActionInput(
184 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode input);
187 * Translates supplied ContainerNode action output.
189 * @param action Binding action class
190 * @param output ContainerNode representing data
191 * @return Binding representation of action output
192 * @throws NullPointerException if any of the arguments is null
195 <T extends RpcOutput> @NonNull T fromNormalizedNodeActionOutput(
196 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode output);
199 * Translates supplied Binding Notification or output into NormalizedNode notification.
201 * @param data {@link Notification} representing notification data
202 * @return NormalizedNode representation of notification
204 @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Notification<?> data);
207 * Translates supplied Binding Notification or output into NormalizedNode notification.
209 * @param path schema node identifier of the notification
210 * @param data {@link BaseNotification} representing notification data
211 * @return NormalizedNode representation of notification
213 @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Absolute path, @NonNull BaseNotification data);
216 * Translates supplied Binding RPC input or output into NormalizedNode data.
218 * @param data NormalizedNode representing rpc data
219 * @return NormalizedNode representation of rpc data
221 @NonNull ContainerNode toNormalizedNodeRpcData(@NonNull DataContainer data);
224 * Lazily translates supplied Binding action input into NormalizedNode data.
226 * @param action Binding action class
227 * @param input Binding action input
228 * @return NormalizedNode representation of action input
229 * @throws NullPointerException if any of the arguments is null
232 @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
233 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
234 @NonNull RpcInput input);
237 * Lazily translates supplied Binding action input into NormalizedNode data.
239 * @param action Binding action class
240 * @param input Binding action input
241 * @return NormalizedNode representation of action input
242 * @throws NullPointerException if any of the arguments is null
244 @Beta default @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
245 @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
246 return toLazyNormalizedNodeActionInput(action,
247 new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input);
251 * Translates supplied Binding action input into NormalizedNode data.
253 * @param action Binding action class
254 * @param input Binding action input
255 * @return NormalizedNode representation of action input
256 * @throws NullPointerException if any of the arguments is null
258 @Beta default @NonNull ContainerNode toNormalizedNodeActionInput(
259 @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcInput input) {
260 return toLazyNormalizedNodeActionInput(action,
261 new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), input)
266 * Lazily translates supplied Binding action output into NormalizedNode data.
268 * @param action Binding action class
269 * @param output Binding action output
270 * @return NormalizedNode representation of action output
273 @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
274 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
275 @NonNull RpcOutput output);
278 * Lazily translates supplied Binding action output into NormalizedNode data.
280 * @param action Binding action class
281 * @param output Binding action output
282 * @return NormalizedNode representation of action output
284 @Beta default @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
285 @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcOutput output) {
286 return toLazyNormalizedNodeActionOutput(action,
287 new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), output);
291 * Translates supplied Binding action output into NormalizedNode data.
293 * @param output Binding action output
294 * @return NormalizedNode representation of action output
296 @Beta default @NonNull ContainerNode toNormalizedNodeActionOutput(
297 @NonNull final Class<? extends Action<?, ?, ?>> action, @NonNull final RpcOutput output) {
298 return toLazyNormalizedNodeActionOutput(action,
299 new NodeIdentifier(YangConstants.operationInputQName(BindingReflections.getQNameModule(action))), output)