StreamWriterMetadataExtension (yangtools-docs 4.0.7 API)

All Superinterfaces:

NormalizedNodeStreamWriterExtension, ObjectExtension<NormalizedNodeStreamWriter,NormalizedNodeStreamWriterExtension>

All Known Implementing Classes:

ImmutableMetadataNormalizedNodeStreamWriter, ImmutableNormalizedMetadataStreamWriter, XMLStreamNormalizedNodeStreamWriter
```
@Beta
public interface StreamWriterMetadataExtension
extends NormalizedNodeStreamWriterExtension
```
Extension to the NormalizedNodeStreamWriter with metadata support. Semantically this extends the event model of NormalizedNodeStreamWriter with a new event, metadata(ImmutableMap). This event is valid on any open node. This event may be emitted only once.
Note that some implementations of this interface, notably those targeting streaming XML, may require metadata to be emitted before any other events. Such requirement is communicated through requireMetadataFirst() and users must honor it. If such requirement is not set, metadata may be emitted at any time.
Furthermore implementations targeting RFC7952 encoding towards external systems are required to handle metadata attached to leaf-list and list nodes by correctly extending them to each entry.

Method Summary

All Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method	Description
`void`	`metadata(ImmutableMap<QName,Object> metadata)`	Emit a block of metadata associated with the currently-open node.
`default boolean`	`requireMetadataFirst()`	Indicate whether metadata is required to be emitted just after an entry is open.

- Method Detail
  - metadata
```
void metadata(ImmutableMap<QName,Object> metadata)
       throws IOException
```
    Emit a block of metadata associated with the currently-open node. The argument is a map of annotation names, as defined md:annotation extension. Values are normalized objects, which are required to be effectively-immutable.
    
    Parameters:
    
    metadata - Metadata block
    
    Throws:
    
    NullPointerException - if metadata is null
    
    IllegalStateException - when this method is invoked outside of an open node or metadata has already been emitted.
    
    IOException - if an underlying IO error occurs
  - requireMetadataFirst
```
default boolean requireMetadataFirst()
```
    Indicate whether metadata is required to be emitted just after an entry is open. The default implementation returns false.
    
    Returns:
    
    True if metadata must occur just after the start of an entry.