org.opendaylight.mdsal.binding.javav2.spec.runtime

Interface BindingStreamEventWriter

All Superinterfaces:

AutoCloseable, Closeable, Flushable

All Known Implementing Classes:

BindingToNormalizedStreamWriter, CachingNormalizedNodeSerializer

@Beta
public interface BindingStreamEventWriter
extends Closeable, Flushable

Event Stream Writer for Binding version 2 Representation

Emitting Event Stream

• container - Container node representation, start event is emitted using startContainerNode(Class, int) and node end event is emitted using endNode(). Container node is implementing TreeNode interface.
• list - YANG list statement has two representations in event stream - un-keyed list and map. Un-keyed list is YANG list which didn't specify key.
  • Map - Map start event is emitted using startMapNode(Class, int) and is ended using endNode(). Each map entry start is emitted using startMapEntryNode(IdentifiableItem, int) with Map of keys and finished using endNode().
  • UnkeyedList - Un-keyed list represents list without keys, un-keyed list start is emitted using startUnkeyedList(Class, int), list end is emitted using endNode(). Each list item is emitted using startUnkeyedListItem(int) and ended using endNode().
• leaf - Leaf node event is emitted using leafNode(String, Object). endNode() MUST NOT be emitted for leaf node.
• leaf-list - Leaf list start is emitted using startLeafSet(String, int). Leaf list end is emitted using endNode(). Leaf list entries are emitted using leafSetEntryNode(Object).
• anyxml - Anyxml node event is emitted using anyxmlNode(String, Object). endNode() MUST NOT be emitted for anyxml node.
• anydata - Anydata node event is emitted using startAnydataNode(String, Object). endNode() MUST NOT be emitted for anydata node.
• choice Choice node event is emitted by startChoiceNode(Item, int) event and must be immediately followed by startCase(Class, int) event. Choice node is finished by emitting an endNode() event.
• case - Case node may be emitted only inside choice node by invoking startCase(Class, int). Case node is finished be emitting an endNode() event.
• augment - Represents augmentation, augmentation node is started by invoking startAugmentationNode(Class) and finished by invoking endNode().

Implementation notes

This interface is not intended to be implemented by users of generated Binding2 DTOs but to be used by utilities, which needs to emit NormalizedNode model from Binding2 DTOs.

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 Binding2 DTOs.

Existence of this interface in runtime Java Binding2 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 Binding2 DTOs and wired in OSGI.

Field Summary

Fields

Modifier and Type	Field and Description
static int	UNKNOWN_SIZE Methods in this interface allow users to hint the underlying implementation about the sizing of container-like constructors (leafLists, containers, etc.).

Method Summary

Modifier and Type	Method and Description
void	anyxmlNode(String name, Object value) Emits anyxml node event.
void	close()
void	endNode() Emits end event for node.
void	flush()
void	leafNode(String localName, Object value) Emits a leaf node event with supplied value.
void	leafSetEntryNode(Object value) Emits a leaf set entry node
void	startAnydataNode(String name, Object value) Emits anydata node event.
void	startAugmentationNode(Class<? extends Augmentation<?>> augmentationType) Emits start of augmentation node.
void	startCase(Class<? extends TreeNode> caze, int childSizeHint) Starts a case node.
<T extends TreeNode> void	startChoiceNode(Item<T> choice, int childSizeHint) Emits start of choice node.
void	startContainerNode(Class<? extends TreeNode> container, int childSizeHint) Emits start of new container.
void	startLeafSet(String localName, int childSizeHint) Emits a start of leaf set (leaf-list).
<I extends TreeNode,T> void	startMapEntryNode(IdentifiableItem<I,T> keyValues, int childSizeHint) Emits start of map entry.
<T extends TreeNode & org.opendaylight.yangtools.concepts.Identifiable<?>> void	startMapNode(Class<T> mapEntryType, int childSizeHint) Emits start of unordered map node event.
void	startOrderedLeafSet(String localName, int childSizeHint) Emits a start of leaf set (leaf-list).
<T extends TreeNode & org.opendaylight.yangtools.concepts.Identifiable<?>> void	startOrderedMapNode(Class<T> mapEntryType, int childSizeHint) Emits start of ordered map node event.
void	startUnkeyedList(Class<? extends TreeNode> localName, int childSizeHint) Emits start of unkeyed list node event.
void	startUnkeyedListItem(int childSizeHint) Emits start of new unkeyed list item.

