2 * Copyright (c) 2017 Pantheon Technologies 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.javav2.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.mdsal.binding.javav2.spec.base.TreeArgument;
17 import org.opendaylight.mdsal.binding.javav2.spec.base.TreeNode;
18 import org.opendaylight.mdsal.binding.javav2.spec.runtime.BindingStreamEventWriter;
19 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
20 import org.opendaylight.yangtools.yang.data.api.schema.stream.NormalizedNodeStreamWriter;
23 * Specific subtree codec to model subtree between Java Binding and DOM.
26 * - Binding representation of data
29 public interface BindingTreeNodeCodec<T extends TreeNode> extends BindingNormalizedNodeCodec<T> {
32 * Returns binding class of interface which represents API of current schema
35 * @return interface which defines API of binding representation of data.
38 Class<T> getBindingClass();
41 * Returns child context as if it was walked by
42 * {@link BindingStreamEventWriter}. This means that to enter case, one must
43 * issue getChild(ChoiceClass).getChild(CaseClass).
46 * - child class by Biding Stream navigation
47 * @param <E> data type
48 * @return context of child
49 * @throws IllegalArgumentException
50 * - if supplied child class is not valid in specified context
53 <E extends TreeNode> BindingTreeNodeCodec<E> streamChild(@Nonnull Class<E> childClass);
56 * Returns child context as if it was walked by
57 * {@link BindingStreamEventWriter}. This means that to enter case, one must
58 * issue getChild(ChoiceClass).getChild(CaseClass).
60 * This method differs from {@link #streamChild(Class)}, that is less
61 * stricter for interfaces representing augmentation and cases, that may
62 * return {@link BindingTreeNodeCodec} even if augmentation interface
63 * containing same data was supplied and does not represent augmentation of
67 * - child class by Binding Stream navigation
68 * @param <E> data type
69 * @return context of child or Optional absent if supplied is not applicable
72 <E extends TreeNode> Optional<? extends BindingTreeNodeCodec<E>> possibleStreamChild(@Nonnull Class<E> childClass);
75 * Returns nested node context using supplied YANG Instance Identifier.
78 * - Yang Instance Identifier Argument
79 * @return context of child
80 * @throws IllegalArgumentException
81 * - if supplied argument does not represent valid child
84 BindingTreeNodeCodec<?> yangPathArgumentChild(@Nonnull YangInstanceIdentifier.PathArgument child);
87 * Returns nested node context using supplied Binding Instance Identifier
88 * and adds YANG instance identifiers to supplied list.
91 * - Binding Instance Identifier Argument
93 * - mutable instance of list, which is appended by
94 * YangInstanceIdentifiers as tree is walked, use null if such
95 * side-product is not needed
96 * @return context of child
97 * @throws IllegalArgumentException
98 * - if supplied argument does not represent valid child.
101 BindingTreeNodeCodec<?> bindingPathArgumentChild(@Nonnull TreeArgument<?> arg,
102 @Nullable List<YangInstanceIdentifier.PathArgument> builder);
105 * Returns codec which uses caches serialization / deserialization results.
108 * Caching may introduce performance penalty to serialization /
109 * deserialization but may decrease use of heap for repetitive objects.
111 * @param cacheSpecifier
112 * - set of objects, for which cache may be in place
113 * @return codec which uses cache for serialization / deserialization
116 BindingNormalizedNodeCachingCodec<T>
117 createCachingCodec(@Nonnull ImmutableCollection<Class<? extends TreeNode>> cacheSpecifier);
120 * Writes data representing object to supplied stream.
123 * - representing object
127 void writeAsNormalizedNode(T data, NormalizedNodeStreamWriter writer);
130 * Serializes path argument for current node.
133 * - Binding Path Argument, may be null if Binding Instance
134 * Identifier does not have representation for current node (e.g.
136 * @return Yang Path Argument, may be null if Yang Instance Identifier does
137 * not have representation for current node (e.g. case).
138 * @throws IllegalArgumentException
139 * - if supplied {@code arg} is not valid.
142 YangInstanceIdentifier.PathArgument serializePathArgument(@Nullable TreeArgument<?> arg);
145 * Deserializes path argument for current node.
148 * - Yang Path Argument, may be null if Yang Instance Identifier
149 * does not have representation for current node (e.g. case)
150 * @return Binding Path Argument, may be null if Binding Instance Identifier
151 * does not have representation for current node (e.g. choice or
153 * @throws IllegalArgumentException
154 * - if supplied {@code arg} is not valid.
157 TreeArgument<?> deserializePathArgument(@Nullable YangInstanceIdentifier.PathArgument arg);
160 * Return schema of node codec context.
162 * @return {@link Object} as schema of specific node context