XmlSerializable<T> Interface

Package:

com.azure.xml

Maven Artifact:

com.azure:azure-xml:1.1.0

Type Parameters

T

The type of the object that is XML serializable.

public interface XmlSerializable

Indicates that the implementing class can be serialized to and deserialized from XML.

Since deserialization needs to work without an instance of the class, implementing this interface it's assumed the class has static methods fromXml(XmlReader xmlReader) and fromXml(XmlReader xmlReader, String rootElementName) that deserializes an instance of that class. The contract for reading XML from XmlReader is that the initial state of the reader on call will either be a null XmlToken or be START_ELEMENT for the object. So, for objects calling out to other XmlSerializable<T> objects for deserialization, they'll pass the reader pointing to the token after the START_ELEMENT. This way objects reading XML will be self-encapsulated for reading properly formatted XML. And, if an error occurs during deserialization an IllegalStateException should be thrown.

Method Summary

Modifier and Type	Method and Description
static T	fromXml(XmlReader xmlReader) Reads an XML stream into an object.
static T	fromXml(XmlReader xmlReader, String rootElementName) Reads an XML stream into an object.
default XmlWriter	toXml(XmlWriter xmlWriter) Writes the object to the passed XmlWriter.
abstract XmlWriter	toXml(XmlWriter xmlWriter, String rootElementName) Writes the object to the passed XmlWriter.

Method Details

fromXml

public static T fromXml(XmlReader xmlReader)

Reads an XML stream into an object.

Implementations of XmlSerializable<T> must define this method, otherwise an UnsupportedOperationException will be thrown.

Code Samples

public static ResponseAuthor fromXml(XmlReader xmlReader) throws XMLStreamException {
     // Pass null as the rootElementName to use the default root element name.
     // Overall, fromXml(XmlReader) is just convenience for fromXml(XmlReader, null).
     return fromXml(xmlReader, null);
 }

Parameters:

xmlReader - The XmlReader being read.

Returns:

The object that the XML stream represented, may return null.

Throws:

XMLStreamException

- If an object fails to be read from the xmlReader.

fromXml

public static T fromXml(XmlReader xmlReader, String rootElementName)

Reads an XML stream into an object.

Implementations of XmlSerializable<T> must define this method, otherwise an UnsupportedOperationException will be thrown.

This differs from fromXml(XmlReader xmlReader) in that it allows the root element name to be overridden. This is useful when the model can deserialize from different root element names.

Code Samples

public static ResponseAuthor fromXml(XmlReader xmlReader, String rootElementName) throws XMLStreamException {
     // Use XmlReader.readObject as a convenience method for checking that the XmlReader has begun reading, the
     // current XmlToken is START_ELEMENT, and the element name matches the expected element name (this can just be
     // matching on the element name or if there is a namespace the namespace qualified element name).
     //
     // The following is the equivalent of:
     // - XmlReader.currentToken() == XmlToken.START_ELEMENT
     // - XmlReader.getElementName().getNamespaceURI().equals("http://www.w3.org/2005/Atom")
     // - XmlReader.getElementName().getLocalPart().equals(getRootElementName(rootElementName, "author"))
     //
     // If XmlReader.readObject(String, ReadValueCallback) was used instead, the namespace check would be omitted.
     //
     // The ReadValueCallback is where the actual deserialization of the object occurs. When the ReadValueCallback is
     // called, the XmlReader is positioned at the start of the element that the object is being deserialized from
     // (in this case the "author" element).
     return xmlReader.readObject("http://www.w3.org/2005/Atom", getRootElementName(rootElementName, "author"),
         reader -> {
             ResponseAuthor author = new ResponseAuthor();

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

                 if ("name".equals(localPart) && "http://www.w3.org/2005/Atom".equals(namespaceUri)) {
                     author.name = xmlReader.getStringElement();
                 }
             }

             return author;
         });
 }

Parameters:

xmlReader - The XmlReader being read.

rootElementName - Optional root element name to override the default defined by the model. Used to support cases where the model can deserialize from different root element names.

Returns:

The object that the XML stream represented, may return null.

Throws:

XMLStreamException

- If an object fails to be read from the xmlReader.

toXml

public default XmlWriter toXml(XmlWriter xmlWriter)

Writes the object to the passed XmlWriter.

The contract for writing XML to XmlWriter is that the object being written will handle opening and closing its own XML object. So, for objects calling out to other XmlSerializable<T> objects for serialization, they'll pass the XmlWriter to the other XmlSerializable<T> object. This way objects writing XML will be self-encapsulated for writing properly formatted XML.

Code Samples

@Override
 public XmlWriter toXml(XmlWriter xmlWriter) throws XMLStreamException {
     // Pass null as the rootElementName to use the default root element name.
     // Overall, toXml(XmlWriter) is just convenience for toXml(XmlWriter, null).
     return toXml(xmlWriter, null);
 }

Parameters:

xmlWriter - The XmlWriter being written to.

Returns:

The XmlWriter where the XML was written for chaining.

Throws:

XMLStreamException

- If the object fails to be written to the xmlWriter.

toXml

public abstract XmlWriter toXml(XmlWriter xmlWriter, String rootElementName)

Writes the object to the passed XmlWriter.

The contract for writing XML to XmlWriter is that the object being written will handle opening and closing its own XML object. So, for objects calling out to other XmlSerializable<T> objects for serialization, they'll pass the XmlWriter to the other XmlSerializable<T> object. This way objects writing XML will be self-encapsulated for writing properly formatted XML.

This differs from toXml(XmlWriter xmlWriter) in that it allows the root element name to be overridden. This is useful when the model can serialize using different root element names.

Code Samples

@Override
 public XmlWriter toXml(XmlWriter xmlWriter, String rootElementName) throws XMLStreamException {
     // The call to XmlSerializable.toXml handles writing the XML start document
     // (<?xml version="1.0" encoding="UTF-8">).
     // Write the start of the XML element.
     xmlWriter.writeStartElement(getRootElementName(rootElementName, "author"));

     // Namespace and attribute writing happens after wiring the start of the element. The element start isn't
     // finished until end element or starting another element is called.
     xmlWriter.writeNamespace("http://www.w3.org/2005/Atom");

     // Convenience method that writes an entire element with a single API call. This is used when the element
     // doesn't have any attributes, namespaces, or child elements.
     xmlWriter.writeStringElement("name", name);

     // Finish writing the XML element. No need to flush as the caller will handle that.
     return xmlWriter.writeEndElement();
 }

Parameters:

xmlWriter - The XmlWriter being written to.

rootElementName - Optional root element name to override the default defined by the model. Used to support cases where the model can serialize using different root element names.

Returns:

The XmlWriter where the XML was written for chaining.

Throws:

XMLStreamException

- If the object fails to be written to the xmlWriter.