org.opendaylight.yangtools.yang.data.codec.xml

Class XmlParserStream

java.lang.Object

org.opendaylight.yangtools.yang.data.codec.xml.XmlParserStream

All Implemented Interfaces:

Closeable, Flushable, AutoCloseable

@Beta
public final class XmlParserStream
extends Object
implements Closeable, Flushable

This class provides functionality for parsing an XML source containing YANG-modeled data. It disallows multiple instances of the same element except for leaf-list and list entries. It also expects that the YANG-modeled data in the XML source are wrapped in a root element. This class is NOT thread-safe.

Due to backwards compatibility reasons, RFC7952 metadata emitted by this parser may include key QNames with empty URI (as exposed via LEGACY_ATTRIBUTE_NAMESPACE) as their QNameModule. These indicate an unqualified XML attribute and their value can be assumed to be a String. Furthermore, this extends to qualified attributes, which uses the proper namespace, but will not bind to a proper module revision -- these need to be reconciled with a particular SchemaContext and are expected to either be fully decoded, or contain a String value. Handling of such annotations is at the discretion of the user encountering it: preferred way of handling is to either filter or normalize them to proper QNames/values when encountered. This caveat will be removed in a future version.

Field Summary

Fields

Modifier and Type	Field and Description
static QNameModule	LEGACY_ATTRIBUTE_NAMESPACE Deprecated. The use on this namespace is discouraged and users are strongly encouraged to proper RFC7952 metadata annotations.

Method Summary

Modifier and Type	Method and Description
void	close()
static XmlParserStream	create(NormalizedNodeStreamWriter writer, MountPointContext mountCtx, SchemaNode parentNode) Utility method for use when caching XmlCodecFactory is not feasible.
static XmlParserStream	create(NormalizedNodeStreamWriter writer, MountPointContext mountCtx, SchemaNode parentNode, boolean strictParsing) Utility method for use when caching XmlCodecFactory is not feasible.
static XmlParserStream	create(NormalizedNodeStreamWriter writer, SchemaContext schemaContext, SchemaNode parentNode) Utility method for use when caching XmlCodecFactory is not feasible.
static XmlParserStream	create(NormalizedNodeStreamWriter writer, SchemaContext schemaContext, SchemaNode parentNode, boolean strictParsing) Utility method for use when caching XmlCodecFactory is not feasible.
static XmlParserStream	create(NormalizedNodeStreamWriter writer, XmlCodecFactory codecs, SchemaNode parentNode) Construct a new XmlParserStream with strict parsing mode switched on.
static XmlParserStream	create(NormalizedNodeStreamWriter writer, XmlCodecFactory codecs, SchemaNode parentNode, boolean strictParsing) Construct a new XmlParserStream.
void	flush()
XmlParserStream	parse(XMLStreamReader reader) This method parses the XML source and emits node events into a NormalizedNodeStreamWriter based on the YANG-modeled data contained in the XML source.
XmlParserStream	traverse(DOMSource src) This method traverses a DOMSource and emits node events into a NormalizedNodeStreamWriter based on the YANG-modeled data contained in the source.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LEGACY_ATTRIBUTE_NAMESPACE

@Deprecated
public static final QNameModule LEGACY_ATTRIBUTE_NAMESPACE

Deprecated. The use on this namespace is discouraged and users are strongly encouraged to proper RFC7952 metadata annotations.

QNameModule for use with legacy XML attributes.

Method Detail

create

public static XmlParserStream create(NormalizedNodeStreamWriter writer,
                                     XmlCodecFactory codecs,
                                     SchemaNode parentNode)

Construct a new XmlParserStream with strict parsing mode switched on.

Parameters:

writer - Output writer

codecs - Shared codecs

parentNode - Parent root node

Returns:

A new stream instance

create

public static XmlParserStream create(NormalizedNodeStreamWriter writer,
                                     XmlCodecFactory codecs,
                                     SchemaNode parentNode,
                                     boolean strictParsing)

Construct a new XmlParserStream.

Parameters:

writer - Output writer

codecs - Shared codecs

parentNode - Parent root node

strictParsing - parsing mode if set to true, the parser will throw an exception if it encounters unknown child nodes (nodes, that are not defined in the provided SchemaContext) in containers and lists if set to false, the parser will skip unknown child nodes

Returns:

A new stream instance

create

public static XmlParserStream create(NormalizedNodeStreamWriter writer,
                                     SchemaContext schemaContext,
                                     SchemaNode parentNode)

Utility method for use when caching XmlCodecFactory is not feasible. Users with high performance requirements should use create(NormalizedNodeStreamWriter, XmlCodecFactory, SchemaNode) instead and maintain a XmlCodecFactory to match the current SchemaContext.

create

public static XmlParserStream create(NormalizedNodeStreamWriter writer,
                                     SchemaContext schemaContext,
                                     SchemaNode parentNode,
                                     boolean strictParsing)

Utility method for use when caching XmlCodecFactory is not feasible. Users with high performance requirements should use create(NormalizedNodeStreamWriter, XmlCodecFactory, SchemaNode) instead and maintain a XmlCodecFactory to match the current SchemaContext.

create

public static XmlParserStream create(NormalizedNodeStreamWriter writer,
                                     MountPointContext mountCtx,
                                     SchemaNode parentNode)

Utility method for use when caching XmlCodecFactory is not feasible. Users with high performance requirements should use create(NormalizedNodeStreamWriter, XmlCodecFactory, SchemaNode) instead and maintain a XmlCodecFactory to match the current MountPointContext.

create

public static XmlParserStream create(NormalizedNodeStreamWriter writer,
                                     MountPointContext mountCtx,
                                     SchemaNode parentNode,
                                     boolean strictParsing)

Utility method for use when caching XmlCodecFactory is not feasible. Users with high performance requirements should use create(NormalizedNodeStreamWriter, XmlCodecFactory, SchemaNode) instead and maintain a XmlCodecFactory to match the current MountPointContext.

parse

public XmlParserStream parse(XMLStreamReader reader)
                      throws XMLStreamException,
                             URISyntaxException,
                             IOException,
                             SAXException

This method parses the XML source and emits node events into a NormalizedNodeStreamWriter based on the YANG-modeled data contained in the XML source.

Parameters:

reader - StAX reader which is to used to walk through the XML source

Returns:

instance of XmlParserStream

Throws:

XMLStreamException - if a well-formedness error or an unexpected processing condition occurs while parsing the XML

URISyntaxException - if the namespace URI of an XML element contains a syntax error

IOException - if an error occurs while parsing the value of an anyxml node

SAXException - if an error occurs while parsing the value of an anyxml node

traverse

@Beta
public XmlParserStream traverse(DOMSource src)
                               throws XMLStreamException,
                                      URISyntaxException,
                                      IOException,
                                      SAXException

This method traverses a DOMSource and emits node events into a NormalizedNodeStreamWriter based on the YANG-modeled data contained in the source.

Parameters:

src - DOMSource to be traversed

Returns:

instance of XmlParserStream

Throws:

XMLStreamException - if a well-formedness error or an unexpected processing condition occurs while parsing the XML

URISyntaxException - if the namespace URI of an XML element contains a syntax error

IOException - if an error occurs while parsing the value of an anyxml node

SAXException - if an error occurs while parsing the value of an anyxml node

close

public void close()
           throws IOException

Specified by:

close in interface Closeable

Specified by:

close in interface AutoCloseable

Throws:

IOException

flush

public void flush()
           throws IOException

Specified by:

flush in interface Flushable

Throws:

IOException