3 * Copyright (c) 2014 Cisco Systems, Inc. and others. All rights reserved.
5 * This program and the accompanying materials are made available under the
6 * terms of the Eclipse Public License v1.0 which accompanies this distribution,
7 * and is available at http://www.eclipse.org/legal/epl-v10.html
10 package org.opendaylight.controller.cluster.datastore.node.utils.stream;
12 import java.io.Closeable;
13 import java.io.Flushable;
14 import java.io.IOException;
16 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
19 * Event Stream Writer based on Normalized Node tree representation
21 * <h3>Writing Event Stream</h3>
24 * <li><code>container</code> - Container node representation, start event is
25 * emitted using {@link #startContainerNode(YangInstanceIdentifier.NodeIdentifier, int)}
26 * and node end event is
27 * emitted using {@link #endNode()}. Container node is implementing
28 * {@link org.opendaylight.yangtools.yang.binding.DataObject} interface.
30 * <li><code>list</code> - YANG list statement has two representation in event
31 * stream - unkeyed list and map. Unkeyed list is YANG list which did not
35 * <li><code>Map</code> - Map start event is emitted using
36 * {@link #startMapNode(YangInstanceIdentifier.NodeIdentifier, int)}
37 * and is ended using {@link #endNode()}. Each map entry start is emitted using
38 * {@link #startMapEntryNode(YangInstanceIdentifier.NodeIdentifierWithPredicates, int)}
40 * and finished using {@link #endNode()}.</li>
42 * <li><code>UnkeyedList</code> - Unkeyed list represent list without keys,
43 * unkeyed list start is emitted using
44 * {@link #startUnkeyedList(YangInstanceIdentifier.NodeIdentifier, int)} list
45 * end is emitted using {@link #endNode()}. Each list item is emitted using
46 * {@link #startUnkeyedListItem(YangInstanceIdentifier.NodeIdentifier, int)}
47 * and ended using {@link #endNode()}.</li>
50 * <li><code>leaf</code> - Leaf node event is emitted using
51 * {@link #leafNode(YangInstanceIdentifier.NodeIdentifier, Object)}.
52 * {@link #endNode()} MUST NOT BE emitted for
55 * <li><code>leaf-list</code> - Leaf list start is emitted using
56 * {@link #startLeafSet(YangInstanceIdentifier.NodeIdentifier, int)}.
57 * Leaf list end is emitted using
58 * {@link #endNode()}. Leaf list entries are emitted using
59 * {@link #leafSetEntryNode(YangInstanceIdentifier.NodeWithValue name, Object).
61 * <li><code>anyxml - Anyxml node event is emitted using
62 * {@link #leafNode(YangInstanceIdentifier.NodeIdentifier, Object)}. {@link #endNode()} MUST NOT BE emitted
63 * for anyxml node.</code></li>
66 * <li><code>choice</code> Choice node event is emmited by
67 * {@link #startChoiceNode(YangInstanceIdentifier.NodeIdentifier, int)} event and
68 * finished by invoking {@link #endNode()}
70 * <code>augment</code> - Represents augmentation, augmentation node is started
71 * by invoking {@link #startAugmentationNode(YangInstanceIdentifier.AugmentationIdentifier)} and
72 * finished by invoking {@link #endNode()}.</li>
76 * <h3>Implementation notes</h3>
79 * Implementations of this interface must not hold user suppled objects
80 * and resources needlessly.
84 public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
86 public final int UNKNOWN_SIZE = -1;
89 * Write the leaf node identifier and value to the stream.
93 * @throws IllegalArgumentException
95 void leafNode(YangInstanceIdentifier.NodeIdentifier name, Object value)
96 throws IOException, IllegalArgumentException;
99 * Start writing leaf Set node. You must call {@link #endNode()} once you are done writing all of its children.
101 * @param childSizeHint is the estimated children count. Usage is optional in implementation.
102 * @throws IOException
103 * @throws IllegalArgumentException
105 void startLeafSet(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
106 throws IOException, IllegalArgumentException;
109 * Write the leaf Set Entry Node object to the stream with identifier and value.
112 * @throws IOException
113 * @throws IllegalArgumentException
115 void leafSetEntryNode(YangInstanceIdentifier.NodeWithValue name, Object value)
116 throws IOException, IllegalArgumentException;
119 * Start writing container node. You must call {@link #endNode()} once you are done writing all of its children.
121 * @param childSizeHint is the estimated children count. Usage is optional in implementation.
122 * @throws IOException
123 * @throws IllegalArgumentException
125 void startContainerNode(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
126 throws IOException, IllegalArgumentException;
129 * Start writing unkeyed list node. You must call {@link #endNode()} once you are done writing all of its children.
131 * @param childSizeHint is the estimated children count. Usage is optional in implementation.
132 * @throws IOException
133 * @throws IllegalArgumentException
135 void startUnkeyedList(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
136 throws IOException, IllegalArgumentException;
139 * Start writing unkeyed list item. You must call {@link #endNode()} once you are done writing all of its children.
141 * @param childSizeHint is the estimated children count. Usage is optional in implementation.
142 * @throws IOException
143 * @throws IllegalStateException
145 void startUnkeyedListItem(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
146 throws IOException, IllegalStateException;
149 * Start writing map node. You must call {@link #endNode()} once you are done writing all of its children.
151 * @param childSizeHint is the estimated children count. Usage is optional in implementation.
152 * @throws IOException
153 * @throws IllegalArgumentException
155 void startMapNode(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
156 throws IOException, IllegalArgumentException;
159 * Start writing map entry node. You must call {@link #endNode()} once you are done writing all of its children.
161 * @param childSizeHint is the estimated children count. Usage is optional in implementation.
162 * @throws IOException
163 * @throws IllegalArgumentException
165 void startMapEntryNode(YangInstanceIdentifier.NodeIdentifierWithPredicates identifier, int childSizeHint)
166 throws IOException, IllegalArgumentException;
169 * Start writing ordered map node. You must call {@link #endNode()} once you are done writing all of its children.
171 * @param childSizeHint is the estimated children count. Usage is optional in implementation.
172 * @throws IOException
173 * @throws IllegalArgumentException
175 void startOrderedMapNode(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
176 throws IOException, IllegalArgumentException;
179 * Start writing choice node. You must call {@link #endNode()} once you are done writing all of its children.
181 * @param childSizeHint is the estimated children count. Usage is optional in implementation.
182 * @throws IOException
183 * @throws IllegalArgumentException
185 void startChoiceNode(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
186 throws IOException, IllegalArgumentException;
189 * Start writing augmentation node. You must call {@link #endNode()} once you are done writing all of its children.
191 * @throws IOException
192 * @throws IllegalArgumentException
194 void startAugmentationNode(YangInstanceIdentifier.AugmentationIdentifier identifier)
195 throws IOException, IllegalArgumentException;
198 * Write any xml node identifier and value to the stream
201 * @throws IOException
202 * @throws IllegalArgumentException
204 void anyxmlNode(YangInstanceIdentifier.NodeIdentifier name, Object value)
205 throws IOException, IllegalArgumentException;
208 * This method should be used to add end symbol/identifier of node in the stream.
209 * @throws IOException
210 * @throws IllegalStateException
212 void endNode() throws IOException, IllegalStateException;
215 void close() throws IOException;
218 void flush() throws IOException;