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.yangtools.yang.binding;
10 import java.io.Closeable;
11 import java.io.Flushable;
12 import java.io.IOException;
16 * Event Stream Writer for Binding Representation
19 * <h3>Emmiting Event Stream</h3>
22 * <li><code>container</code> - Container node representation, start event is
23 * emitted using {@link #startContainerNode(Class, int)} and node end event is
24 * emitted using {@link #endNode()}. Container node is implementing
25 * {@link DataObject} interface.
27 * <li><code>list</code> - YANG list statement has two representation in event
28 * stream - unkeyed list and map. Unkeyed list is YANG list which did not
32 * <li><code>Map</code> - Map start event is emitted using
33 * {@link #startMapNode(Class, int)} and is ended using {@link #endNode()}. Each map
34 * entry start is emitted using {@link #startMapEntryNode(Identifier, int)} with Map of keys
35 * and finished using {@link #endNode()}.</li>
37 * <li><code>UnkeyedList</code> - Unkeyed list represent list without keys,
38 * unkeyed list start is emitted using {@link #startUnkeyedList(Class, int)} list
39 * end is emitted using {@link #endNode()}. Each list item is emitted using
40 * {@link #startUnkeyedListItem(int)} and ended using {@link #endNode()}.</li>
43 * <li><code>leaf</code> - Leaf node event is emitted using
44 * {@link #leafNode(String, Object)}. {@link #endNode()} MUST be not emitted for
47 * <li><code>leaf-list</code> - Leaf list start is emitted using
48 * {@link #startLeafSet(String, int)}. Leaf list end is emitted using
49 * {@link #endNode()}. Leaf list entries are emitted using
50 * {@link #leafSetEntryNode(Object)}.
52 * <li><code>anyxml - Anyxml node event is emitted using
53 * {@link #leafNode(String, Object)}. {@link #endNode()} MUST be not emitted
54 * for anyxml node.</code></li>
57 * <li><code>choice</code> Choice node event is emitted by
58 * {@link #startChoiceNode(Class, int)} event and must be immediately followed by
59 * {@link #startCase(Class, int)} event. Choice node is finished by emitting an
60 * {@link #endNode()} event.</li>
63 * <code>case</code> - Case node may be emitted only inside choice node by
64 * invoking {@link #startCase(Class, int)}. Case node is finished be emitting an
65 * {@link #endNode()} event.</li>
68 * <code>augment</code> - Represents augmentation, augmentation node is started
69 * by invoking {@link #startAugmentationNode(Class)} and
70 * finished by invoking {@link #endNode()}.</li>
74 * <h3>Implementation notes</h3> This interface is not intended to be
75 * implemented by users of generated Binding DTOs but to be used by utilities,
76 * which needs to emit NormalizedNode model from Binding DTOs.
78 * This interface is intended as API definition of facade for real Event /
79 * Stream Writer, without explicitly requiring stream writer and related
80 * interfaces to be imported by all generated Binding DTOs.
82 * Existence of this interface in base Java Binding package is required to
83 * support runtime generation of users of this interface in OSGI and OSGI-like
84 * environment, since this package is only package which is imported by all
85 * generated Binding DTOs and wired in OSGI.
89 public interface BindingStreamEventWriter extends Closeable, Flushable {
92 * Methods in this interface allow users to hint the underlying
93 * implementation about the sizing of container-like constructors
94 * (leafLists, containers, etc.). These hints may be taken into account by a
95 * particular implementation to improve performance, but clients are not
96 * required to provide hints. This constant should be used by clients who
97 * either do not have the sizing information, or do not wish to divulge it
98 * (for whatever reasons). Implementations are free to ignore these hints
99 * completely, but if they do use them, they are expected to be resilient in
100 * face of missing and mismatched hints, which is to say the user can
101 * specify startLeafSet(..., 1) and then call leafNode() 15 times.
103 * The acceptable hint values are non-negative integers and this constant,
104 * all other values will result, based on implementation preference, in the
105 * hint being completely ignored or IllegalArgumentException being thrown.
107 int UNKNOWN_SIZE = -1;
111 * Emits a leaf node event with supplied value.
114 * name of node as defined in schema, namespace and revision are
115 * derived from parent node.
117 * Value of leaf node.
118 * @throws IllegalArgumentException
119 * If emitted leaf node has invalid value in current context or
120 * was emitted multiple times.
121 * @throws IllegalStateException
122 * If node was emitted inside <code>map</code>,
123 * <code>choice</code> <code>unkeyed list</code> node.
124 * @throws IOException if an underlying IO error occurs
126 void leafNode(String localName, Object value) throws IOException;
130 * Emits a start of leaf set (leaf-list).
132 * Emits start of leaf set, during writing leaf set event, only
133 * {@link #leafSetEntryNode(Object)} calls are valid. Leaf set event is
134 * finished by calling {@link #endNode()}.
137 * name of node as defined in schema, namespace and revision are
138 * derived from parent node.
139 * @param childSizeHint
140 * Non-negative count of expected direct child nodes or
141 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
142 * and should not fail writing of child events, if there are more
144 * @throws IllegalArgumentException
145 * If emitted leaf node is invalid in current context or was
146 * emitted multiple times.
147 * @throws IllegalStateException
148 * If node was emitted inside <code>map</code>,
149 * <code>choice</code> <code>unkeyed list</code> node.
150 * @throws IOException if an underlying IO error occurs
152 void startLeafSet(String localName, int childSizeHint) throws IOException;
156 * Emits a start of leaf set (leaf-list).
158 * Emits start of leaf set, during writing leaf set event, only
159 * {@link #leafSetEntryNode(Object)} calls are valid. Leaf set event is
160 * finished by calling {@link #endNode()}.
163 * name of node as defined in schema, namespace and revision are
164 * derived from parent node.
165 * @param childSizeHint
166 * Non-negative count of expected direct child nodes or
167 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
168 * and should not fail writing of child events, if there are more
170 * @throws IllegalArgumentException
171 * If emitted leaf node is invalid in current context or was
172 * emitted multiple times.
173 * @throws IllegalStateException
174 * If node was emitted inside <code>map</code>,
175 * <code>choice</code> <code>unkeyed list</code> node.
176 * @throws IOException if an underlying IO error occurs
178 void startOrderedLeafSet(String localName, int childSizeHint) throws IOException;
181 * Emits a leaf set entry node
184 * Value of leaf set entry node.
185 * @throws IllegalArgumentException
186 * If emitted leaf node has invalid value.
187 * @throws IllegalStateException
188 * If node was emitted outside <code>leaf set</code> node.
189 * @throws IOException if an underlying IO error occurs
191 void leafSetEntryNode(Object value) throws IOException;
195 * Emits start of new container.
198 * End of container event is emitted by invoking {@link #endNode()}.
201 * Valid sub-events are:
203 * <li>{@link #leafNode(String, Object)}</li>
204 * <li>{@link #startContainerNode(Class, int)}</li>
205 * <li>{@link #startChoiceNode(Class, int)}</li>
206 * <li>{@link #startLeafSet(String, int)}</li>
207 * <li>{@link #startMapNode(Class, int)}</li>
208 * <li>{@link #startUnkeyedList(Class, int)}</li>
209 * <li>{@link #startAugmentationNode(Class)}</li>
213 * name of node as defined in schema, namespace and revision are
214 * derived from parent node.
215 * @param childSizeHint
216 * Non-negative count of expected direct child nodes or
217 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
218 * and should not fail writing of child events, if there are more
220 * @throws IllegalArgumentException
221 * If emitted node is invalid in current context or was emitted
223 * @throws IllegalStateException
224 * If node was emitted inside <code>map</code>,
225 * <code>choice</code> <code>unkeyed list</code> node.
226 * @throws IOException if an underlying IO error occurs
228 void startContainerNode(Class<? extends DataObject> container, int childSizeHint) throws IOException;
232 * Emits start of unkeyed list node event.
235 * End of unkeyed list event is emitted by invoking {@link #endNode()}.
236 * Valid subevents is only {@link #startUnkeyedListItem(int)}. All other
237 * methods will throw {@link IllegalArgumentException}.
240 * name of node as defined in schema, namespace and revision are
241 * derived from parent node.
242 * @param childSizeHint
243 * Non-negative count of expected direct child nodes or
244 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
245 * and should not fail writing of child events, if there are more
247 * @throws IllegalArgumentException
248 * If emitted node is invalid in current context or was emitted
250 * @throws IllegalStateException
251 * If node was emitted inside <code>map</code>,
252 * <code>choice</code> <code>unkeyed list</code> node.
253 * @throws IOException if an underlying IO error occurs
255 void startUnkeyedList(Class<? extends DataObject> localName, int childSizeHint) throws IOException;
258 * Emits start of new unkeyed list item.
261 * Unkeyed list item event is finished by invoking {@link #endNode()}. Valid
264 * Valid sub-events are:
267 * <li>{@link #leafNode(String, Object)}</li>
268 * <li>{@link #startContainerNode(Class, int)}</li>
269 * <li>{@link #startChoiceNode(Class, int)}</li>
270 * <li>{@link #startLeafSet(String, int)}</li>
271 * <li>{@link #startMapNode(Class, int)}</li>
272 * <li>{@link #startUnkeyedList(Class, int)}</li>
273 * <li>{@link #startAugmentationNode(Class)}</li>
277 * @param childSizeHint
278 * Non-negative count of expected direct child nodes or
279 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
280 * and should not fail writing of child events, if there are more
282 * @throws IllegalStateException
283 * If node was emitted outside <code>unkeyed list</code> node.
284 * @throws IOException if an underlying IO error occurs
286 void startUnkeyedListItem(int childSizeHint) throws IOException;
290 * Emits start of unordered map node event.
293 * End of map node event is emitted by invoking {@link #endNode()}. Valid
294 * subevents is only {@link #startMapEntryNode(Identifier, int)}. All other methods will
295 * throw {@link IllegalArgumentException}.
297 * @param mapEntryType
298 * Class of list item, which has defined key.
299 * @param childSizeHint
300 * Non-negative count of expected direct child nodes or
301 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
302 * and should not fail writing of child events, if there are more
304 * @throws IllegalArgumentException
305 * @throws IllegalStateException
306 * If node was emitted inside <code>map</code>,
307 * <code>choice</code> <code>unkeyed list</code> node.
308 * @throws IOException if an underlying IO error occurs
310 <T extends DataObject & Identifiable<?>> void startMapNode(Class<T> mapEntryType, int childSizeHint)
315 * Emits start of ordered map node event.
318 * End of map node event is emitted by invoking {@link #endNode()}. Valid
319 * subevents is only {@link #startMapEntryNode(Identifier, int)}. All other methods will
320 * throw {@link IllegalArgumentException}.
322 * @param mapEntryType
323 * Class of list item, which has defined key.
324 * @param childSizeHint
325 * Non-negative count of expected direct child nodes or
326 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
327 * and should not fail writing of child events, if there are more
329 * @throws IllegalArgumentException
330 * @throws IllegalStateException
331 * If node was emitted inside <code>map</code>,
332 * <code>choice</code> <code>unkeyed list</code> node.
333 * @throws IOException if an underlying IO error occurs
335 <T extends DataObject & Identifiable<?>> void startOrderedMapNode(Class<T> mapEntryType, int childSizeHint)
340 * Emits start of map entry.
343 * End of map entry event is emitted by invoking {@link #endNode()}.
346 * Valid sub-events are:
348 * <li>{@link #leafNode(String, Object)}</li>
349 * <li>{@link #startContainerNode(Class, int)}</li>
350 * <li>{@link #startChoiceNode(Class, int)}</li>
351 * <li>{@link #startLeafSet(String, int)}</li>
352 * <li>{@link #startMapNode(Class, int)}</li>
353 * <li>{@link #startUnkeyedList(Class, int)}</li>
354 * <li>{@link #startAugmentationNode(Class)}</li>
358 * Key of map entry node
359 * @param childSizeHint
360 * Non-negative count of expected direct child nodes or
361 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
362 * and should not fail writing of child events, if there are more
364 * @throws IllegalArgumentException
365 * If key contains incorrect value.
366 * @throws IllegalStateException
367 * If node was emitted outside <code>map entry</code> node.
368 * @throws IOException if an underlying IO error occurs
370 void startMapEntryNode(Identifier<?> keyValues, int childSizeHint) throws IOException;
373 * Emits start of choice node.
376 * Valid sub-event in {@link #startCase(Class, int)}, which selects case
377 * which should be written.
381 * @param childSizeHint
382 * Non-negative count of expected direct child nodes or
383 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
384 * and should not fail writing of child events, if there are more
386 * @throws IllegalArgumentException
387 * @throws IllegalStateException
388 * If node was emitted inside <code>map</code>, <code>choice</code>,
389 * <code>unkeyed list</code> node.
390 * @throws IOException if an underlying IO error occurs
392 void startChoiceNode(Class<? extends DataContainer> choice, int childSizeHint) throws IOException;
396 * Starts a case node.
399 * Valid sub-events are:
401 * <li>{@link #leafNode(String, Object)}</li>
402 * <li>{@link #startContainerNode(Class, int)}</li>
403 * <li>{@link #startChoiceNode(Class, int)}</li>
404 * <li>{@link #startLeafSet(String, int)}</li>
405 * <li>{@link #startMapNode(Class, int)}</li>
406 * <li>{@link #startUnkeyedList(Class, int)}</li>
407 * <li>{@link #startAugmentationNode(Class)}</li>
410 * @param caze Case class
411 * @throws IllegalArgumentException
412 * @throws IOException if an underlying IO error occurs
414 void startCase(Class<? extends DataObject> caze, int childSizeHint) throws IOException;
417 * Emits start of augmentation node.
420 * End of augmentation event is emitted by invoking {@link #endNode()}.
423 * Valid sub-events are:
426 * <li>{@link #leafNode(String, Object)}</li>
427 * <li>{@link #startContainerNode(Class, int)}</li>
428 * <li>{@link #startChoiceNode(Class, int)}</li>
429 * <li>{@link #startLeafSet(String, int)}</li>
430 * <li>{@link #startMapNode(Class, int)}</li>
431 * <li>{@link #startUnkeyedList(Class, int)}</li>
435 * Note this is only method, which does not require childSizeHint, since
436 * maximum value is always size of <code>possibleChildren</code>.
438 * @param augmentationType augmentation class
439 * @throws IllegalArgumentException
440 * If augmentation is invalid in current context.
441 * @throws IOException if an underlying IO error occurs
443 void startAugmentationNode(Class<? extends Augmentation<?>> augmentationType) throws IOException;
446 * Emits anyxml node event.
450 * @throws IllegalArgumentException
451 * @throws IllegalStateException
452 * If node was emitted inside <code>map</code>,
453 * <code>choice</code> <code>unkeyed list</code> node.
454 * @throws IOException if an underlying IO error occurs
456 void anyxmlNode(String name, Object value) throws IOException;
459 * Emits end event for node.
461 * @throws IllegalStateException If there is no open node.
462 * @throws IOException if an underlying IO error occurs
464 void endNode() throws IOException;
466 void flush() throws IOException;
469 void close() throws IOException;