Field Detail

UNKNOWN_SIZE

static final int UNKNOWN_SIZE

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.

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.

See Also:

Constant Field Values

Method Detail

leafNode

void leafNode(String localName,
              Object value)
       throws IOException

Emits a leaf node event with supplied value.

Parameters:

localName - name of node as defined in schema, namespace and revision are derived from parent node.

value - Value of leaf node.

Throws:

IllegalArgumentException - If emitted leaf node has invalid value in current context or was emitted multiple times.

IllegalStateException - If node was emitted inside map, choice unkeyed list node.

IOException - if an underlying IO error occurs

startLeafSet

void startLeafSet(String localName,
                  int childSizeHint)
           throws IOException

Emits a start of leaf set (leaf-list).

Emits start of leaf set, during writing leaf set event, only leafSetEntryNode(Object) calls are valid. Leaf set event is finished by calling endNode().

Parameters:

localName - name of node as defined in schema, namespace and revision are derived from parent node.

childSizeHint - Non-negative count of expected direct child nodes or 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 leaf node is invalid in current context or was emitted multiple times.

IllegalStateException - If node was emitted inside map, choice unkeyed list node.

IOException - if an underlying IO error occurs

startOrderedLeafSet

void startOrderedLeafSet(String localName,
                         int childSizeHint)
                  throws IOException

Emits a start of leaf set (leaf-list).

Emits start of leaf set, during writing leaf set event, only leafSetEntryNode(Object) calls are valid. Leaf set event is finished by calling endNode().

Parameters:

localName - name of node as defined in schema, namespace and revision are derived from parent node.

childSizeHint - Non-negative count of expected direct child nodes or 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 leaf node is invalid in current context or was emitted multiple times.

IllegalStateException - If node was emitted inside map, choice unkeyed list node.

IOException - if an underlying IO error occurs

leafSetEntryNode

void leafSetEntryNode(Object value)
               throws IOException

Emits a leaf set entry node

Parameters:

value - Value of leaf set entry node.

Throws:

IllegalArgumentException - If emitted leaf node has invalid value.

IllegalStateException - If node was emitted outside leaf set node.

IOException - if an underlying IO error occurs

startContainerNode

void startContainerNode(Class<? extends TreeNode> container,
                        int childSizeHint)
                 throws IOException

Emits start of new container.

End of container event is emitted by invoking endNode().

Valid sub-events are:

• leafNode(String, Object)
• startContainerNode(Class, int)
• startChoiceNode(Item, int)
• startLeafSet(String, int)
• startMapNode(Class, int)
• startUnkeyedList(Class, int)
• startAugmentationNode(Class)

Parameters:

container - name of node as defined in schema, namespace and revision are derived from parent node.

childSizeHint - Non-negative count of expected direct child nodes or 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.

IllegalStateException - If node was emitted inside map, choice unkeyed list node.

IOException - if an underlying IO error occurs

startUnkeyedList

void startUnkeyedList(Class<? extends TreeNode> localName,
                      int childSizeHint)
               throws IOException

Emits start of unkeyed list node event.

End of unkeyed list event is emitted by invoking endNode(). Valid sub-event is only startUnkeyedListItem(int). All other methods will throw IllegalArgumentException.

Parameters:

localName - name of node as defined in schema, namespace and revision are derived from parent node.

childSizeHint - Non-negative count of expected direct child nodes or 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.

IllegalStateException - If node was emitted inside map, choice unkeyed list node.

IOException - if an underlying IO error occurs

startUnkeyedListItem

void startUnkeyedListItem(int childSizeHint)
                   throws IOException

Emits start of new unkeyed list item.

Un-keyed list item event is finished by invoking endNode().

Valid sub-events are:

• leafNode(String, Object)
• startContainerNode(Class, int)
• startChoiceNode(Item, int)
• startLeafSet(String, int)
• startMapNode(Class, int)
• startUnkeyedList(Class, int)
• startAugmentationNode(Class)

Parameters:

childSizeHint - Non-negative count of expected direct child nodes or 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:

IllegalStateException - If node was emitted outside unkeyed list node.

IOException - if an underlying IO error occurs

startMapNode

<T extends TreeNode & org.opendaylight.yangtools.concepts.Identifiable<?>> void startMapNode(Class<T> mapEntryType,
                                                                                             int childSizeHint)
                                                                                      throws IOException

