XmlReader Class

Package:

com.azure.xml

Maven Artifact:

com.azure:azure-xml:1.2.0

• java.lang.Object
• • com.azure.xml.XmlReader

Implements

AutoCloseable

public final class XmlReader
implements AutoCloseable

Reads an XML encoded value as a stream of tokens.

Method Summary

Modifier and Type	Method and Description
void	close() Closes the XML stream.
XmlToken	currentToken() Gets the XmlToken that the reader points to currently.
boolean	elementNameMatches(String localName) Checks if the current element name matches the provided local name.
boolean	elementNameMatches(String namespaceUri, String localName) Checks if the current element namespace URI and name matches the provided namespace URI and local name.
static XmlReader	fromBytes(byte[] xml) Creates an XMLStreamReader-based XmlReader that parses the passed xml.
static XmlReader	fromReader(Reader xml) Creates an XmlReader that parses the passed xml.
static XmlReader	fromStream(InputStream xml) Creates an XmlReader that parses the passed xml.
static XmlReader	fromString(String xml) Creates an XmlReader that parses the passed xml.
static XmlReader	fromXmlStreamReader(XMLStreamReader reader) Creates an XmlReader that parses the passed xml.
byte[]	getBinaryAttribute(String namespaceUri, String localName) Gets the binary value for the attribute in the XML element.
byte[]	getBinaryElement() Gets the binary value for the current element.
boolean	getBooleanAttribute(String namespaceUri, String localName) Gets the boolean value for the attribute in the XML element.
boolean	getBooleanElement() Gets the boolean value for the current element.
double	getDoubleAttribute(String namespaceUri, String localName) Gets the double value for the attribute in the XML element.
double	getDoubleElement() Gets the double value for the current element.
String	getElementLocalName() Gets the local name for the current XML element.
QName	getElementName() Gets the QName for the current XML element.
String	getElementNamespaceUri() Gets the namespace URI for the current XML element.
float	getFloatAttribute(String namespaceUri, String localName) Gets the float value for the attribute in the XML element.
float	getFloatElement() Gets the float value for the current element.
int	getIntAttribute(String namespaceUri, String localName) Gets the int value for the attribute in the XML element.
int	getIntElement() Gets the int value for the current element.
long	getLongAttribute(String namespaceUri, String localName) Gets the long value for the attribute in the XML element.
long	getLongElement() Gets the long value for the current element.
T	getNullableAttribute(String namespaceUri, String localName, XmlReadValueCallback<String,T> converter) Gets the nullable value for the attribute in the XML element.
T	getNullableElement(XmlReadValueCallback<String,T> converter) Gets the nullable value for the current element.
String	getStringAttribute(String namespaceUri, String localName) Gets the string value for the attribute in the XML element.
String	getStringElement() Gets the string value for the current element.
XmlToken	nextElement() Iterates to and returns the next START_ELEMENT or END_ELEMENT in the XML stream.
void	processNextElement(XmlElementConsumer callback) Processes the next element in the XML stream.
T	readObject(String localName, XmlReadValueCallback<XmlReader,T> converter) Reads an object from the XML stream.
T	readObject(String namespaceUri, String localName, XmlReadValueCallback<XmlReader,T> converter) Reads an object from the XML stream.
void	skipElement() Skips the current XML element.

Methods inherited from java.lang.Object

clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

Method Details

close

public void close()

Closes the XML stream.

Throws:

XMLStreamException

- If the underlying content store fails to close.

currentToken

public XmlToken currentToken()

Gets the XmlToken that the reader points to currently.

Returns START_DOCUMENT if the reader hasn't begun reading the XML stream. Returns END_DOCUMENT if the reader has completed reading the XML stream.

Returns:

The XmlToken that the reader points to currently.

elementNameMatches

public boolean elementNameMatches(String localName)

Checks if the current element name matches the provided local name.

If the namespace of the current element also needs to be validated use elementNameMatches(String namespaceUri, String localName).

Parameters:

localName - The local name to match.

Returns:

Whether the current element name matches the provided local name.

elementNameMatches

public boolean elementNameMatches(String namespaceUri, String localName)

Checks if the current element namespace URI and name matches the provided namespace URI and local name.

Namespace URI validation replaces null values with XMLConstants#NULL_NS_URI.

Parameters:

namespaceUri - The namespace URI to match.

localName - The local name to match.

Returns:

Whether the current element namespace URI and name matches the provided namespace URI and local name.

