XmlSerializable<T> Interface

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:

Returns:

Throws:

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:

Returns:

Throws:

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:

Returns:

Throws:

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:

Returns:

Throws: