Package org.opendaylight.mdsal.binding.dom.codec.api

Interface BindingStreamEventWriter

All Superinterfaces:

AutoCloseable, Closeable, Flushable

@Beta
public interface BindingStreamEventWriter
extends Closeable, Flushable

Event Stream Writer for Binding Representation.

Emmiting 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 DataObject interface.
• list - YANG list statement has two representation in event stream - unkeyed list and map. Unkeyed list is YANG list which did not 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(Identifier, int) with Map of keys and finished using endNode().
  • UnkeyedList - Unkeyed list represent list without keys, unkeyed 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 be not 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 leafNode(String, Object). endNode() MUST be not emitted for anyxml node.
• choice Choice node event is emitted by startChoiceNode(Class, 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 Binding DTOs but to be used by utilities, which needs to emit NormalizedNode model from Binding 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 Binding DTOs.

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

Field Summary

Fields

Modifier and Type	Field	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	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	startAugmentationNode(Class<? extends Augmentation<?>> augmentationType)	Emits start of augmentation node.
void	startCase(Class<? extends DataObject> caze, int childSizeHint)	Starts a case node.
void	startChoiceNode(Class<? extends DataContainer> choice, int childSizeHint)	Emits start of choice node.
void	startContainerNode(Class<? extends DataObject> container, int childSizeHint)	Emits start of new container.
void	startLeafSet(String localName, int childSizeHint)	Emits a start of leaf set (leaf-list).
void	startMapEntryNode(Identifier<?> keyValues, int childSizeHint)	Emits start of map entry.
<T extends DataObject & 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 DataObject & Identifiable<?>> void	startOrderedMapNode(Class<T> mapEntryType, int childSizeHint)	Emits start of ordered map node event.
void	startUnkeyedList(Class<? extends DataObject> 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 DataObject> 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(Class, 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 DataObject> localName,
                      int childSizeHint)
               throws IOException

Emits start of unkeyed list node event.

End of unkeyed list event is emitted by invoking endNode(). Valid subevents 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.

Unkeyed list item event is finished by invoking endNode(). Valid sub-events are:

• leafNode(String, Object)
• startContainerNode(Class, int)
• startChoiceNode(Class, 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 DataObject & 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 subevent is only startMapEntryNode(Identifier, 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 - 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

startOrderedMapNode

<T extends DataObject & 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 subevent is only startMapEntryNode(Identifier, 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 - 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

startMapEntryNode

void startMapEntryNode(Identifier<?> 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(Class, 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

void startChoiceNode(Class<? extends DataContainer> choice,
                     int childSizeHint)
              throws IOException

Emits start of choice node.

Valid sub-event in 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:

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

IOException - if an underlying IO error occurs

startCase

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

Starts a case node.

Valid sub-events are:

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

Parameters:

caze - Case class

Throws:

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(Class, 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 - node name

value - node 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