2 * Copyright (c) 2023 PANTHEON.tech, s.r.o. 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.util.List;
12 import org.eclipse.jdt.annotation.NonNull;
13 import org.eclipse.jdt.annotation.Nullable;
14 import org.opendaylight.yangtools.yang.binding.DataObject;
15 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
16 import org.opendaylight.yangtools.yang.common.Empty;
17 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
20 * Common interface shared between {@link BindingDataObjectCodecTreeNode} and {@link BindingAugmentationCodecTreeNode}.
21 * This interface should never be implemented on its own.
23 * @param <T> DataObject type
26 public interface CommonDataObjectCodecTreeNode<T extends DataObject>
27 extends BindingDataObjectCodecTreeParent<Empty>, BindingObjectCodecTreeNode<T> {
29 * Returns binding class of interface which represents API of current schema node. The result is same as invoking
30 * {@link DataObject#implementedInterface()} on instance of data.
32 * @return interface which defines API of binding representation of data.
35 @NonNull Class<T> getBindingClass();
38 * Returns child context as if it was walked by {@link BindingStreamEventWriter}. This means that to enter case,
39 * one must issue getChild(ChoiceClass).getChild(CaseClass).
42 * This method differs from {@link #getStreamChild(Class)}, that is less strict for interfaces representing
43 * augmentation and cases, that may return {@link BindingCodecTreeNode} even if augmentation interface containing
44 * same data was supplied and does not represent augmentation of this node.
46 * @param childClass Child class by Binding Stream navigation
47 * @return Context of child or {@code null} is supplied class is not applicable in context.
48 * @throws NullPointerException if {@code childClass} is {@code null}
50 <E extends DataObject> @Nullable CommonDataObjectCodecTreeNode<E> streamChild(@NonNull Class<E> childClass);
53 * Returns nested node context using supplied YANG Instance Identifier.
56 * Yang Instance Identifier Argument
57 * @return Context of child
58 * @throws IllegalArgumentException
59 * If supplied argument does not represent valid child.
61 @NonNull BindingCodecTreeNode yangPathArgumentChild(YangInstanceIdentifier.@NonNull PathArgument child);
64 * Returns nested node context using supplied Binding Instance Identifier and adds YANG instance identifiers to
68 * Binding Instance Identifier Argument
70 * Mutable instance of list, which is appended by YangInstanceIdentifiers
71 * as tree is walked. Use null if such side-product is not needed.
72 * @return Context of child
73 * @throws IllegalArgumentException
74 * If supplied argument does not represent valid child.
76 @NonNull CommonDataObjectCodecTreeNode<?> bindingPathArgumentChild(InstanceIdentifier.@NonNull PathArgument arg,
77 @Nullable List<YangInstanceIdentifier.PathArgument> builder);
80 * Serializes path argument for current node.
82 * @param arg Binding Path Argument, may be null if Binding Instance Identifier does not have
83 * representation for current node (e.g. choice or case).
84 * @return Yang Path Argument, may be null if Yang Instance Identifier does not have
85 * representation for current node (e.g. case).
86 * @throws IllegalArgumentException If supplied {@code arg} is not valid.
89 YangInstanceIdentifier.@Nullable PathArgument serializePathArgument(InstanceIdentifier.@Nullable PathArgument arg);
92 * Deserializes path argument for current node.
94 * @param arg Yang Path Argument, may be null if Yang Instance Identifier does not have
95 * representation for current node (e.g. case).
96 * @return Binding Path Argument, may be null if Binding Instance Identifier does not have
97 * representation for current node (e.g. choice or case).
98 * @throws IllegalArgumentException If supplied {@code arg} is not valid.
101 InstanceIdentifier.@Nullable PathArgument deserializePathArgument(
102 YangInstanceIdentifier.@Nullable PathArgument arg);
105 * Return a summary of addressability of potential children. Binding specification does not allow all DOM tree
106 * elements to be directly addressed, which means some recursive tree operations, like data tree changes do not
107 * have a one-to-one mapping from DOM to binding in all cases. This method provides an optimization hint to guide
108 * translation of data structures, allowing for fast paths when all children are known to either be addressable
109 * or non-addressable.
111 * @return Summary children addressability.
113 @NonNull ChildAddressabilitySummary getChildAddressabilitySummary();
116 * Enumeration of possible addressability attribute of all children.
118 enum ChildAddressabilitySummary {
120 * All children are addressable.
124 * All children are non-addressable, including the case when this node does not have any children.
128 * Mixed children, some are addressable and some are not.