Emits start of unordered map node event.

End of map node event is emitted by invoking endNode(). Valid subevents is only startMapEntryNode(IdentifiableItem, int). All other methods will throw IllegalArgumentException.

Parameters:

mapEntryType - Class of list.

childSizeHint - Non-negative count of expected direct child nodes or 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

IllegalStateException - If node was emitted inside map, choice unkeyed list node.

IOException - if an underlying IO error occurs

startOrderedMapNode

<T extends TreeNode & org.opendaylight.yangtools.concepts.Identifiable<?>> void startOrderedMapNode(Class<T> mapEntryType,
                                                                                                    int childSizeHint)
                                                                                             throws IOException

Emits start of ordered map node event.

End of map node event is emitted by invoking endNode(). Valid sub-event is only startMapEntryNode(IdentifiableItem, int). All other methods will throw IllegalArgumentException.

Parameters:

mapEntryType - Class of list item, which has defined key.

childSizeHint - Non-negative count of expected direct child nodes or 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

IllegalStateException - If node was emitted inside map, choice unkeyed list node.

IOException - if an underlying IO error occurs

startMapEntryNode

<I extends TreeNode,T> void startMapEntryNode(IdentifiableItem<I,T> keyValues,
                                              int childSizeHint)
                                       throws IOException

Emits start of map entry.

End of map entry event is emitted by invoking endNode().

Valid sub-events are:

• leafNode(String, Object)
• startContainerNode(Class, int)
• startChoiceNode(Item, int)
• startLeafSet(String, int)
• startMapNode(Class, int)
• startUnkeyedList(Class, int)
• startAugmentationNode(Class)

Parameters:

keyValues - Key of map entry node

childSizeHint - Non-negative count of expected direct child nodes or 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.

IllegalStateException - If node was emitted outside map entry node.

IOException - if an underlying IO error occurs

startChoiceNode

<T extends TreeNode> void startChoiceNode(Item<T> choice,
                                          int childSizeHint)
                                   throws IOException

Emits start of choice node.

Valid sub-event is startCase(Class, int), which selects case which should be written.

Parameters:

choice - Choice class.

childSizeHint - Non-negative count of expected direct child nodes or 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

IllegalStateException - If node was emitted inside map, choice, unkeyed list node.

IOException - if an underlying IO error occurs

startCase

void startCase(Class<? extends TreeNode> caze,
               int childSizeHint)
        throws IOException

Starts a case node.

Valid sub-events are:

• leafNode(String, Object)
• startContainerNode(Class, int)
• startChoiceNode(Item, int)
• startLeafSet(String, int)
• startMapNode(Class, int)
• startUnkeyedList(Class, int)
• startAugmentationNode(Class)

Parameters:

caze - Case class

Throws:

IllegalArgumentException

IOException - if an underlying IO error occurs

startAugmentationNode

void startAugmentationNode(Class<? extends Augmentation<?>> augmentationType)
                    throws IOException

Emits start of augmentation node.

End of augmentation event is emitted by invoking endNode().

Valid sub-events are:

• leafNode(String, Object)
• startContainerNode(Class, int)
• startChoiceNode(Item, int)
• startLeafSet(String, int)
• startMapNode(Class, int)
• startUnkeyedList(Class, int)

Note this is only method, which does not require childSizeHint, since maximum value is always size of possibleChildren.

Parameters:

augmentationType - augmentation class

Throws:

IllegalArgumentException - If augmentation is invalid in current context.

IOException - if an underlying IO error occurs

anyxmlNode

void anyxmlNode(String name,
                Object value)
         throws IOException

Emits anyxml node event.

Parameters:

name -

value -

Throws:

IllegalArgumentException

IllegalStateException - If node was emitted inside map, choice unkeyed list node.

IOException - if an underlying IO error occurs

startAnydataNode

void startAnydataNode(String name,
                      Object value)
               throws IOException

Emits anydata node event.

Parameters:

name -

value -

Throws:

IllegalStateException - If node was emitted inside map, choice unkeyed list node.

IOException - if an underlying IO error occurs

endNode

void endNode()
      throws IOException

Emits end event for node.

Throws:

IllegalStateException - If there is no open node.

IOException - if an underlying IO error occurs

flush

void flush()
    throws IOException

Specified by:

flush in interface Flushable

Throws:

IOException

close

void close()
    throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException