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.yangtools.yang.binding.Action;
20 import org.opendaylight.yangtools.yang.binding.Augmentation;
21 import org.opendaylight.yangtools.yang.binding.BaseNotification;
22 import org.opendaylight.yangtools.yang.binding.DataContainer;
23 import org.opendaylight.yangtools.yang.binding.DataObject;
24 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
25 import org.opendaylight.yangtools.yang.binding.Notification;
26 import org.opendaylight.yangtools.yang.binding.RpcInput;
27 import org.opendaylight.yangtools.yang.binding.RpcOutput;
28 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
29 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier;
30 import org.opendaylight.yangtools.yang.data.api.schema.ContainerNode;
31 import org.opendaylight.yangtools.yang.data.api.schema.DataContainerChild;
32 import org.opendaylight.yangtools.yang.data.api.schema.NormalizedNode;
33 import org.opendaylight.yangtools.yang.model.api.stmt.SchemaNodeIdentifier.Absolute;
36 * Serialization service, which provides two-way serialization between Java Binding Data representation and
37 * NormalizedNode representation.
39 public interface BindingNormalizedNodeSerializer {
41 * Result of a {@link BindingNormalizedNodeSerializer#toNormalizedNode(InstanceIdentifier, DataObject)}. Since the
42 * Binding {@link Augmentation} does not have an exact equivalent, there are two specializations of this class:
43 * {@link NodeResult} and {@link AugmentationResult}.
45 sealed interface NormalizedResult {
47 * Return the {@link YangInstanceIdentifier} path of this result.
49 * @return A {@link YangInstanceIdentifier}
51 @NonNull YangInstanceIdentifier path();
55 * A {@link NormalizedResult} for an {@link Augmentation}.
57 * @param path A YangInstanceIdentifier identifying the parent of this augmentation
58 * @param possibleChildren {@link NodeIdentifier}s of each possible child
59 * @param children Augmentation children
61 record AugmentationResult(
62 @NonNull YangInstanceIdentifier path,
63 @NonNull ImmutableSet<NodeIdentifier> possibleChildren,
64 @NonNull ImmutableList<DataContainerChild> children) implements NormalizedResult {
65 public AugmentationResult {
67 requireNonNull(possibleChildren);
68 requireNonNull(children);
72 record NodeResult(@NonNull YangInstanceIdentifier path, @NonNull NormalizedNode node) implements NormalizedResult {
80 * Translates supplied Binding Instance Identifier into NormalizedNode instance identifier.
82 * @param binding Binding Instance Identifier
83 * @return DOM Instance Identifier
84 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
86 // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
87 @NonNull YangInstanceIdentifier toYangInstanceIdentifier(@NonNull InstanceIdentifier<?> binding);
90 * Translates supplied YANG Instance Identifier into Binding instance identifier.
92 * @param dom YANG Instance Identifier
93 * @return Binding Instance Identifier, or null if the instance identifier is not representable.
95 // FIXME: MDSAL-525: reconcile this with BindingInstanceIdentifierCodec
96 <T extends DataObject> @Nullable InstanceIdentifier<T> fromYangInstanceIdentifier(
97 @NonNull YangInstanceIdentifier dom);
100 * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
102 * @param path Binding Instance Identifier pointing to data
103 * @param data Data object representing data
104 * @return {@link NormalizedResult} representation
105 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
107 <T extends DataObject> @NonNull NormalizedResult toNormalizedNode(InstanceIdentifier<T> path, T data);
110 * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
112 * @param path Binding Instance Identifier pointing to data
113 * @param data Data object representing data
114 * @return {@link NormalizedResult} representation
115 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
117 <A extends Augmentation<?>> @NonNull AugmentationResult toNormalizedAugmentation(InstanceIdentifier<A> path,
121 * Translates supplied Binding Instance Identifier and data into NormalizedNode representation.
123 * @param path Binding Instance Identifier pointing to data
124 * @param data Data object representing data
125 * @return {@link NormalizedResult} representation
126 * @throws IllegalArgumentException If supplied Instance Identifier is not valid.
128 <T extends DataObject> @NonNull NodeResult toNormalizedDataObject(InstanceIdentifier<T> path, T data);
131 * Translates supplied YANG Instance Identifier and NormalizedNode into Binding data.
133 * @param path Binding Instance Identifier
134 * @param data NormalizedNode representing data
135 * @return DOM Instance Identifier
137 @Nullable Entry<InstanceIdentifier<?>, DataObject> fromNormalizedNode(@NonNull YangInstanceIdentifier path,
138 NormalizedNode data);
141 * Translates supplied NormalizedNode Notification into Binding data.
143 * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
144 * @param data NormalizedNode representing data
145 * @return Binding representation of Notification
147 @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data);
150 * Translates supplied NormalizedNode Notification into Binding data, optionally taking an instant
151 * when the notification was generated.
153 * @param path Schema Path of Notification, schema path is absolute, and consists of Notification QName.
154 * @param data NormalizedNode representing data
155 * @param eventInstant optional instant when the event was generated
156 * @return Binding representation of Notification
159 @NonNull BaseNotification fromNormalizedNodeNotification(@NonNull Absolute path, @NonNull ContainerNode data,
160 @Nullable Instant eventInstant);
163 * Translates supplied NormalizedNode RPC input or output into Binding data.
165 * @param containerPath Container path (RPC type + input/output)
166 * @param data NormalizedNode representing data
167 * @return Binding representation of RPC data
169 @Nullable DataObject fromNormalizedNodeRpcData(@NonNull Absolute containerPath, @NonNull ContainerNode data);
172 * Translates supplied ContainerNode action input.
174 * @param action Binding action class
175 * @param input ContainerNode representing data
176 * @return Binding representation of action input
177 * @throws NullPointerException if any of the arguments is null
180 <T extends RpcInput> @NonNull T fromNormalizedNodeActionInput(
181 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode input);
184 * Translates supplied ContainerNode action output.
186 * @param action Binding action class
187 * @param output ContainerNode representing data
188 * @return Binding representation of action output
189 * @throws NullPointerException if any of the arguments is null
192 <T extends RpcOutput> @NonNull T fromNormalizedNodeActionOutput(
193 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull ContainerNode output);
196 * Translates supplied Binding Notification or output into NormalizedNode notification.
198 * @param data {@link Notification} representing notification data
199 * @return NormalizedNode representation of notification
201 @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Notification<?> data);
204 * Translates supplied Binding Notification or output into NormalizedNode notification.
206 * @param path schema node identifier of the notification
207 * @param data {@link BaseNotification} representing notification data
208 * @return NormalizedNode representation of notification
210 @NonNull ContainerNode toNormalizedNodeNotification(@NonNull Absolute path, @NonNull BaseNotification data);
213 * Translates supplied Binding RPC input or output into NormalizedNode data.
215 * @param data NormalizedNode representing rpc data
216 * @return NormalizedNode representation of rpc data
218 @NonNull ContainerNode toNormalizedNodeRpcData(@NonNull DataContainer data);
221 * Lazily translates supplied Binding action input into NormalizedNode data.
223 * @param action Binding action class
224 * @param input Binding action input
225 * @return NormalizedNode representation of action input
226 * @throws NullPointerException if any of the arguments is null
229 @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
230 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
231 @NonNull RpcInput input);
234 * Lazily translates supplied Binding action input into NormalizedNode data.
236 * @param action Binding action class
237 * @param input Binding action input
238 * @return NormalizedNode representation of action input
239 * @throws NullPointerException if any of the arguments is null
242 @NonNull BindingLazyContainerNode<RpcInput> toLazyNormalizedNodeActionInput(
243 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull RpcInput input);
246 * Translates supplied Binding action input into NormalizedNode data.
248 * @param action Binding action class
249 * @param input Binding action input
250 * @return NormalizedNode representation of action input
251 * @throws NullPointerException if any of the arguments is null
254 @NonNull ContainerNode toNormalizedNodeActionInput(@NonNull Class<? extends Action<?, ?, ?>> action,
255 @NonNull RpcInput input);
258 * Lazily translates supplied Binding action output into NormalizedNode data.
260 * @param action Binding action class
261 * @param output Binding action output
262 * @return NormalizedNode representation of action output
265 @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
266 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull NodeIdentifier identifier,
267 @NonNull RpcOutput output);
270 * Lazily translates supplied Binding action output into NormalizedNode data.
272 * @param action Binding action class
273 * @param output Binding action output
274 * @return NormalizedNode representation of action output
277 @NonNull BindingLazyContainerNode<RpcOutput> toLazyNormalizedNodeActionOutput(
278 @NonNull Class<? extends Action<?, ?, ?>> action, @NonNull RpcOutput output);
281 * Translates supplied Binding action output into NormalizedNode data.
283 * @param output Binding action output
284 * @return NormalizedNode representation of action output
287 @NonNull ContainerNode toNormalizedNodeActionOutput(@NonNull Class<? extends Action<?, ?, ?>> action,
288 @NonNull RpcOutput output);