/**
- * Event Stream Writer for Binding Representation
- *
+ * Event Stream Writer for Binding Representation.
*
* <h3>Emmiting Event Stream</h3>
*
* {@link #startMapNode(Class, int)} and is ended using {@link #endNode()}. Each map
* entry start is emitted using {@link #startMapEntryNode(Identifier, int)} with Map of keys
* and finished using {@link #endNode()}.</li>
- *
* <li><code>UnkeyedList</code> - Unkeyed list represent list without keys,
* unkeyed list start is emitted using {@link #startUnkeyedList(Class, int)} list
* end is emitted using {@link #endNode()}. Each list item is emitted using
* {@link #startUnkeyedListItem(int)} and ended using {@link #endNode()}.</li>
* </ul></li>
- *
* <li><code>leaf</code> - Leaf node event is emitted using
* {@link #leafNode(String, Object)}. {@link #endNode()} MUST be not emitted for
* leaf node.</li>
- *
* <li><code>leaf-list</code> - Leaf list start is emitted using
* {@link #startLeafSet(String, int)}. Leaf list end is emitted using
* {@link #endNode()}. Leaf list entries are emitted using
* {@link #leafSetEntryNode(Object)}.
- *
* <li><code>anyxml - Anyxml node event is emitted using
* {@link #leafNode(String, Object)}. {@link #endNode()} MUST be not emitted
* for anyxml node.</code></li>
- *
- *
* <li><code>choice</code> Choice node event is emitted by
* {@link #startChoiceNode(Class, int)} event and must be immediately followed by
* {@link #startCase(Class, int)} event. Choice node is finished by emitting an
* {@link #endNode()} event.</li>
- *
* <li>
* <code>case</code> - Case node may be emitted only inside choice node by
* invoking {@link #startCase(Class, int)}. Case node is finished be emitting an
* {@link #endNode()} event.</li>
- *
* <li>
* <code>augment</code> - Represents augmentation, augmentation node is started
* by invoking {@link #startAugmentationNode(Class)} and
* finished by invoking {@link #endNode()}.</li>
- *
* </ul>
*
- * <h3>Implementation notes</h3> This interface is not intended to be
- * implemented by users of generated Binding DTOs but to be used by utilities,
- * which needs to emit NormalizedNode model from Binding DTOs.
- * <p>
- * This interface is intended as API definition of facade for real Event /
- * Stream Writer, without explicitly requiring stream writer and related
- * interfaces to be imported by all generated Binding DTOs.
- * <p>
- * Existence of this interface in base Java Binding package is required to
- * support runtime generation of users of this interface in OSGI and OSGI-like
- * environment, since this package is only package which is imported by all
- * generated Binding DTOs and wired in OSGI.
+ * <h3>Implementation notes</h3> This interface is not intended to be implemented by users of generated Binding DTOs
+ * but to be used by utilities, which needs to emit NormalizedNode model from Binding DTOs.
*
+ * <p>
+ * This interface is intended as API definition of facade for real Event / Stream Writer, without explicitly requiring
+ * stream writer and related interfaces to be imported by all generated Binding DTOs.
*
+ * <p>
+ * Existence of this interface in base Java Binding package is required to support runtime generation of users of this
+ * interface in OSGI and OSGI-like environment, since this package is only package which is imported by all generated
+ * Binding DTOs and wired in OSGI.
*/
public interface BindingStreamEventWriter extends Closeable, Flushable {
/**
- * Methods in this interface allow users to hint the underlying
- * implementation about the sizing of container-like constructors
- * (leafLists, containers, etc.). These hints may be taken into account by a
- * particular implementation to improve performance, but clients are not
- * required to provide hints. This constant should be used by clients who
- * either do not have the sizing information, or do not wish to divulge it
- * (for whatever reasons). Implementations are free to ignore these hints
- * completely, but if they do use them, they are expected to be resilient in
- * face of missing and mismatched hints, which is to say the user can
- * specify startLeafSet(..., 1) and then call leafNode() 15 times.
+ * Methods in this interface allow users to hint the underlying implementation about the sizing of container-like
+ * constructors (leafLists, containers, etc.). These hints may be taken into account by a particular implementation
+ * to improve performance, but clients are not required to provide hints. This constant should be used by clients
+ * who either do not have the sizing information, or do not wish to divulge it (for whatever reasons).
+ * Implementations are free to ignore these hints completely, but if they do use them, they are expected to be
+ * resilient in face of missing and mismatched hints, which is to say the user can specify startLeafSet(..., 1)
+ * and then call leafNode() 15 times.
+ *
* <p>
- * The acceptable hint values are non-negative integers and this constant,
- * all other values will result, based on implementation preference, in the
- * hint being completely ignored or IllegalArgumentException being thrown.
+ * The acceptable hint values are non-negative integers and this constant, all other values will result, based on
+ * implementation preference, in the hint being completely ignored or IllegalArgumentException being thrown.
*/
int UNKNOWN_SIZE = -1;
/**
- *
* Emits a leaf node event with supplied value.
*
* @param localName
void leafNode(String localName, Object value) throws IOException;
/**
- *
- * Emits a start of leaf set (leaf-list).
- * <p>
- * Emits start of leaf set, during writing leaf set event, only
- * {@link #leafSetEntryNode(Object)} calls are valid. Leaf set event is
- * finished by calling {@link #endNode()}.
+ * Emits a start of leaf set (leaf-list). Emits start of leaf set, during writing leaf set event, only
+ * {@link #leafSetEntryNode(Object)} calls are valid. Leaf set event is finished by calling {@link #endNode()}.
*
* @param localName
* name of node as defined in schema, namespace and revision are
void startLeafSet(String localName, int childSizeHint) throws IOException;
/**
- *
* Emits a start of leaf set (leaf-list).
+ *
* <p>
* Emits start of leaf set, during writing leaf set event, only
* {@link #leafSetEntryNode(Object)} calls are valid. Leaf set event is
void startOrderedLeafSet(String localName, int childSizeHint) throws IOException;
/**
- * Emits a leaf set entry node
+ * Emits a leaf set entry node.
*
* @param value
* Value of leaf set entry node.
void leafSetEntryNode(Object value) throws IOException;
/**
- *
- * Emits start of new container.
- *
- * <p>
- * End of container event is emitted by invoking {@link #endNode()}.
+ * Emits start of new container. End of container event is emitted by invoking {@link #endNode()}.
*
* <p>
* Valid sub-events are:
void startContainerNode(Class<? extends DataObject> container, int childSizeHint) throws IOException;
/**
- *
* Emits start of unkeyed list node event.
*
* <p>
* <p>
* Unkeyed list item event is finished by invoking {@link #endNode()}. Valid
* sub-events are:
- * <p>
- * Valid sub-events are:
- *
* <ul>
* <li>{@link #leafNode(String, Object)}</li>
* <li>{@link #startContainerNode(Class, int)}</li>
* <li>{@link #startAugmentationNode(Class)}</li>
* </ul>
*
- *
* @param childSizeHint
* Non-negative count of expected direct child nodes or
* {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
void startUnkeyedListItem(int childSizeHint) throws IOException;
/**
- *
* Emits start of unordered map node event.
*
* <p>
* End of map node event is emitted by invoking {@link #endNode()}. Valid
- * subevents is only {@link #startMapEntryNode(Identifier, int)}. All other methods will
+ * subevent is only {@link #startMapEntryNode(Identifier, int)}. All other methods will
* throw {@link IllegalArgumentException}.
*
* @param mapEntryType
* and should not fail writing of child events, if there are more
* events than count.
* @throws IllegalArgumentException
+ * If emitted node is invalid in current context or was emitted
+ * multiple times.
* @throws IllegalStateException
* If node was emitted inside <code>map</code>,
* <code>choice</code> <code>unkeyed list</code> node.
throws IOException;
/**
- *
* Emits start of ordered map node event.
*
* <p>
* End of map node event is emitted by invoking {@link #endNode()}. Valid
- * subevents is only {@link #startMapEntryNode(Identifier, int)}. All other methods will
+ * subevent is only {@link #startMapEntryNode(Identifier, int)}. All other methods will
* throw {@link IllegalArgumentException}.
*
* @param mapEntryType
* and should not fail writing of child events, if there are more
* events than count.
* @throws IllegalArgumentException
+ * If emitted node is invalid in current context or was emitted
+ * multiple times.
* @throws IllegalStateException
* If node was emitted inside <code>map</code>,
* <code>choice</code> <code>unkeyed list</code> node.
throws IOException;
/**
- *
* Emits start of map entry.
*
* <p>
* {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
* and should not fail writing of child events, if there are more
* events than count.
- * @throws IllegalArgumentException
* @throws IllegalStateException
* If node was emitted inside <code>map</code>, <code>choice</code>,
* <code>unkeyed list</code> node.
void startChoiceNode(Class<? extends DataContainer> choice, int childSizeHint) throws IOException;
/**
- *
* Starts a case node.
*
* <p>
* </ul>
*
* @param caze Case class
- * @throws IllegalArgumentException
* @throws IOException if an underlying IO error occurs
*/
void startCase(Class<? extends DataObject> caze, int childSizeHint) throws IOException;
/**
* Emits anyxml node event.
*
- * @param name
- * @param value
- * @throws IllegalArgumentException
+ * @param name node name
+ * @param value node value
* @throws IllegalStateException
* If node was emitted inside <code>map</code>,
* <code>choice</code> <code>unkeyed list</code> node.
* @throws IOException if an underlying IO error occurs
*/
void endNode() throws IOException;
+
@Override
void flush() throws IOException;
Code Review / mdsal.git / blobdiff