fromBytes

public static XmlReader fromBytes(byte[] xml)

Creates an XMLStreamReader-based XmlReader that parses the passed xml.

This uses the XMLStreamReader implementation provided by the default XMLInputFactory#newInstance(). If you need to provide a custom implementation of XMLStreamReader use fromXmlStreamReader(XMLStreamReader reader).

Parameters:

xml - The XML to parse.

Returns:

A new XmlReader instance.

Throws:

XMLStreamException

- If xml is null.

fromReader

public static XmlReader fromReader(Reader xml)

Creates an XmlReader that parses the passed xml.

This uses the XMLStreamReader implementation provided by the default XMLInputFactory#newInstance(). If you need to provide a custom implementation of XMLStreamReader use fromXmlStreamReader(XMLStreamReader reader).

Parameters:

xml - The XML to parse.

Returns:

A new XmlReader instance.

Throws:

XMLStreamException

- If xml is null.

fromStream

public static XmlReader fromStream(InputStream xml)

Creates an XmlReader that parses the passed xml.

This uses the XMLStreamReader implementation provided by the default XMLInputFactory#newInstance(). If you need to provide a custom implementation of XMLStreamReader use fromXmlStreamReader(XMLStreamReader reader).

Parameters:

xml - The XML to parse.

Returns:

A new XmlReader instance.

Throws:

XMLStreamException

- If xml is null.

fromString

public static XmlReader fromString(String xml)

Creates an XmlReader that parses the passed xml.

This uses the XMLStreamReader implementation provided by the default XMLInputFactory#newInstance(). If you need to provide a custom implementation of XMLStreamReader use fromXmlStreamReader(XMLStreamReader reader).

Parameters:

xml - The XML to parse.

Returns:

A new XmlReader instance.

Throws:

XMLStreamException

- If xml is null.

fromXmlStreamReader

public static XmlReader fromXmlStreamReader(XMLStreamReader reader)

Creates an XmlReader that parses the passed xml.

This uses the provided XMLStreamReader implementation to parse the XML.

Parameters:

reader - The XMLStreamReader to parse the XML.

Returns:

A new XmlReader instance.

getBinaryAttribute

public byte[] getBinaryAttribute(String namespaceUri, String localName)

Gets the binary value for the attribute in the XML element.

Parameters:

namespaceUri - Attribute namespace, may be null.

localName - Attribute local name.

Returns:

The binary value for the attribute in the XML element.

getBinaryElement

public byte[] getBinaryElement()

Gets the binary value for the current element.

Returns:

The binary value for the current element.

Throws:

XMLStreamException

- If the binary element cannot be read.

getBooleanAttribute

public boolean getBooleanAttribute(String namespaceUri, String localName)

Gets the boolean value for the attribute in the XML element.

Parameters:

namespaceUri - Attribute namespace, may be null.

localName - Attribute local name.

Returns:

The boolean value for the attribute in the XML element.

getBooleanElement

public boolean getBooleanElement()

Gets the boolean value for the current element.

Returns:

The boolean value for the current element.

Throws:

XMLStreamException

- If the boolean element cannot be read.

getDoubleAttribute

public double getDoubleAttribute(String namespaceUri, String localName)

Gets the double value for the attribute in the XML element.

Parameters:

namespaceUri - Attribute namespace, may be null.

localName - Attribute local name.

Returns:

The double value for the attribute in the XML element.

getDoubleElement

public double getDoubleElement()

Gets the double value for the current element.

Returns:

The double value for the current element.

Throws:

XMLStreamException

- If the double element cannot be read.

getElementLocalName

public String getElementLocalName()

Gets the local name for the current XML element.

Returns:

The local name for the current XML element.

getElementName

public QName getElementName()

Gets the QName for the current XML element.

Code Samples

QName qName = xmlReader.getElementName();
 String localPart = qName.getLocalPart(); // The name of the XML element.
 String namespaceUri = qName.getNamespaceURI(); // The namespace of the XML element.

Returns:

The QName for the current XML element.

getElementNamespaceUri

public String getElementNamespaceUri()

Gets the namespace URI for the current XML element.

If the current element doesn't have a namespace URI, XMLConstants#NULL_NS_URI will be returned.

Returns:

The namespace URI for the current XML element.

getFloatAttribute

public float getFloatAttribute(String namespaceUri, String localName)

Gets the float value for the attribute in the XML element.

Parameters:

namespaceUri - Attribute namespace, may be null.

localName - Attribute local name.

Returns:

The float value for the attribute in the XML element.

getFloatElement

public float getFloatElement()

Gets the float value for the current element.

Returns:

The float value for the current element.

Throws:

XMLStreamException

- If the float element cannot be read.

getIntAttribute

public int getIntAttribute(String namespaceUri, String localName)

Gets the int value for the attribute in the XML element.

Parameters:

namespaceUri - Attribute namespace, may be null.

localName - Attribute local name.

Returns:

The int value for the attribute in the XML element.

getIntElement

public int getIntElement()

Gets the int value for the current element.

Returns:

The int value for the current element.

Throws:

XMLStreamException

- If the int element cannot be read.

getLongAttribute

public long getLongAttribute(String namespaceUri, String localName)

Gets the long value for the attribute in the XML element.

Parameters:

namespaceUri - Attribute namespace, may be null.

localName - Attribute local name.

Returns:

The long value for the attribute in the XML element.

getLongElement

public long getLongElement()

Gets the long value for the current element.

Returns:

The long value for the current element.

Throws:

XMLStreamException

- If the long element cannot be read.

getNullableAttribute

public T getNullableAttribute(String namespaceUri, String localName, XmlReadValueCallback converter)

Gets the nullable value for the attribute in the XML element.

If the attribute doesn't have a value or doesn't exist null will be returned, otherwise the attribute getStringAttribute(String namespaceUri, String localName) is passed to the converter.

Code Samples

try (XmlReader reader = XmlReader.fromString("<root><element attribute=\"1234\"/></root>")) {
     reader.nextElement(); // Progress to <root>
     reader.nextElement(); // Progress to <element>

     // Get the value of the attribute "attribute" as an Integer in a way that allows for the attribute to be
     // missing or have a null value.
     Objects.equals(1234, reader.getNullableAttribute(null, "attribute", Integer::parseInt));

     // This attribute doesn't exist, so null is returned without causing a NumberFormatException (which is what
     // Integer.parseInt throws on a null string being passed).
     Objects.isNull(reader.getNullableAttribute(null, "nonExistentAttribute", Integer::parseInt));
 } catch (XMLStreamException ex) {
     // Do something with the exception
 }

Parameters:

namespaceUri - Attribute namespace, may be null.

localName - Attribute local name.

converter - Function that converts the attribute text value to the nullable type.

Returns:

The converted text value, or null if the attribute didn't have a value.

Throws:

XMLStreamException

- If the nullable attribute cannot be read.

getNullableElement

public T getNullableElement(XmlReadValueCallback converter)

Gets the nullable value for the current element.

If the current element doesn't have a value null will be returned, otherwise the element getStringElement() is passed to the converter.

Code Samples

try (XmlReader reader = XmlReader.fromString("<root><element>1234</element><emptyElement/></root>")) {
     reader.nextElement(); // Progress to <root>
     reader.nextElement(); // Progress to <element>

     // Get the value of the element "element" as an Integer in a way that allows for the element to be missing
     // or have a null value.
     Objects.equals(1234, reader.getNullableElement(Integer::parseInt)); // 1234

     reader.nextElement(); // Progress to <emptyElement>

     // This element doesn't exist, so null is returned without causing a NumberFormatException (which is what
     // Integer.parseInt throws on a null string being passed).
     Objects.isNull(reader.getNullableElement(Integer::parseInt));
 } catch (XMLStreamException ex) {
     // Do something with the exception
 }

Parameters:

converter - Function that converts the element text value to the nullable type.

Returns:

The converted text value, or null if the element didn't have a value.

Throws:

XMLStreamException

- If the nullable element cannot be read.

getStringAttribute

public String getStringAttribute(String namespaceUri, String localName)

Gets the string value for the attribute in the XML element.

Null is returned if the attribute doesn't exist in the XML element.

Parameters:

namespaceUri - Attribute namespace, may be null.

localName - Attribute local name.

Returns:

The string value for the attribute in the XML element, or null if the attribute doesn't exist.

getStringElement

public String getStringElement()

Gets the string value for the current element.

Returns:

The string value for the current element.

Throws:

XMLStreamException

- If the String element cannot be read.

nextElement

public XmlToken nextElement()

Iterates to and returns the next START_ELEMENT or END_ELEMENT in the XML stream.

