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

   1 /*
   2  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   3  *
   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
   7  */
   8 package org.opendaylight.yangtools.yang.data.api.schema.stream;
   9
  10 import java.io.Closeable;
  11 import java.io.Flushable;
  12 import java.io.IOException;
  13 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.AugmentationIdentifier;
  14 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifier;
  15 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier.NodeIdentifierWithPredicates;
  16
  17
  18 /**
  19  * Event Stream Writer based on Normalized Node tree representation
  20  *
  21  * <h3>Writing Event Stream</h3>
  22  *
  23  * <ul>
  24  * <li><code>container</code> - Container node representation, start event is
  25  * emitted using {@link #startContainerNode(NodeIdentifier, int)} and node end event is
  26  * emitted using {@link #endNode()}. Container node is implementing
  27  * the org.opendaylight.yangtools.yang.binding.DataObject interface.
  28  *
  29  * <li><code>list</code> - YANG list statement has two representation in event
  30  * stream - unkeyed list and map. Unkeyed list is YANG list which did not
  31  * specify key.
  32  *
  33  * <ul>
  34  * <li><code>Map</code> - Map start event is emitted using
  35  * {@link #startMapNode(NodeIdentifier, int)} and is ended using {@link #endNode()}. Each map
  36  * entry start is emitted using {@link #startMapEntryNode(NodeIdentifierWithPredicates, int)} with Map of keys
  37  * and finished using {@link #endNode()}.</li>
  38  *
  39  * <li><code>UnkeyedList</code> - Unkeyed list represent list without keys,
  40  * unkeyed list start is emitted using {@link #startUnkeyedList(NodeIdentifier, int)} list
  41  * end is emitted using {@link #endNode()}. Each list item is emitted using
  42  * {@link #startUnkeyedListItem(NodeIdentifier, int)} and ended using {@link #endNode()}.</li>
  43  * </ul></li>
  44  *
  45  * <li><code>leaf</code> - Leaf node event is emitted using
  46  * {@link #leafNode(NodeIdentifier, Object)}. {@link #endNode()} MUST NOT BE emitted for
  47  * leaf node.</li>
  48  *
  49  * <li><code>leaf-list</code> - Leaf list start is emitted using
  50  * {@link #startLeafSet(NodeIdentifier, int)}. Leaf list end is emitted using
  51  * {@link #endNode()}. Leaf list entries are emmited using
  52  * {@link #leafSetEntryNode(Object)}.
  53  *
  54  * <li><code>anyxml - AN node event is emitted using
  55  * {@link #leafNode(NodeIdentifier, Object)}. {@link #endNode()} MUST NOT BE emitted
  56  * for anyxml node.</code></li>
  57  *
  58  *
  59  * <li><code>choice</code> Choice node event is emmited by
  60  * {@link #startChoiceNode(NodeIdentifier, int)} event and
  61  * finished by invoking {@link #endNode()}
  62  * <li>
  63  * <code>augment</code> - Represents augmentation, augmentation node is started
  64  * by invoking {@link #startAugmentationNode(AugmentationIdentifier)} and
  65  * finished by invoking {@link #endNode()}.</li>
  66  *
  67  * </ul>
  68  *
  69  * <h3>Implementation notes</h3>
  70  *
  71  * <p>
  72  * Implementations of this interface must not hold user suppled objects
  73  * and resources needlessly.
  74  *
  75  */
  76 public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
  77
  78     /**
  79      * Methods in this interface allow users to hint the underlying
  80      * implementation about the sizing of container-like constructors
  81      * (leafLists, containers, etc.). These hints may be taken into account by a
  82      * particular implementation to improve performance, but clients are not
  83      * required to provide hints. This constant should be used by clients who
  84      * either do not have the sizing information, or do not wish to divulge it
  85      * (for whatever reasons). Implementations are free to ignore these hints
  86      * completely, but if they do use them, they are expected to be resilient in
  87      * face of missing and mismatched hints, which is to say the user can
  88      * specify startLeafSet(..., 1) and then call leafNode() 15 times.
  89      * <p>
  90      * The acceptable hint values are non-negative integers and this constant,
  91      * all other values will result, based on implementation preference, in the
  92      * hint being completely ignored or IllegalArgumentException being thrown.
  93      */
  94     int UNKNOWN_SIZE = -1;
  95
  96     /**
  97      *
  98      * Emits a leaf node event with supplied value.
  99      *
 100      * @param name
 101      *            name of node as defined in schema, namespace and revision are
 102      *            derived from parent node.
 103      * @param value
 104      *            Value of leaf node. v
 105      * @throws IllegalArgumentException
 106      *             If emitted leaf node has invalid value in current context or
 107      *             was emitted multiple times.
 108      * @throws IllegalStateException
 109      *             If node was emitted inside <code>map</code>,
 110      *             <code>choice</code> <code>unkeyed list</code> node.
 111      * @throws IOException if an underlying IO error occurs
 112      */
 113     void leafNode(NodeIdentifier name, Object value) throws IOException;
 114
 115     /**
 116      *
 117      * Emits a start of leaf set (leaf-list).
 118      * <p>
 119      * Emits start of leaf set, during writing leaf set event, only
 120      * {@link #leafSetEntryNode(Object)} calls are valid. Leaf set event is
 121      * finished by calling {@link #endNode()}.
 122      *
 123      * @param name
 124      *            name of node as defined in schema, namespace and revision are
 125      *            derived from parent node.
 126      * @param childSizeHint
 127      *            Non-negative count of expected direct child nodes or
 128      *            {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
 129      *            and should not fail writing of child events, if there are more
 130      *            events than count.
 131      * @throws IllegalArgumentException
 132      *             If emitted leaf node is invalid in current context or was
 133      *             emitted multiple times.
 134      * @throws IllegalStateException
 135      *             If node was emitted inside <code>map</code>,
 136      *             <code>choice</code> <code>unkeyed list</code> node.
 137      * @throws IOException if an underlying IO error occurs
 138      */
 139     void startLeafSet(NodeIdentifier name, int childSizeHint) throws IOException;
 140
 141     /**
 142      * Emits a leaf set entry node
 143      *
 144      * @param value
 145      *            Value of leaf set entry node. Supplied object MUST BE constant over time.
 146      * @throws IllegalArgumentException
 147      *             If emitted leaf node has invalid value.
 148      * @throws IllegalStateException
 149      *             If node was emitted outside <code>leaf set</code> node.
 150      * @throws IOException if an underlying IO error occurs
 151      */
 152     void leafSetEntryNode(Object value) throws IOException;
 153
 154     /**
 155      *
 156      * Emits start of new container.
 157      *
 158      * <p>
 159      * End of container event is emitted by invoking {@link #endNode()}.
 160      *
 161      * <p>
 162      * Valid sub-events are:
 163      * <ul>
 164      * <li>{@link #leafNode}</li>
 165      * <li>{@link #startContainerNode(NodeIdentifier, int)}</li>
 166      * <li>{@link #startChoiceNode(NodeIdentifier, int)}</li>
 167      * <li>{@link #startLeafSet(NodeIdentifier, int)}</li>
 168      * <li>{@link #startMapNode(NodeIdentifier, int)}</li>
 169      * <li>{@link #startUnkeyedList(NodeIdentifier, int)}</li>
 170      * <li>{@link #startAugmentationNode(AugmentationIdentifier)}</li>
 171      * </ul>
 172      *
 173      * @param name
 174      *            name of node as defined in schema, namespace and revision are
 175      *            derived from parent node.
 176      * @param childSizeHint
 177      *            Non-negative count of expected direct child nodes or
 178      *            {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
 179      *            and should not fail writing of child events, if there are more
 180      *            events than count.
 181      * @throws IllegalArgumentException
 182      *             If emitted node is invalid in current context or was emitted
 183      *             multiple times.
 184      * @throws IllegalStateException
 185      *             If node was emitted inside <code>map</code>,
 186      *             <code>choice</code> <code>unkeyed list</code> node.
 187      * @throws IOException if an underlying IO error occurs
 188      */
 189     void startContainerNode(NodeIdentifier name, int childSizeHint) throws IOException;
 190
 191     /**
 192      *
 193      * Emits start of unkeyed list node event.
 194      *
 195      * <p>
 196      * End of unkeyed list event is emitted by invoking {@link #endNode()}.
 197      * Valid subevents is only {@link #startUnkeyedListItem(NodeIdentifier, int)}. All other
 198      * methods will throw {@link IllegalArgumentException}.
 199      *
 200      * @param name
 201      *            name of node as defined in schema, namespace and revision are
 202      *            derived from parent node.
 203      * @param childSizeHint
 204      *            Non-negative count of expected direct child nodes or
 205      *            {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
 206      *            and should not fail writing of child events, if there are more
 207      *            events than count.
 208      * @throws IllegalArgumentException
 209      *             If emitted node is invalid in current context or was emitted
 210      *             multiple times.
 211      * @throws IllegalStateException
 212      *             If node was emitted inside <code>map</code>,
 213      *             <code>choice</code> <code>unkeyed list</code> node.
 214      * @throws IOException if an underlying IO error occurs
 215      */
 216     void startUnkeyedList(NodeIdentifier name, int childSizeHint) throws IOException;
 217
 218     /**
 219      * Emits start of new unkeyed list item.
 220      *
 221      * <p>
 222      * Unkeyed list item event is finished by invoking {@link #endNode()}. Valid
 223      * sub-events are:
 224      * <ul>
 225      * <li>{@link #leafNode}</li>
 226      * <li>{@link #startContainerNode(NodeIdentifier, int)}</li>
 227      * <li>{@link #startChoiceNode(NodeIdentifier, int)}</li>
 228      * <li>{@link #startLeafSet(NodeIdentifier, int)}</li>
 229      * <li>{@link #startMapNode(NodeIdentifier, int)}</li>
 230      * <li>{@link #startUnkeyedList(NodeIdentifier, int)}</li>
 231      * <li>{@link #startAugmentationNode(AugmentationIdentifier)}</li>
 232      * </ul>
 233      *
 234      * @param name Identifier of node
 235      * @param childSizeHint
 236      *            Non-negative count of expected direct child nodes or
 237      *            {@link #UNKNOWN_SIZE} if count is unknown. This is only hint
 238      *            and should not fail writing of child events, if there are more
 239      *            events than count.
 240      * @throws IllegalStateException
 241      *             If node was emitted outside <code>unkeyed list</code> node.
 242      * @throws IOException if an underlying IO error occurs
 243      */
 244     void startUnkeyedListItem(NodeIdentifier name, int childSizeHint) throws IOException;
 245
 246     /**
 247      *
 248      * Emits start of map node event.
 249      *
 250      * <p>
 251      * End of map node event is emitted by invoking {@link #endNode()}. Valid
 252      * subevents is only
 253      * {@link #startMapEntryNode(NodeIdentifierWithPredicates, int)}. All other
 254      * methods will throw {@link IllegalArgumentException}.
 255      *
 256      * @param name
 257      *            name of node as defined in schema, namespace and revision are
 258      *            derived from parent node.
 259      * @param childSizeHint
 260      * @throws IllegalArgumentException
 261      * @throws IllegalStateException
 262      *             If node was emitted inside <code>map</code>,
 263      *             <code>choice</code> <code>unkeyed list</code> node.
 264      * @throws IOException if an underlying IO error occurs
 265      */
 266     void startMapNode(NodeIdentifier name, int childSizeHint) throws IOException;
 267
 268     /**
 269      *
 270      * Emits start of map entry.
 271      *
 272      * <p>
 273      * End of map entry event is emitted by invoking {@link #endNode()}.
 274      *
 275      * <p>
 276      * Valid sub-events are:
 277      * <ul>
 278      * <li>{@link #leafNode}</li>
 279      * <li>{@link #startContainerNode(NodeIdentifier, int)}</li>
 280      * <li>{@link #startChoiceNode(NodeIdentifier, int)}</li>
 281      * <li>{@link #startLeafSet(NodeIdentifier, int)}</li>
 282      * <li>{@link #startMapNode(NodeIdentifier, int)}</li>
 283      * <li>{@link #startUnkeyedList(NodeIdentifier, int)}</li>
 284      * <li>{@link #startAugmentationNode(AugmentationIdentifier)}</li>
 285      * </ul>
 286      *
 287      *
 288      * @param identifier
 289      *            QName to value pairs of keys of map entry node. Values  MUST BE constant over time.
 290      * @throws IllegalArgumentException
 291      *             If key contains incorrect value.
 292      * @throws IllegalStateException
 293      *             If node was emitted outside <code>map entry</code> node.
 294      * @throws IOException if an underlying IO error occurs
 295      */
 296     void startMapEntryNode(NodeIdentifierWithPredicates identifier, int childSizeHint) throws IOException;
 297
 298     /**
 299      *
 300      * Emits start of map node event.
 301      *
 302      * <p>
 303      * End of map node event is emitted by invoking {@link #endNode()}. Valid
 304      * subevents is only
 305      * {@link #startMapEntryNode(NodeIdentifierWithPredicates, int)}. All other
 306      * methods will throw {@link IllegalArgumentException}.
 307      *
 308      * @param name
 309      *            name of node as defined in schema, namespace and revision are
 310      *            derived from parent node.
 311      * @throws IllegalArgumentException
 312      * @throws IllegalStateException
 313      *             If node was emitted inside <code>map</code>,
 314      *             <code>choice</code> <code>unkeyed list</code> node.
 315      * @throws IOException if an underlying IO error occurs
 316      */
 317     void startOrderedMapNode(NodeIdentifier name, int childSizeHint) throws IOException;
 318
 319     /**
 320      *
 321      *
 322      *
 323      * @param name
 324      *            name of node as defined in schema, namespace and revision are
 325      *            derived from parent node.
 326      * @param childSizeHint
 327      * @throws IllegalArgumentException
 328      * @throws IllegalStateException
 329      *             If node was emitted inside <code>map</code>,
 330      *             <code>choice</code> <code>unkeyed list</code> node.
 331      * @throws IOException if an underlying IO error occurs
 332      */
 333     void startChoiceNode(NodeIdentifier name, int childSizeHint) throws IOException;
 334
 335     /**
 336      * Emits start of augmentation node.
 337      *
 338      * <p>
 339      * End of augmentation event is emitted by invoking {@link #endNode()}.
 340      *
 341      * <p>
 342      * Valid sub-events are:
 343      *
 344      * <ul>
 345      * <li>{@link #leafNode}</li>
 346      * <li>{@link #startContainerNode(NodeIdentifier, int)}</li>
 347      * <li>{@link #startChoiceNode(NodeIdentifier, int)}</li>
 348      * <li>{@link #startLeafSet(NodeIdentifier, int)}</li>
 349      * <li>{@link #startMapNode(NodeIdentifier, int)}</li>
 350      * <li>{@link #startUnkeyedList(NodeIdentifier, int)}</li>
 351      * </ul>
 352      *
 353      * @param identifier
 354      *            Augmentation identifier
 355      * @throws IllegalArgumentException
 356      *             If augmentation is invalid in current context.
 357      * @throws IOException if an underlying IO error occurs
 358      */
 359     void startAugmentationNode(AugmentationIdentifier identifier) throws IOException;
 360
 361     /**
 362      * Emits anyxml node event.
 363      *
 364      * @param name
 365      * @param value
 366      * @throws IllegalArgumentException
 367      * @throws IllegalStateException
 368      *             If node was emitted inside <code>map</code>,
 369      *             <code>choice</code> <code>unkeyed list</code> node.
 370      * @throws IOException if an underlying IO error occurs
 371      */
 372     void anyxmlNode(NodeIdentifier name, Object value) throws IOException;
 373
 374     /**
 375      * Emits end event for node.
 376      *
 377      * @throws IllegalStateException If there is no start* event to be closed.
 378      * @throws IOException if an underlying IO error occurs
 379      */
 380     void endNode() throws IOException;
 381
 382     @Override
 383     void close() throws IOException;
 384
 385     @Override
 386     void flush() throws IOException;
 387 }