azure-docs-sdk-java/docs-ref-autogen/com.azure.xml.XmlSerializable.yml

### YamlMime:JavaType
uid: "com.azure.xml.XmlSerializable"
fullName: "com.azure.xml.XmlSerializable<T>"
name: "XmlSerializable<T>"
nameWithType: "XmlSerializable<T>"
summary: "Indicates that the implementing class can be serialized to and deserialized from XML."
syntax: "public interface **XmlSerializable<T>**"
methods:
- uid: "com.azure.xml.XmlSerializable.<T>fromXml(com.azure.xml.XmlReader)"
  fullName: "com.azure.xml.XmlSerializable<T>.fromXml(XmlReader xmlReader)"
  name: "fromXml(XmlReader xmlReader)"
  nameWithType: "XmlSerializable<T>.fromXml(XmlReader xmlReader)"
  summary: "Reads an XML stream into an object."
  modifiers:
  - "static"
  parameters:
  - description: "The <xref uid=\"com.azure.xml.XmlReader\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlReader\"></xref> being read."
    name: "xmlReader"
    type: "<xref href=\"com.azure.xml.XmlReader?alt=com.azure.xml.XmlReader&text=XmlReader\" data-throw-if-not-resolved=\"False\" />"
  syntax: "public static T <T>fromXml(XmlReader xmlReader)"
  exceptions:
  - description: "If an object fails to be read from the <code>xmlReader</code>."
    type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamException.html\">XMLStreamException</a>"
  desc: "Reads an XML stream into an object.\n\nImplementations of <xref uid=\"com.azure.xml.XmlSerializable\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlSerializable\"></xref> must define this method, otherwise an <xref uid=\"\" data-throw-if-not-resolved=\"false\" data-raw-source=\"UnsupportedOperationException\"></xref> will be thrown.\n\n**Code Samples**\n\n```java\npublic static ResponseAuthor fromXml(XmlReader xmlReader) throws XMLStreamException {\n     // Pass null as the rootElementName to use the default root element name.\n     // Overall, fromXml(XmlReader) is just convenience for fromXml(XmlReader, null).\n     return fromXml(xmlReader, null);\n }\n```"
  returns:
    description: "The object that the XML stream represented, may return null."
    type: "<xref href=\"T?alt=T&text=T\" data-throw-if-not-resolved=\"False\" />"
- uid: "com.azure.xml.XmlSerializable.<T>fromXml(com.azure.xml.XmlReader,java.lang.String)"
  fullName: "com.azure.xml.XmlSerializable<T>.fromXml(XmlReader xmlReader, String rootElementName)"
  name: "fromXml(XmlReader xmlReader, String rootElementName)"
  nameWithType: "XmlSerializable<T>.fromXml(XmlReader xmlReader, String rootElementName)"
  summary: "Reads an XML stream into an object."
  modifiers:
  - "static"
  parameters:
  - description: "The <xref uid=\"com.azure.xml.XmlReader\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlReader\"></xref> being read."
    name: "xmlReader"
    type: "<xref href=\"com.azure.xml.XmlReader?alt=com.azure.xml.XmlReader&text=XmlReader\" data-throw-if-not-resolved=\"False\" />"
  - description: "Optional root element name to override the default defined by the model. Used to support\n cases where the model can deserialize from different root element names."
    name: "rootElementName"
    type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/String.html\">String</a>"
  syntax: "public static T <T>fromXml(XmlReader xmlReader, String rootElementName)"
  exceptions:
  - description: "If an object fails to be read from the <code>xmlReader</code>."
    type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamException.html\">XMLStreamException</a>"
  desc: "Reads an XML stream into an object.\n\nImplementations of <xref uid=\"com.azure.xml.XmlSerializable\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlSerializable\"></xref> must define this method, otherwise an <xref uid=\"\" data-throw-if-not-resolved=\"false\" data-raw-source=\"UnsupportedOperationException\"></xref> will be thrown.\n\nThis differs from <xref uid=\"com.azure.xml.XmlSerializable.<T>fromXml(com.azure.xml.XmlReader)\" data-throw-if-not-resolved=\"false\" data-raw-source=\"#fromXml(XmlReader)\"></xref> in that it allows the root element name to be overridden. This is useful when the model can deserialize from different root element names.\n\n**Code Samples**\n\n```java\npublic static ResponseAuthor fromXml(XmlReader xmlReader, String rootElementName) throws XMLStreamException {\n     // Use XmlReader.readObject as a convenience method for checking that the XmlReader has begun reading, the\n     // current XmlToken is START_ELEMENT, and the element name matches the expected element name (this can just be\n     // matching on the element name or if there is a namespace the namespace qualified element name).\n     //\n     // The following is the equivalent of:\n     // - XmlReader.currentToken() == XmlToken.START_ELEMENT\n     // - XmlReader.getElementName().getNamespaceURI().equals(\"http://www.w3.org/2005/Atom\")\n     // - XmlReader.getElementName().getLocalPart().equals(getRootElementName(rootElementName, \"author\"))\n     //\n     // If XmlReader.readObject(String, ReadValueCallback) was used instead, the namespace check would be omitted.\n     //\n     // The ReadValueCallback is where the actual deserialization of the object occurs. When the ReadValueCallback is\n     // called, the XmlReader is positioned at the start of the element that the object is being deserialized from\n     // (in this case the \"author\" element).\n     return xmlReader.readObject(\"http://www.w3.org/2005/Atom\", getRootElementName(rootElementName, \"author\"),\n         reader -> {\n             ResponseAuthor author = new ResponseAuthor();\n\n             while (xmlReader.nextElement() != XmlToken.END_ELEMENT) {\n                 QName qName = xmlReader.getElementName();\n                 String localPart = qName.getLocalPart();\n                 String namespaceUri = qName.getNamespaceURI();\n\n                 if (\"name\".equals(localPart) && \"http://www.w3.org/2005/Atom\".equals(namespaceUri)) {\n                     author.name = xmlReader.getStringElement();\n                 }\n             }\n\n             return author;\n         });\n }\n```"
  returns:
    description: "The object that the XML stream represented, may return null."
    type: "<xref href=\"T?alt=T&text=T\" data-throw-if-not-resolved=\"False\" />"