Returns END_DOCUMENT if iterating to the next element token completes reading of the XML stream.

Returns:

The next START_ELEMENT or END_ELEMENT in the XML stream, or END_DOCUMENT if reading completes.

Throws:

XMLStreamException

- If the next element cannot be determined.

processNextElement

public void processNextElement(XmlElementConsumer callback)

Processes the next element in the XML stream.

The callback will be invoked with the current element's namespace URI, where null is replaced with XMLConstants#NULL_NS_URI, and local name and this XmlReader.

Parameters:

callback - The callback to process the next element.

Throws:

XMLStreamException

- If the next element cannot be processed.

readObject

public T readObject(String localName, XmlReadValueCallback converter)

Reads an object from the XML stream.

Validates that the XmlReader is currently pointing to an START_ELEMENT which has the qualifying name specified by the startTagName.

Code Samples

return xmlReader.readObject(getRootElementName(rootElementName, "Name"), reader -> {
     BlobName result = new BlobName();
     result.encoded = reader.getNullableAttribute(null, "Encoded", Boolean::parseBoolean);
     result.content = reader.getStringElement();

     return result;
 });

Parameters:

localName - The expecting starting local name for the object.

converter - The function that reads the object.

Returns:

An instance of the expected object,

Throws:

XMLStreamException

- If the starting tag isn't XmlToken#START_ELEMENT or the tag doesn't match the expected startTagName

readObject

public T readObject(String namespaceUri, String localName, XmlReadValueCallback converter)

Reads an object from the XML stream.

Validates that the XmlReader is currently pointing to an START_ELEMENT which has the qualifying name specified by the startTagName.

Code Samples

return xmlReader.readObject("http://schemas.microsoft.com/netservices/2010/10/servicebus/connect",
     getRootElementName(rootElementName, "NamespaceInfo"), reader -> {
         NamespaceProperties properties = new NamespaceProperties();

         while (xmlReader.nextElement() != XmlToken.END_ELEMENT) {
             QName qName = xmlReader.getElementName();
             String localPart = qName.getLocalPart();
             String namespaceUri = qName.getNamespaceURI();

             if ("Alias".equals(localPart)
                 && "http://schemas.microsoft.com/netservices/2010/10/servicebus/connect".equals(namespaceUri)) {
                 properties.alias = xmlReader.getStringElement();
             } else if ("CreatedTime".equals(localPart)
                 && "http://schemas.microsoft.com/netservices/2010/10/servicebus/connect".equals(namespaceUri)) {
                 properties.createdTime = OffsetDateTime.parse(xmlReader.getStringElement());
             } else if ("MessagingSKU".equals(localPart)
                 && "http://schemas.microsoft.com/netservices/2010/10/servicebus/connect".equals(namespaceUri)) {
                 properties.messagingSku = MessagingSku.fromString(xmlReader.getStringElement());
             } else if ("MessagingUnits".equals(localPart)
                 && "http://schemas.microsoft.com/netservices/2010/10/servicebus/connect".equals(namespaceUri)) {
                 properties.messagingUnits = xmlReader.getIntElement();
             } else if ("ModifiedTime".equals(localPart)
                 && "http://schemas.microsoft.com/netservices/2010/10/servicebus/connect".equals(namespaceUri)) {
                 properties.modifiedTime = OffsetDateTime.parse(xmlReader.getStringElement());
             } else if ("Name".equals(localPart)
                 && "http://schemas.microsoft.com/netservices/2010/10/servicebus/connect".equals(namespaceUri)) {
                 properties.name = xmlReader.getStringElement();
             } else if ("NamespaceType".equals(localPart)
                 && "http://schemas.microsoft.com/netservices/2010/10/servicebus/connect".equals(namespaceUri)) {
                 properties.namespaceType = NamespaceType.fromString(xmlReader.getStringElement());
             }
         }

         return properties;
     });

Parameters:

namespaceUri - The expecting namespace for the object.

localName - The expecting starting local name for the object.

converter - The function that reads the object.

Returns:

An instance of the expected object,

Throws:

XMLStreamException

- If the starting tag isn't XmlToken#START_ELEMENT or the tag doesn't match the expected startTagName

skipElement

public void skipElement()

Skips the current XML element.

If the currentToken() isn't an START_ELEMENT this is a no-op.

This reads the XML stream until the matching END_ELEMENT is found for the current START_ELEMENT.

Throws:

XMLStreamException

- If skipping the element fails.