Parsing XML data into an XML element

The XmlElement class contains static methods for parsing XML data into a graph of XmlElement objects. Parsing means to convert serialized XML data into a more complex in-memory representation of the document. All these methods have the name parse. There are multiple methods because Gosu supports parsing from several different sources of XML data.

Important: For each source of data, there is an optional method variant that modifies the way Gosu parses the XML. Gosu encapsulates these options in an instance of the type XmlParseOptions. The XmlParseOptions specifies additional schemas that resolve schema components for the input instance XML document. Typical code does not need this. Use this if your XML data contains references to schema components that are neither directly nor indirectly imported by the schema of the context type.

For example, the following example parses XML contained in a String into an XmlElement object, and then prints the parsed XML data:

var a = XmlElement.parse("<Test123/>")
a.print()

If you are using an XSD, call the parse method directly on your XSD-based node, which is a subclass of XmlElement. For example:

var a = docexamples.gosu.xml.demoattributes.Element1.parse(xmlDataString)

The following table lists the signatures of the parse method.

Parameters

Description

byte[]

byte[], XmlParseOptions

Parses XML from a byte array, with optional parsing options.

java.io.File

java.io.File, XmlParseOptions

Parses XML from a file, with optional parsing options.

java.io.InputStream

java.io.InputStream, XmlParseOptions

Parses XML from an InputStream, with optional parsing options.

java.io.Reader

java.io.Reader, XmlParseOptions

Parses XML from a reader, which is an object for reading character streams. Optionally, add parsing options.

Warning: Because this uses character data, not bytes, the character encoding is irrelevant. Any encoding header at the top of the file has no effect. It is strongly recommended to treat XML as binary data, not as String data. If your code needs to send XML with a transport that only understands character (not byte) data, always Base64 encode the bytes. (From Gosu, use the syntax: Base64Util.encode(element.bytes())

String

String, XmlParseOptions

Parses XML from a String, with optional parsing options.

Important: Because this uses character data, not bytes, the character encoding is irrelevant. Any encoding header at the top of the file has no effect. It is strongly recommended to treat XML as binary data, not as String data. If your code needs to send XML with a transport that only understands character (not byte) data, always Base64 encode the bytes. From Gosu, create the syntax: Base64Util.encode(element.bytes())

Checking XML well-formedness and validation during parsing

For XSD-based XML elements, Gosu has the following behavior:

  • Gosu checks for well-formedness. For example, Gosu checks that the XML contains no unclosed tags or other structural errors.
  • Gosu always validates the XML against the XSD.

For non-XSD-based XML elements:

  • Gosu checks for well-formedness.
  • If the XML parse options object includes references to other schemas, Gosu validates the XML against those schemas.

If the XML document fails any of these tests, Gosu throws an exception.

See also