2 * Copyright (c) 2015 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 com.google.common.base.Optional;
12 import com.google.common.collect.ImmutableCollection;
13 import java.util.List;
14 import javax.annotation.Nonnull;
15 import javax.annotation.Nullable;
16 import org.opendaylight.yangtools.yang.binding.BindingStreamEventWriter;
17 import org.opendaylight.yangtools.yang.binding.DataObject;
18 import org.opendaylight.yangtools.yang.binding.InstanceIdentifier;
19 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
20 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriter;
21 import org.opendaylight.yangtools.yang.model.api.DocumentedNode.WithStatus;
24 * Subtree codec specific to model subtree between Java Binding and NormalizedNode.
27 public interface BindingCodecTreeNode<T extends DataObject> extends BindingNormalizedNodeCodec<T> {
30 * Returns binding class of interface which represents API of current schema node. The result is same as invoking
31 * {@link DataObject#getImplementedInterface()} on instance of data.
33 * @return interface which defines API of binding representation of data.
36 Class<T> getBindingClass();
39 * Returns child context as if it was walked by {@link BindingStreamEventWriter}. This means that to enter case,
40 * one must issue getChild(ChoiceClass).getChild(CaseClass).
42 * @param childClass Child class by Biding Stream navigation
43 * @return Context of child
44 * @throws IllegalArgumentException
45 * If supplied child class is not valid in specified context.
48 <E extends DataObject> BindingCodecTreeNode<E> streamChild(@Nonnull Class<E> childClass);
51 * Returns child context as if it was walked by {@link BindingStreamEventWriter}. This means that to enter case,
52 * one must issue getChild(ChoiceClass).getChild(CaseClass).
55 * This method differs from {@link #streamChild(Class)}, that is less strict for interfaces representing
56 * augmentation and cases, that may return {@link BindingCodecTreeNode} even if augmentation interface containing
57 * same data was supplied and does not represent augmentation of this node.
60 * @return Context of child or Optional absent is supplied class is not
61 * applicable in context.
63 <E extends DataObject> Optional<? extends BindingCodecTreeNode<E>> possibleStreamChild(
64 @Nonnull Class<E> childClass);
67 * Returns nested node context using supplied YANG Instance Identifier.
70 * Yang Instance Identifier Argument
71 * @return Context of child
72 * @throws IllegalArgumentException
73 * If supplied argument does not represent valid child.
76 BindingCodecTreeNode<?> yangPathArgumentChild(@Nonnull YangInstanceIdentifier.PathArgument child);
79 * Returns nested node context using supplied Binding Instance Identifier and adds YANG instance identifiers to
83 * Binding Instance Identifier Argument
85 * Mutable instance of list, which is appended by YangInstanceIdentifiers
86 * as tree is walked. Use null if such side-product is not needed.
87 * @return Context of child
88 * @throws IllegalArgumentException
89 * If supplied argument does not represent valid child.
92 BindingCodecTreeNode<?> bindingPathArgumentChild(@Nonnull InstanceIdentifier.PathArgument arg,
93 @Nullable List<YangInstanceIdentifier.PathArgument> builder);
96 * Returns codec which uses caches serialization / deserialization results.
99 * Caching may introduce performance penalty to serialization / deserialization
100 * but may decrease use of heap for repetitive objects.
102 * @param cacheSpecifier Set of objects, for which cache may be in place
103 * @return Codec whihc uses cache for serialization / deserialization.
106 BindingNormalizedNodeCachingCodec<T> createCachingCodec(@Nonnull
107 ImmutableCollection<Class<? extends DataObject>> cacheSpecifier);
110 void writeAsNormalizedNode(T data, NormalizedNodeStreamWriter writer);
113 * Serializes path argument for current node.
115 * @param arg Binding Path Argument, may be null if Binding Instance Identifier does not have
116 * representation for current node (e.g. choice or case).
117 * @return Yang Path Argument, may be null if Yang Instance Identifier does not have
118 * representation for current node (e.g. case).
119 * @throws IllegalArgumentException If supplied {@code arg} is not valid.
122 @Nullable YangInstanceIdentifier.PathArgument serializePathArgument(@Nullable InstanceIdentifier.PathArgument arg);
125 * Deserializes path argument for current node.
127 * @param arg Yang Path Argument, may be null if Yang Instance Identifier does not have
128 * representation for current node (e.g. case).
129 * @return Binding Path Argument, may be null if Binding Instance Identifier does not have
130 * representation for current node (e.g. choice or case).
131 * @throws IllegalArgumentException If supplied {@code arg} is not valid.
134 @Nullable InstanceIdentifier.PathArgument deserializePathArgument(
135 @Nullable YangInstanceIdentifier.PathArgument arg);
138 * Return the schema node associated with this node.
140 * @return A schema node.
142 @Nonnull WithStatus getSchema();
145 * Return a summary of addressability of potential children. Binding specification does not allow all DOM tree
146 * elements to be directly addressed, which means some recursive tree operations, like data tree changes do not
147 * have a one-to-one mapping from DOM to binding in all cases. This method provides an optimization hint to guide
148 * translation of data structures, allowing for fast paths when all children are known to either be addressable
149 * or non-addressable.
151 * @return Summary children addressability.
153 @Nonnull ChildAddressabilitySummary getChildAddressabilitySummary();
156 * Enumeration of possible addressability attribute of all children.
158 enum ChildAddressabilitySummary {
160 * All children are addressable.
164 * All children are non-addressable, including the case when this node does not have any children.
168 * Mixed children, some are addressable and some are not.