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