- uid: "com.azure.xml.XmlSerializable.toXml(com.azure.xml.XmlWriter)"
  fullName: "com.azure.xml.XmlSerializable<T>.toXml(XmlWriter xmlWriter)"
  name: "toXml(XmlWriter xmlWriter)"
  nameWithType: "XmlSerializable<T>.toXml(XmlWriter xmlWriter)"
  summary: "Writes the object to the passed <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref>."
  modifiers:
  - "default"
  parameters:
  - description: "The <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref> being written to."
    name: "xmlWriter"
    type: "<xref href=\"com.azure.xml.XmlWriter?alt=com.azure.xml.XmlWriter&text=XmlWriter\" data-throw-if-not-resolved=\"False\" />"
  syntax: "public default XmlWriter toXml(XmlWriter xmlWriter)"
  exceptions:
  - description: "If the object fails to be written to the <code>xmlWriter</code>."
    type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamException.html\">XMLStreamException</a>"
  desc: "Writes the object to the passed <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref>.\n\nThe contract for writing XML to <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref> is that the object being written will handle opening and closing its own XML object. So, for objects calling out to other <xref uid=\"com.azure.xml.XmlSerializable\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlSerializable\"></xref> objects for serialization, they'll pass the <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref> to the other <xref uid=\"com.azure.xml.XmlSerializable\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlSerializable\"></xref> object. This way objects writing XML will be self-encapsulated for writing properly formatted XML.\n\n**Code Samples**\n\n```java\n@Override\n public XmlWriter toXml(XmlWriter xmlWriter) throws XMLStreamException {\n     // Pass null as the rootElementName to use the default root element name.\n     // Overall, toXml(XmlWriter) is just convenience for toXml(XmlWriter, null).\n     return toXml(xmlWriter, null);\n }\n```"
  returns:
    description: "The <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref> where the XML was written for chaining."
    type: "<xref href=\"com.azure.xml.XmlWriter?alt=com.azure.xml.XmlWriter&text=XmlWriter\" data-throw-if-not-resolved=\"False\" />"
