Dela via

XmlReader Class

  • Reference
Package:
com.azure.xml
Maven Artifact:
com.azure:azure-xml:1.1.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
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.
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 close()

Closes the XML stream.
XmlToken currentToken()

Gets the XmlToken that the reader points to currently.
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.
QName getElementName()

Gets the QName 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.
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 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

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.

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

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.

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.

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.

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.

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.

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.

Applies to