opendaylight/md-sal/sal-clustering-commons/src/main/java/org/opendaylight/controller/cluster/datastore/node/utils/stream/NormalizedNodeStreamWriter.java

   1
   2 /*
   3  * Copyright (c) 2014 Cisco Systems, Inc. and others.  All rights reserved.
   4  *
   5  * This program and the accompanying materials are made available under the
   6  * terms of the Eclipse Public License v1.0 which accompanies this distribution,
   7  * and is available at http://www.eclipse.org/legal/epl-v10.html
   8  */
   9
  10 package org.opendaylight.controller.cluster.datastore.node.utils.stream;
  11
  12 import java.io.Closeable;
  13 import java.io.Flushable;
  14 import java.io.IOException;
  15
  16 import org.opendaylight.yangtools.yang.data.api.YangInstanceIdentifier;
  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(YangInstanceIdentifier.NodeIdentifier, int)}
  26  * and node end event is
  27  * emitted using {@link #endNode()}. Container node is implementing
  28  * {@link org.opendaylight.yangtools.yang.binding.DataObject} interface.
  29  *
  30  * <li><code>list</code> - YANG list statement has two representation in event
  31  * stream - unkeyed list and map. Unkeyed list is YANG list which did not
  32  * specify key.</li>
  33  *
  34  * <ul>
  35  * <li><code>Map</code> - Map start event is emitted using
  36  * {@link #startMapNode(YangInstanceIdentifier.NodeIdentifier, int)}
  37  * and is ended using {@link #endNode()}. Each map entry start is emitted using
  38  * {@link #startMapEntryNode(YangInstanceIdentifier.NodeIdentifierWithPredicates, int)}
  39  * with Map of keys
  40  * and finished using {@link #endNode()}.</li>
  41  *
  42  * <li><code>UnkeyedList</code> - Unkeyed list represent list without keys,
  43  * unkeyed list start is emitted using
  44  * {@link #startUnkeyedList(YangInstanceIdentifier.NodeIdentifier, int)} list
  45  * end is emitted using {@link #endNode()}. Each list item is emitted using
  46  * {@link #startUnkeyedListItem(YangInstanceIdentifier.NodeIdentifier, int)}
  47  * and ended using {@link #endNode()}.</li>
  48  * </ul>
  49  *
  50  * <li><code>leaf</code> - Leaf node event is emitted using
  51  * {@link #leafNode(YangInstanceIdentifier.NodeIdentifier, Object)}.
  52  * {@link #endNode()} MUST NOT BE emitted for
  53  * leaf node.</li>
  54  *
  55  * <li><code>leaf-list</code> - Leaf list start is emitted using
  56  * {@link #startLeafSet(YangInstanceIdentifier.NodeIdentifier, int)}.
  57  * Leaf list end is emitted using
  58  * {@link #endNode()}. Leaf list entries are emitted using
  59  * {@link #leafSetEntryNode(YangInstanceIdentifier.NodeWithValue name, Object).
  60  *
  61  * <li><code>anyxml - Anyxml node event is emitted using
  62  * {@link #leafNode(YangInstanceIdentifier.NodeIdentifier, Object)}. {@link #endNode()} MUST NOT BE emitted
  63  * for anyxml node.</code></li>
  64  *
  65  *
  66  * <li><code>choice</code> Choice node event is emmited by
  67  * {@link #startChoiceNode(YangInstanceIdentifier.NodeIdentifier, int)} event and
  68  * finished by invoking {@link #endNode()}
  69  * <li>
  70  * <code>augment</code> - Represents augmentation, augmentation node is started
  71  * by invoking {@link #startAugmentationNode(YangInstanceIdentifier.AugmentationIdentifier)} and
  72  * finished by invoking {@link #endNode()}.</li>
  73  *
  74  * </ul>
  75  *
  76  * <h3>Implementation notes</h3>
  77  *
  78  * <p>
  79  * Implementations of this interface must not hold user suppled objects
  80  * and resources needlessly.
  81  *
  82  */
  83
  84 public interface NormalizedNodeStreamWriter extends Closeable, Flushable {
  85
  86     public final int UNKNOWN_SIZE = -1;
  87
  88     /**
  89      * Write the leaf node identifier and value to the stream.
  90      * @param name
  91      * @param value
  92      * @throws IOException
  93      * @throws IllegalArgumentException
  94      */
  95     void leafNode(YangInstanceIdentifier.NodeIdentifier name, Object value)
  96         throws IOException, IllegalArgumentException;
  97
  98     /**
  99      * Start writing leaf Set node. You must call {@link #endNode()} once you are done writing all of its children.
 100      * @param name
 101      * @param childSizeHint is the estimated children count. Usage is optional in implementation.
 102      * @throws IOException
 103      * @throws IllegalArgumentException
 104      */
 105     void startLeafSet(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
 106         throws IOException, IllegalArgumentException;
 107
 108     /**
 109      * Write the leaf Set Entry Node object to the stream with identifier and value.
 110      * @param name
 111      * @param value
 112      * @throws IOException
 113      * @throws IllegalArgumentException
 114      */
 115     void leafSetEntryNode(YangInstanceIdentifier.NodeWithValue name, Object value)
 116         throws IOException, IllegalArgumentException;
 117
 118     /**
 119      * Start writing container node. You must call {@link #endNode()} once you are done writing all of its children.
 120      * @param name
 121      * @param childSizeHint is the estimated children count. Usage is optional in implementation.
 122      * @throws IOException
 123      * @throws IllegalArgumentException
 124      */
 125     void startContainerNode(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
 126         throws IOException, IllegalArgumentException;
 127
 128     /**
 129      * Start writing unkeyed list node. You must call {@link #endNode()} once you are done writing all of its children.
 130      * @param name
 131      * @param childSizeHint is the estimated children count. Usage is optional in implementation.
 132      * @throws IOException
 133      * @throws IllegalArgumentException
 134      */
 135     void startUnkeyedList(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
 136         throws IOException, IllegalArgumentException;
 137
 138     /**
 139      * Start writing unkeyed list item. You must call {@link #endNode()} once you are done writing all of its children.
 140      * @param name
 141      * @param childSizeHint is the estimated children count. Usage is optional in implementation.
 142      * @throws IOException
 143      * @throws IllegalStateException
 144      */
 145     void startUnkeyedListItem(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
 146         throws IOException, IllegalStateException;
 147
 148     /**
 149      * Start writing map node. You must call {@link #endNode()} once you are done writing all of its children.
 150      * @param name
 151      * @param childSizeHint is the estimated children count. Usage is optional in implementation.
 152      * @throws IOException
 153      * @throws IllegalArgumentException
 154      */
 155     void startMapNode(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
 156         throws IOException, IllegalArgumentException;
 157
 158     /**
 159      * Start writing map entry node. You must call {@link #endNode()} once you are done writing all of its children.
 160      * @param identifier
 161      * @param childSizeHint is the estimated children count. Usage is optional in implementation.
 162      * @throws IOException
 163      * @throws IllegalArgumentException
 164      */
 165     void startMapEntryNode(YangInstanceIdentifier.NodeIdentifierWithPredicates identifier, int childSizeHint)
 166         throws IOException, IllegalArgumentException;
 167
 168     /**
 169      * Start writing ordered map node. You must call {@link #endNode()} once you are done writing all of its children.
 170      * @param name
 171      * @param childSizeHint is the estimated children count. Usage is optional in implementation.
 172      * @throws IOException
 173      * @throws IllegalArgumentException
 174      */
 175     void startOrderedMapNode(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
 176         throws IOException, IllegalArgumentException;
 177
 178     /**
 179      * Start writing choice node. You must call {@link #endNode()} once you are done writing all of its children.
 180      * @param name
 181      * @param childSizeHint is the estimated children count. Usage is optional in implementation.
 182      * @throws IOException
 183      * @throws IllegalArgumentException
 184      */
 185     void startChoiceNode(YangInstanceIdentifier.NodeIdentifier name, int childSizeHint)
 186         throws IOException, IllegalArgumentException;
 187
 188     /**
 189      * Start writing augmentation node. You must call {@link #endNode()} once you are done writing all of its children.
 190      * @param identifier
 191      * @throws IOException
 192      * @throws IllegalArgumentException
 193      */
 194     void startAugmentationNode(YangInstanceIdentifier.AugmentationIdentifier identifier)
 195         throws IOException, IllegalArgumentException;
 196
 197     /**
 198      * Write any xml node identifier and value to the stream
 199      * @param name
 200      * @param value
 201      * @throws IOException
 202      * @throws IllegalArgumentException
 203      */
 204     void anyxmlNode(YangInstanceIdentifier.NodeIdentifier name, Object value)
 205         throws IOException, IllegalArgumentException;
 206
 207     /**
 208      * This method should be used to add end symbol/identifier of node in the stream.
 209      * @throws IOException
 210      * @throws IllegalStateException
 211      */
 212     void endNode() throws IOException, IllegalStateException;
 213
 214     @Override
 215     void close() throws IOException;
 216
 217     @Override
 218     void flush() throws IOException;
 219 }