你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
XmlSerializable<T> Interface
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
Xml |
toXml(XmlWriter xmlWriter)
Writes the object to the passed XmlWriter. |
|
abstract
Xml |
toXml(XmlWriter xmlWriter, String rootElementName)
Writes the object to the passed XmlWriter. |
Method Details
fromXml
public static T
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:
xmlReader.
fromXml
public static T
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:
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:
Returns:
Throws:
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:
Returns:
Throws:
xmlWriter.
