Revert "Revert "Bug 3874: Support of yang modeled AnyXML - API""

[yangtools.git] / yang / yang-data-api / src / main / java / org / opendaylight / yangtools / yang / data / api / schema / stream / NormalizedNodeStreamWriter.java

diff --git a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/stream/NormalizedNodeStreamWriter.java b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/stream/NormalizedNodeStreamWriter.java
index 94b5ba69e57457ef0c503468ebd08063ed384e24..983378703e57f72694db34748f7011b008484fd6 100644 (file)
--- a/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/stream/NormalizedNodeStreamWriter.java
+++ b/yang/yang-data-api/src/main/java/org/opendaylight/yangtools/yang/data/api/schema/stream/NormalizedNodeStreamWriter.java
@@ -10,7 +10,6 @@ package org.opendaylight.yangtools.yang.data.api.schema.stream;
 import java.io.Closeable;
 import java.io.Flushable;
 import java.io.IOException;
-
 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.AugmentationIdentifier;
 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier;
 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifierWithPredicates;
@@ -92,7 +91,7 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      * all other values will result, based on implementation preference, in the
      * hint being completely ignored or IllegalArgumentException being thrown.
      */
-    public final int UNKNOWN_SIZE = -1;
+    int UNKNOWN_SIZE = -1;
 
     /**
      *
@@ -111,7 +110,7 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *             <code>choice</code> <code>unkeyed list</code> node.
      * @throws IOException if an underlying IO error occurs
      */
-    void leafNode(NodeIdentifier name, Object value) throws IOException, IllegalArgumentException;
+    void leafNode(NodeIdentifier name, Object value) throws IOException;
 
     /**
      *
@@ -137,7 +136,7 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *             <code>choice</code> <code>unkeyed list</code> node.
      * @throws IOException if an underlying IO error occurs
      */
-    void startLeafSet(NodeIdentifier name, int childSizeHint) throws IOException, IllegalArgumentException;
+    void startLeafSet(NodeIdentifier name, int childSizeHint) throws IOException;
 
     /**
      * Emits a leaf set entry node
@@ -150,7 +149,7 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *             If node was emitted outside <code>leaf set</code> node.
      * @throws IOException if an underlying IO error occurs
      */
-    void leafSetEntryNode(Object value) throws IOException, IllegalArgumentException;
+    void leafSetEntryNode(Object value) throws IOException;
 
     /**
      *
@@ -187,7 +186,7 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *             <code>choice</code> <code>unkeyed list</code> node.
      * @throws IOException if an underlying IO error occurs
      */
-    void startContainerNode(NodeIdentifier name, int childSizeHint) throws IOException, IllegalArgumentException;
+    void startContainerNode(NodeIdentifier name, int childSizeHint) throws IOException;
 
     /**
      *
@@ -214,7 +213,7 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *             <code>choice</code> <code>unkeyed list</code> node.
      * @throws IOException if an underlying IO error occurs
      */
-    void startUnkeyedList(NodeIdentifier name, int childSizeHint) throws IOException, IllegalArgumentException;
+    void startUnkeyedList(NodeIdentifier name, int childSizeHint) throws IOException;
 
     /**
      * Emits start of new unkeyed list item.
@@ -242,7 +241,7 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *             If node was emitted outside <code>unkeyed list</code> node.
      * @throws IOException if an underlying IO error occurs
      */
-    void startUnkeyedListItem(NodeIdentifier name, int childSizeHint) throws IOException, IllegalStateException;
+    void startUnkeyedListItem(NodeIdentifier name, int childSizeHint) throws IOException;
 
     /**
      *
@@ -258,13 +257,19 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *            name of node as defined in schema, namespace and revision are
      *            derived from parent node.
      * @param childSizeHint
+     *            Non-negative count of expected direct child nodes or
+     *            {@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
+     *             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 if an underlying IO error occurs
      */
-    void startMapNode(NodeIdentifier name, int childSizeHint) throws IOException, IllegalArgumentException;
+    void startMapNode(NodeIdentifier name, int childSizeHint) throws IOException;
 
     /**
      *
@@ -288,13 +293,18 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *
      * @param identifier
      *            QName to value pairs of keys of map entry node. Values  MUST BE constant over time.
+     * @param childSizeHint
+     *            Non-negative count of expected direct child nodes or
+     *            {@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
      *             If key contains incorrect value.
      * @throws IllegalStateException
      *             If node was emitted outside <code>map entry</code> node.
      * @throws IOException if an underlying IO error occurs
      */
-    void startMapEntryNode(NodeIdentifierWithPredicates identifier, int childSizeHint) throws IOException, IllegalArgumentException;
+    void startMapEntryNode(NodeIdentifierWithPredicates identifier, int childSizeHint) throws IOException;
 
     /**
      *
@@ -309,13 +319,20 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      * @param name
      *            name of node as defined in schema, namespace and revision are
      *            derived from parent node.
+     * @param childSizeHint
+     *            Non-negative count of expected direct child nodes or
+     *            {@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
+     *             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 if an underlying IO error occurs
      */
-    void startOrderedMapNode(NodeIdentifier name, int childSizeHint) throws IOException, IllegalArgumentException;
+    void startOrderedMapNode(NodeIdentifier name, int childSizeHint) throws IOException;
 
     /**
      *
@@ -325,13 +342,19 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *            name of node as defined in schema, namespace and revision are
      *            derived from parent node.
      * @param childSizeHint
+     *            Non-negative count of expected direct child nodes or
+     *            {@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
+     *             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 if an underlying IO error occurs
      */
-    void startChoiceNode(NodeIdentifier name, int childSizeHint) throws IOException, IllegalArgumentException;
+    void startChoiceNode(NodeIdentifier name, int childSizeHint) throws IOException;
 
     /**
      * Emits start of augmentation node.
@@ -357,20 +380,60 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      *             If augmentation is invalid in current context.
      * @throws IOException if an underlying IO error occurs
      */
-    void startAugmentationNode(AugmentationIdentifier identifier) throws IOException, IllegalArgumentException;
+    void startAugmentationNode(AugmentationIdentifier identifier) throws IOException;
 
     /**
      * Emits anyxml node event.
      *
      * @param name
+     *            name of node as defined in schema, namespace and revision are
+     *            derived from parent node.
      * @param value
+     *             Value of AnyXml node.
      * @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 if an underlying IO error occurs
      */
-    void anyxmlNode(NodeIdentifier name, Object value) throws IOException, IllegalArgumentException;
+    void anyxmlNode(NodeIdentifier name, Object value) throws IOException;
+
+    /**
+    *
+    * Emits start of new yang modeled anyXml node.
+    *
+    * <p>
+    * End of yang modeled anyXml node event is emitted by invoking {@link #endNode()}.
+    *
+    * <p>
+    * Valid sub-events are:
+    * <ul>
+    * <li>{@link #leafNode}</li>
+    * <li>{@link #startContainerNode}</li>
+    * <li>{@link #startLeafSet}</li>
+    * <li>{@link #startMapNode}</li>
+    * <li>{@link #startUnkeyedList}</li>
+    * </ul>
+    *
+    * @param name
+    *            name of node as defined in schema, namespace and revision are
+    *            derived from parent node.
+    * @param childSizeHint
+    *            Non-negative count of expected direct child nodes or
+    *            {@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
+    *             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 if an underlying IO error occurs
+    */
+    void startYangModeledAnyXmlNode(NodeIdentifier name, int childSizeHint) throws IOException;
 
     /**
      * Emits end event for node.
@@ -378,7 +441,7 @@ public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
      * @throws IllegalStateException If there is no start* event to be closed.
      * @throws IOException if an underlying IO error occurs
      */
-    void endNode() throws IOException, IllegalStateException;
+    void endNode() throws IOException;
 
     @Override
     void close() throws IOException;