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;
12 * Event Stream Writer for Binding Representation
15 * <h3>Emmiting Event Stream</h3>
18 * <li><code>container</code> - Container node representation, start event is
19 * emitted using {@link #startContainerNode(Class, int)} and node end event is
20 * emitted using {@link #endNode()}. Container node is implementing
21 * {@link DataObject} interface.
23 * <li><code>list</code> - YANG list statement has two representation in event
24 * stream - unkeyed list and map. Unkeyed list is YANG list which did not
28 * <li><code>Map</code> - Map start event is emitted using
29 * {@link #startMapNode(Class, int)} and is ended using {@link #endNode()}. Each map
30 * entry start is emitted using {@link #startMapEntryNode(Identifier, int)} with Map of keys
31 * and finished using {@link #endNode()}.</li>
33 * <li><code>UnkeyedList</code> - Unkeyed list represent list without keys,
34 * unkeyed list start is emmited using {@link #startUnkeyedList(Class, int)} list
35 * end is emmited using {@link #endNode()}. Each list item is emmited using
36 * {@link #startUnkeyedListItem()} and ended using {@link #endNode()}.</li>
39 * <li><code>leaf</code> - Leaf node event is emitted using
40 * {@link #leafNode(String, Object)}. {@link #endNode()} MUST be not emmited for
43 * <li><code>leaf-list</code> - Leaf list start is emitted using
44 * {@link #startLeafSet(String, int)}. Leaf list end is emitted using
45 * {@link #endNode()}. Leaf list entries are emmited using
46 * {@link #leafSetEntryNode(Object).
48 * <li><code>anyxml - Anyxml node event is emitted using
49 * {@link #leafNode(String, Object)}. {@link #endNode()} MUST be not emmited
50 * for anyxml node.</code></li>
53 * <li><code>choice</code> Choice node event is emmited by
54 * {@link #startChoiceNode(Class, int)} event and must be immediately followed by
55 * {@link #startCase(Class, int)} event. Choice node is finished by emitting
56 * {@link #endNode()} event.</li>
59 * <code>case</code> - Case node may be emitted only inside choice node by
60 * invoking {@link #startCase(Class, int)}. Case node is finished be emitting
61 * {@link #endNode()} event.</li>
64 * <code>augment</code> - Represents augmentation, augmentation node is started
65 * by invoking {@link #startAugmentationNode(Class)} and
66 * finished by invoking {@link #endNode()}.</li>
70 * <h3>Implementation notes</h3> This interface is not intended to be
71 * implemented by users of generated Binding DTOs but to be used by utilities,
72 * which needs to emit NormalizedNode model from Binding DTOs.
74 * This interface is intended as API definition of facade for real Event /
75 * Stream Writer, without explicitly requiring stream writer and related
76 * interfaces to be imported by all generated Binding DTOs.
78 * Existence of this interface in base Java Binding package is required to
79 * support runtime generation of users of this interface in OSGI and OSGI-like
80 * environment, since this package is only package which is imported by all
81 * generated Binding DTOs and wired in OSGI.
85 public interface BindingStreamEventWriter {
88 * Methods in this interface allow users to hint the underlying
89 * implementation about the sizing of container-like constructurs
90 * (leafLists, containers, etc.). These hints may be taken into account by a
91 * particular implementation to improve performance, but clients are not
92 * required to provide hints. This constant should be used by clients who
93 * either do not have the sizing information, or do not wish to divulge it
94 * (for whatever reasons). Implementations are free to ignore these hints
95 * completely, but if they do use them, they are expected to be resilient in
96 * face of missing and mismatched hints, which is to say the user can
97 * specify startLeafSet(..., 1) and then call leafNode() 15 times.
99 * The acceptable hint values are non-negative integers and this constant,
100 * all other values will result, based on implementation preference, in the
101 * hint being completely ignored or IllegalArgumentException being thrown.
103 public final int UNKNOWN_SIZE = -1;
107 * Emits a leaf node event with supplied value.
110 * name of node as defined in schema, namespace and revision are
111 * derived from parent node.
113 * Value of leaf node.
114 * @throws IllegalArgumentException
115 * If emitted leaf node has invalid value in current context or
116 * was emitted multiple times.
117 * @throws IllegalStateException
118 * If node was emitted inside <code>map</code>,
119 * <code>choice</code> <code>unkeyed list</code> node.
121 void leafNode(String localName, Object value) throws IllegalArgumentException;
125 * Emits a start of leaf set (leaf-list).
127 * Emits start of leaf set, during writing leaf set event, only
128 * {@link #leafSetEntryNode(Object)} calls are valid. Leaf set event is
129 * finished by calling {@link #endNode()}.
132 * name of node as defined in schema, namespace and revision are
133 * derived from parent node.
134 * @param childSizeHint
135 * Non-negative count of expected direct child nodes or
136 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
137 * and should not fail writing of child events, if there are more
139 * @throws IllegalArgumentException
140 * If emitted leaf node is invalid in current context or was
141 * emitted multiple times.
142 * @throws IllegalStateException
143 * If node was emitted inside <code>map</code>,
144 * <code>choice</code> <code>unkeyed list</code> node.
146 void startLeafSet(String localName, int childSizeHint) throws IllegalArgumentException;
149 * Emits a leaf set entry node
152 * Value of leaf set entry node.
153 * @throws IllegalArgumentException
154 * If emitted leaf node has invalid value.
155 * @throws IllegalStateException
156 * If node was emitted outside <code>leaf set</code> node.
158 void leafSetEntryNode(Object value) throws IllegalArgumentException;
162 * Emits start of new container.
165 * End of container event is emitted by invoking {@link #endNode()}.
168 * Valid sub-events are:
170 * <li>{@link #leafNode(String, Object)}</li>
171 * <li>{@link #startContainerNode(Class, int)}</li>
172 * <li>{@link #startChoiceNode(Class, int)}</li>
173 * <li>{@link #startLeafSet(String, int)}</li>
174 * <li>{@link #startMapNode(Class, int)}</li>
175 * <li>{@link #startUnkeyedList(Class, int)}</li>
176 * <li>{@link #startAugmentationNode(Class)}</li>
180 * name of node as defined in schema, namespace and revision are
181 * derived from parent node.
182 * @param childSizeHint
183 * Non-negative count of expected direct child nodes or
184 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
185 * and should not fail writing of child events, if there are more
187 * @throws IllegalArgumentException
188 * If emitted node is invalid in current context or was emitted
190 * @throws IllegalStateException
191 * If node was emitted inside <code>map</code>,
192 * <code>choice</code> <code>unkeyed list</code> node.
194 void startContainerNode(Class<? extends DataObject> container, int childSizeHint) throws IllegalArgumentException;
198 * Emits start of unkeyed list node event.
201 * End of unkeyed list event is emitted by invoking {@link #endNode()}.
202 * Valid subevents is only {@link #startUnkeyedListItem()}. All other
203 * methods will throw {@link IllegalArgumentException}.
206 * name of node as defined in schema, namespace and revision are
207 * derived from parent node.
208 * @param childSizeHint
209 * Non-negative count of expected direct child nodes or
210 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
211 * and should not fail writing of child events, if there are more
213 * @throws IllegalArgumentException
214 * If emitted node is invalid in current context or was emitted
216 * @throws IllegalStateException
217 * If node was emitted inside <code>map</code>,
218 * <code>choice</code> <code>unkeyed list</code> node.
220 void startUnkeyedList(Class<? extends DataObject> localName, int childSizeHint) throws IllegalArgumentException;
223 * Emits start of new unkeyed list item.
226 * Unkeyed list item event is finished by invoking {@link #endNode()}. Valid
229 * Valid sub-events are:
232 * <li>{@link #leafNode(String, Object)}</li>
233 * <li>{@link #startContainerNode(Class, int)}</li>
234 * <li>{@link #startChoiceNode(Class, int)}</li>
235 * <li>{@link #startLeafSet(String, int)}</li>
236 * <li>{@link #startMapNode(Class, int)}</li>
237 * <li>{@link #startUnkeyedList(Class, int)}</li>
238 * <li>{@link #startAugmentationNode(Class)}</li>
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 IllegalStateException
248 * If node was emitted outside <code>unkeyed list</code> node.
250 void startUnkeyedListItem(int childSizeHint) throws IllegalStateException;
254 * Emits start of unordered map node event.
257 * End of map node event is emitted by invoking {@link #endNode()}. Valid
258 * subevents is only {@link #startMapEntryNode(Identifier, int)}. All other methods will
259 * throw {@link IllegalArgumentException}.
261 * @param mapEntryType
262 * Class of list item, which has defined key.
263 * @param childSizeHint
264 * Non-negative count of expected direct child nodes or
265 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
266 * and should not fail writing of child events, if there are more
268 * @throws IllegalArgumentException
269 * @throws IllegalStateException
270 * If node was emitted inside <code>map</code>,
271 * <code>choice</code> <code>unkeyed list</code> node.
273 <T extends DataObject & Identifiable<?>> void startMapNode(Class<T> mapEntryType, int childSizeHint)
274 throws IllegalArgumentException;
279 * Emits start of ordered map node event.
282 * End of map node event is emitted by invoking {@link #endNode()}. Valid
283 * subevents is only {@link #startMapEntryNode(Identifier, int)}. All other methods will
284 * throw {@link IllegalArgumentException}.
286 * @param mapEntryType
287 * Class of list item, which has defined key.
288 * @param childSizeHint
289 * Non-negative count of expected direct child nodes or
290 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
291 * and should not fail writing of child events, if there are more
293 * @throws IllegalArgumentException
294 * @throws IllegalStateException
295 * If node was emitted inside <code>map</code>,
296 * <code>choice</code> <code>unkeyed list</code> node.
298 <T extends DataObject & Identifiable<?>> void startOrderedMapNode(Class<T> mapEntryType, int childSizeHint)
299 throws IllegalArgumentException;
303 * Emits start of map entry.
306 * End of map entry event is emitted by invoking {@link #endNode()}.
309 * Valid sub-events are:
311 * Valid sub-events are:
313 * <li>{@link #leafNode(String, Object)}</li>
314 * <li>{@link #startContainerNode(Class, int)}</li>
315 * <li>{@link #startChoiceNode(Class, int)}</li>
316 * <li>{@link #startLeafSet(String, int)}</li>
317 * <li>{@link #startMapNode(Class, int)}</li>
318 * <li>{@link #startUnkeyedList(Class, int)}</li>
319 * <li>{@link #startAugmentationNode(Class)}</li>
323 * Key of map entry node
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 * If key contains incorrect value.
331 * @throws IllegalStateException
332 * If node was emitted outside <code>map entry</code> node.
334 void startMapEntryNode(Identifier<?> keyValues, int childSizeHint) throws IllegalArgumentException;
337 * Emits start of choice node.
340 * Valid sub-event in {@link #startCase(QName, int)}, which selects case
341 * which should be written.
345 * name of node as defined in schema, namespace and revision are
346 * derived from parent node.
347 * @param childSizeHint
348 * Non-negative count of expected direct child nodes or
349 * {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
350 * and should not fail writing of child events, if there are more
352 * @throws IllegalArgumentException
353 * @throws IllegalStateException
354 * If node was emitted inside <code>map</code>, <code>choice
355 * </code> <code>unkeyed list</code> node.
357 void startChoiceNode(Class<? extends DataContainer> choice, int childSizeHint) throws IllegalArgumentException;
361 * Starts a case node.
364 * Valid sub-events are:
366 * <li>{@link #leafNode(String, Object)}</li>
367 * <li>{@link #startContainerNode(Class, int)}</li>
368 * <li>{@link #startChoiceNode(Class, int)}</li>
369 * <li>{@link #startLeafSet(String, int)}</li>
370 * <li>{@link #startMapNode(Class, int)}</li>
371 * <li>{@link #startUnkeyedList(Class, int)}</li>
372 * <li>{@link #startAugmentationNode(Class)}</li>
376 * @throws IllegalArgumentException
378 void startCase(Class<? extends DataObject> caze, int childSizeHint) throws IllegalArgumentException;
381 * Emits start of augmentation node.
384 * End of augmentation event is emitted by invoking {@link #endNode()}.
387 * Valid sub-events are:
390 * Valid sub-events are:
392 * <li>{@link #leafNode(String, Object)}</li>
393 * <li>{@link #startContainerNode(Class, int)}</li>
394 * <li>{@link #startChoiceNode(Class, int)}</li>
395 * <li>{@link #startLeafSet(String, int)}</li>
396 * <li>{@link #startMapNode(Class, int)}</li>
397 * <li>{@link #startUnkeyedList(Class, int)}</li>
401 * Note this is only method, which does not require childSizeHint, since
402 * maximum value is always size of <code>possibleChildren</code>.
405 * QName module of YANG module in which augmentation was defined
406 * @param possibleChildren
407 * Local names of all valid children defined by augmentation.
408 * @throws IllegalArgumentException
409 * If augmentation is invalid in current context.
411 void startAugmentationNode(Class<? extends Augmentation<?>> augmentationType) throws IllegalArgumentException;
414 * Emits anyxml node event.
418 * @throws IllegalArgumentException
419 * @throws IllegalStateException
420 * If node was emitted inside <code>map</code>,
421 * <code>choice</code> <code>unkeyed list</code> node.
423 void anyxmlNode(String name, Object value) throws IllegalArgumentException;
426 * Emits end event for node.
428 * @throws IllegalStateException If there is no open node.
430 void endNode() throws IllegalStateException;