Export-related methods on an XML element

Each XML element provides several methods to serialize its value.

Note: Nillable elements (nillable="true") with a value of null are skipped and are not exported. This behavior occurs even if the element is required (minOccurs="1").

To ensure the correct serialization of XML elements that contain characters with high Unicode code points, best practice is to test serialized values that contain non-English characters.

Exporting bytes

The bytes method returns an array of bytes (the type byte[]) that contains the UTF-8-encoded bytes in the XML. Generally speaking, the bytes method is the best approach for serializing the XML.

var ba = element.bytes()

The method has no required arguments, but can be customized by passing an optional argument of an XmlSerializationOptions object.

Code that sends XML with a transport that understands only character data and not byte data must always base-64 encode the bytes to compactly and safely encode binary data.

var base64String = gw.util.Base64Util.encode(element.bytes())

Base-64 encoded bytes can be decoded with the decode method.

var bytes = gw.util.Base64Util.decode(base64String)
Note: For example, for PolicyCenter messaging, the payload field in a Message entity is type String.

Printing to standard output stream

The print method serializes the element to the standard output stream (System.out).

element.print()

The method has no required arguments, but can be customized by passing an optional argument of an XmlSerializationOptions object.

Writing to a specific output stream

The writeTo method writes to an output stream (java.io.OutputStream). The output stream remains open and is not closed.

The method accepts a single required argument of an OutputStream object. Serialization can be customized by passing an optional second argument of an XmlSerializationOptions object.

Output to string with XML header

The asUTFString method serializes the element to a String object, with a header line that is compatible with UTF-8 encoding.

var s = element.asUTFString()
Important: Although the asUTFString method is helpful for debugging use, the asUTFString method is not the best way to export XML safely to external systems. Instead, it is usually best to use the XML element’s bytes method to produce an array of bytes.

The asUTFString method outputs the node as a String value that contains XML, with a header suitable for later export to UTF-8 or UTF-16 encoding. The generated XML header does not specify the encoding. In the absence of a specified encoding, all XML parsers must detect the encoding (UTF-8 or UTF-16). The existence of a byte order mark at the beginning of the document tells the parser what encoding to use.

The method has no required arguments. However, it can be customized by passing an optional argument for an XmlSerializationOptions object.

Warning: Although the asUTFString method adds an XML header that can specify the encoding, there is no automatic encoding transformation into bytes. To write this String object to another system or a file, you must be careful to do the correct encoding transformation on export. Also be aware that if you use the optional XmlSerializationOptions argument, you could choose another encoding. However, just like for the default asUTFString method signature, which assumes UTF-8 encoding, the encoding choice only affects the serialized header, not the encoding of the output bytes.

XML serialization options and methods

The XmlSerializationOptions type exposes properties and also special methods for each one of these properties. Each method has the prefix with followed by the property name. For example, withSort. The method takes one argument of the type of that property.

These methods return the XmlSerializationOptions object again, so the methods are chainable. This behavior supports combining multiple method invocations in a single chained statement.

var opts = new gw.xml.XmlSerializationOptions().withSort(false).withValidate(false)

In addition, the withEncoding property has a secondary method signature that takes the Java short name for the encoding. You can set the encoding by either of the following operations.

  • Use the withEncoding method and pass a standard Java encoding name as a String, such as "Big5".
  • Set the Encoding property to a raw character set object for the encoding. You can use the static method Charset.forName(ENCODING_NAME) to get the desired static instance of the character set object. For example, pass "Big5".

See also