Package com.azure.xml

Class XmlReader

java.lang.Object
com.azure.xml.XmlReader
All Implemented Interfaces:
AutoCloseable
public final class XmlReader extends Object implements AutoCloseable
Reads an XML encoded value as a stream of tokens.

  • Method Details

    • fromBytes

      public static XmlReader fromBytes(byte[] xml) throws XMLStreamException
      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).

      Parameters:
      xml - The XML to parse.
      Returns:
      A new XmlReader instance.
      Throws:
      NullPointerException - If xml is null.
      XMLStreamException - If an XmlReader cannot be instantiated.

    • fromString

      public static XmlReader fromString(String xml) throws XMLStreamException
      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).

      Parameters:
      xml - The XML to parse.
      Returns:
      A new XmlReader instance.
      Throws:
      NullPointerException - If xml is null.
      XMLStreamException - If an XmlReader cannot be instantiated.

    • fromStream

      public static XmlReader fromStream(InputStream xml) throws XMLStreamException
      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).

      Parameters:
      xml - The XML to parse.
      Returns:
      A new XmlReader instance.
      Throws:
      NullPointerException - If xml is null.
      XMLStreamException - If an XmlReader cannot be instantiated.

    • fromReader

      public static XmlReader fromReader(Reader xml) throws XMLStreamException
      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).

      Parameters:
      xml - The XML to parse.
      Returns:
      A new XmlReader instance.
      Throws:
      NullPointerException - If xml is null.
      XMLStreamException - If an XmlReader cannot be instantiated.

    • 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.
      Throws:
      NullPointerException - If reader is null.

    • currentToken

      public XmlToken currentToken()
      Gets the XmlToken that the reader points to currently.

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

      Returns:
      The XmlToken that the reader points to currently.

    • nextElement

      public XmlToken nextElement() throws XMLStreamException
      Iterates to and returns the next XmlToken.START_ELEMENT or XmlToken.END_ELEMENT in the XML stream.

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

      Returns:
      The next XmlToken.START_ELEMENT or XmlToken.END_ELEMENT in the XML stream, or XmlToken.END_DOCUMENT if reading completes.
      Throws:
      XMLStreamException - If the next element cannot be determined.

    • close

      public void close() throws XMLStreamException
      Closes the XML stream.
      Specified by:
      close in interface AutoCloseable
      Throws:
      XMLStreamException - If the underlying content store fails to close.

    • 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.
      Throws:
      IllegalStateException - If the currentToken() isn't XmlToken.START_ELEMENT or XmlToken.END_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.

    • getElementLocalName

      public String getElementLocalName()
      Gets the local name for the current XML element.
      Returns:
      The local name for the current XML element.

    • 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, String).

      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.

    • processNextElement

      public void processNextElement(XmlElementConsumer callback) throws XMLStreamException
      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.

    • 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.
      Throws:
      IllegalStateException - If currentToken() isn't XmlToken.START_ELEMENT.

    • 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.

    • 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.

    • 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.

    • 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.

    • 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.

    • 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.

    • getNullableAttribute

      public <T> T getNullableAttribute(String namespaceUri, String localName, XmlReadValueCallback<String,T> converter) throws XMLStreamException
      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, String) 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
 }
      Type Parameters:
      T - Type of the attribute.
      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.

    • getStringElement

      public String getStringElement() throws XMLStreamException
      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.

    • getBinaryElement

      public byte[] getBinaryElement() throws XMLStreamException
      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.

    • getBooleanElement

      public boolean getBooleanElement() throws XMLStreamException
      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.

    • getDoubleElement

      public double getDoubleElement() throws XMLStreamException
      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.

    • getFloatElement

      public float getFloatElement() throws XMLStreamException
      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.

    • getIntElement

      public int getIntElement() throws XMLStreamException
      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.

    • getLongElement

      public long getLongElement() throws XMLStreamException
      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.

    • getNullableElement

      public <T> T getNullableElement(XmlReadValueCallback<String,T> converter) throws XMLStreamException
      Gets the nullable value for the current element.

      If the current element doesn't have a value null will be returned, otherwise the element text value 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
 }
      Type Parameters:
      T - Type of the element.
      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> T readObject(String localName, XmlReadValueCallback<XmlReader,T> converter) throws XMLStreamException
      Reads an object from the XML stream.

      Validates that the XmlReader is currently pointing to an XmlToken.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;
 });
      Type Parameters:
      T - Type of the object.
      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:
      IllegalStateException - If the starting tag isn't XmlToken.START_ELEMENT or the tag doesn't match the expected startTagName
      XMLStreamException - If the object cannot be read.

    • readObject

      public <T> T readObject(String namespaceUri, String localName, XmlReadValueCallback<XmlReader,T> converter) throws XMLStreamException
      Reads an object from the XML stream.

      Validates that the XmlReader is currently pointing to an XmlToken.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;
     });
      Type Parameters:
      T - Type of the object.
      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:
      IllegalStateException - If the starting tag isn't XmlToken.START_ELEMENT or the tag doesn't match the expected startTagName
      XMLStreamException - If the object cannot be read.

    • skipElement

      public void skipElement() throws XMLStreamException
      Skips the current XML element.

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

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

      Throws:
      XMLStreamException - If skipping the element fails.