Software AG Products 10.7 | Integrating On-Premises and Cloud Applications | Integration Cloud | Built-In Services | Built-In Services | documentToXMLString
 
documentToXMLString
Converts a document to xml content string. This service will recurse through a given document and build an XML representation from the elements within it. Key names are turned into XML elements, and the key values are turned into the contents of those elements.
This service will convert the following document:
To an XML document string, whose content looks like:
<?xml version="1.0" ?>
<tns:AcctInfo>
xmlns:tns="http://localhost/DerivedAddress/schema.xsd"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<name>Midwest Extreme Sports</name>
<rep>Laura M. Sanchez</rep>
<acctNum type=platinum>G97041A</acctNum>
<phoneNum cc=011>216-741-7566</phoneNum>
<address country=USA>
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
</address>
<address country=USA xsi:type="tns:DerivedAddress">
<street1>10211 Brook Road</street1>
<city>Cleveland</city>
<state>OH</state>
<postalCode>22130</postalCode>
<landMark>Besides Ohio River-Bank Square</landMark>
<telNo>001222555</telNo>
</address>
<serialNum>19970523A</serialNum>
<serialNum>20001106G</serialNum>
<serialNum>20010404K</serialNum>
</tns:AcctInfo>
Input Parameters
document
Document. Document that is to be converted to XML. If you want to produce a valid XML document (one with a single root node), document must contain only one top-level document that is, a single document. The name of that document will serve as the name of the XML document's root element. If you need to produce an XML fragment, for example, a loose collection of elements that are not encompassed within a single root element, then document can contain multiple top level elements.
nsDecls [ ]
Document. Optional. Namespaces associated with any namespace prefixes that are used in the key names in document. Each entry in nsDecls represents a namespace prefix/URI pair, where a key name represents a prefix and the value of the key specifies the namespace URI. For example, to define the URIs associated with two prefixes called GSX and TxMon, you would set nsDecls as follows:
For each prefix specified in nsDecls, this service generates an xmlns attribute and inserts it into the top-most element of the resulting XML String. For example, if nsDecls had the two keys shown above, this service would insert the following attribute into the root element of the XML String:
xmlns:gsx="http://www.gsx.com"
xmlns:TxMon="http:www.acrtrak/txMonitor"
Alternatively, you can declare a namespace by including an @xmlns key in document. If you were not using the @ character to designate attributes, use the correct attribute prefix in your code.
Parameters for nsDecls [ ] are:
prefix: Key name.
uri: Key value.
addHeader
String. Optional.
Flag specifying whether the header element <?xml version="1.0"?> is to be included in the resulting XML String.
Set to:
true to include the header. This is the default.
false to omit the header. Omit the header to generate an XML fragment or to insert a custom header.
attrPrefix
String Optional. Prefix that designates keys containing attributes. The default prefix is "@".
For example, if you set attrPrefix to ATT_ and document contained the following element:
documentToXMLString would convert the ATT_currency key to the attribute, currency=dollars, in the <tx> element as shown below:
<tx currency=dollars>
<acct>cash</acct>
<amt>120.00</amt>
</tx>
encode
String Optional. Flag indicating whether to HTML-encode the data. Set this parameter to true if your XML data contains special characters, including the following: < > & " '
Set to:
*true to HTML-encode the data.
For example, the string expression 5 < 6 would be converted to <expr>5 &lt; 6</expr>, which is valid.
If you do not want a leading & (ampersand) character encoded when it appears as part of a character or entity reference, set preserveRefs to true.
*false to not HTML-encode the data. This is the default.
For example, the string expression 5 < 6would be converted to <expr>5 < 6</expr>, which is invalid.
preserveRefs
String Optional. Flag indicating whether the leading & (ampersand) of a well-formed entity or character reference is left as & or further encoded as &amp; when the data is to be HTML-encoded (encode is set to true).
Set to:
*true to preserve the leading & (ampersand) in an entity or character reference when the service HTML-encodes the data.
*false to encode the leading & (ampersand) as &amp; when the & appears in an entity or character reference. This is the default.
The service ignores the value of preseveRefs when encode is set to false.
enforceLegalXML
String Optional. Flag indicating whether the service throws an exception when document contains multiple root elements or illegal XML tag names. Set to:
*true to throw an exception if document would produce an XML String containing multiple root elements and/or illegal XML tag names.
*false to allow the resulting XML String to contain multiple root elements and/or illegal XML tag names. You would use this setting, for example, to create an XML fragment composed of multiple elements that were not all enclosed within a root element. This is the default.
Output Parameters
xmlString
Object. XML document string produced from document.
Usage Notes
If you are building a Document that will be converted to an XML String, keep the following points in mind:
If you want to generate a simple element that contains only a character value, represent it with a String element in document as shown below:
If you want to generate an element that contains children, represent with a document in the document as shown below:
If you want to generate a simple element that contains a character value and one or more attributes, you must represent it as a document that has one key for each attribute and a key named *body that contains the element's value.
For example, if you want to produce the following element:
<phoneNum cc=011>216-741-7566</phoneNum>
You would include the following in document:
To include namespaces, ensure that you do the following:
Include the appropriate namespace prefix in the key names in document. For example, to produce an element called acctNum that belongs to a namespace that is represented by the "GSX" prefix, you would include a key named GSX:acctNum in document.
Define the URIs for the prefixes that appear in document. You can do this through nsDecls or by including an @xmlns key in the element where you want the xmlns attribute to be inserted.