- uid: "com.azure.xml.XmlSerializable.toXml(com.azure.xml.XmlWriter,java.lang.String)"
  fullName: "com.azure.xml.XmlSerializable<T>.toXml(XmlWriter xmlWriter, String rootElementName)"
  name: "toXml(XmlWriter xmlWriter, String rootElementName)"
  nameWithType: "XmlSerializable<T>.toXml(XmlWriter xmlWriter, String rootElementName)"
  summary: "Writes the object to the passed <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref>."
  modifiers:
  - "abstract"
  parameters:
  - description: "The <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref> being written to."
    name: "xmlWriter"
    type: "<xref href=\"com.azure.xml.XmlWriter?alt=com.azure.xml.XmlWriter&text=XmlWriter\" data-throw-if-not-resolved=\"False\" />"
  - description: "Optional root element name to override the default defined by the model. Used to support\n cases where the model can serialize using different root element names."
    name: "rootElementName"
    type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/java/lang/String.html\">String</a>"
  syntax: "public abstract XmlWriter toXml(XmlWriter xmlWriter, String rootElementName)"
  exceptions:
  - description: "If the object fails to be written to the <code>xmlWriter</code>."
    type: "<a href=\"https://docs.oracle.com/javase/8/docs/api/javax/xml/stream/XMLStreamException.html\">XMLStreamException</a>"
  desc: "Writes the object to the passed <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref>.\n\nThe contract for writing XML to <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref> is that the object being written will handle opening and closing its own XML object. So, for objects calling out to other <xref uid=\"com.azure.xml.XmlSerializable\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlSerializable\"></xref> objects for serialization, they'll pass the <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref> to the other <xref uid=\"com.azure.xml.XmlSerializable\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlSerializable\"></xref> object. This way objects writing XML will be self-encapsulated for writing properly formatted XML.\n\nThis differs from <xref uid=\"com.azure.xml.XmlSerializable.toXml(com.azure.xml.XmlWriter)\" data-throw-if-not-resolved=\"false\" data-raw-source=\"#toXml(XmlWriter)\"></xref> in that it allows the root element name to be overridden. This is useful when the model can serialize using different root element names.\n\n**Code Samples**\n\n```java\n@Override\n public XmlWriter toXml(XmlWriter xmlWriter, String rootElementName) throws XMLStreamException {\n     // The call to XmlSerializable.toXml handles writing the XML start document\n     // (<?xml version=\"1.0\" encoding=\"UTF-8\">).\n     // Write the start of the XML element.\n     xmlWriter.writeStartElement(getRootElementName(rootElementName, \"author\"));\n\n     // Namespace and attribute writing happens after wiring the start of the element. The element start isn't\n     // finished until end element or starting another element is called.\n     xmlWriter.writeNamespace(\"http://www.w3.org/2005/Atom\");\n\n     // Convenience method that writes an entire element with a single API call. This is used when the element\n     // doesn't have any attributes, namespaces, or child elements.\n     xmlWriter.writeStringElement(\"name\", name);\n\n     // Finish writing the XML element. No need to flush as the caller will handle that.\n     return xmlWriter.writeEndElement();\n }\n```"
  returns:
    description: "The <xref uid=\"com.azure.xml.XmlWriter\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlWriter\"></xref> where the XML was written for chaining."
    type: "<xref href=\"com.azure.xml.XmlWriter?alt=com.azure.xml.XmlWriter&text=XmlWriter\" data-throw-if-not-resolved=\"False\" />"
type: "interface"
typeParameters:
- description: "The type of the object that is XML serializable."
  name: "T"
desc: "Indicates that the implementing class can be serialized to and deserialized from XML.\n\nSince deserialization needs to work without an instance of the class, implementing this interface it's assumed the class has static methods <xref uid=\"com.azure.xml.XmlSerializable.<T>fromXml(com.azure.xml.XmlReader)\" data-throw-if-not-resolved=\"false\" data-raw-source=\"#fromXml(XmlReader)\"></xref> and <xref uid=\"com.azure.xml.XmlSerializable.<T>fromXml(com.azure.xml.XmlReader,java.lang.String)\" data-throw-if-not-resolved=\"false\" data-raw-source=\"#fromXml(XmlReader, String)\"></xref> that deserializes an instance of that class. The contract for reading XML from <xref uid=\"com.azure.xml.XmlReader\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlReader\"></xref> is that the initial state of the reader on call will either be a null <xref uid=\"com.azure.xml.XmlToken\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlToken\"></xref> or be <xref uid=\"com.azure.xml.XmlToken.START_ELEMENT\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlToken#START_ELEMENT\"></xref> for the object. So, for objects calling out to other <xref uid=\"com.azure.xml.XmlSerializable\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlSerializable\"></xref> objects for deserialization, they'll pass the reader pointing to the token after the <xref uid=\"com.azure.xml.XmlToken.START_ELEMENT\" data-throw-if-not-resolved=\"false\" data-raw-source=\"XmlToken#START_ELEMENT\"></xref>. This way objects reading XML will be self-encapsulated for reading properly formatted XML. And, if an error occurs during deserialization an <xref uid=\"\" data-throw-if-not-resolved=\"false\" data-raw-source=\"IllegalStateException\"></xref> should be thrown."
metadata: {}
package: "com.azure.xml"
artifact: com.azure:azure-xml:1.1.0