Integration Server 10.5 | Built-In Services Reference Guide | XML Folder | Summary of Elements in this Folder | pub.xml:loadEnhancedXMLNode
 
pub.xml:loadEnhancedXMLNode
WmPublic. Retrieves an XML document via HTTP or HTTPS, parses it using the enhanced XML parser, and produces an org.w3c.dom.Node object.
An DOM node is a special representation of an XML document that can be consumed by any program that uses standard DOM APIs. The pub.xml:xmlNodeToDocument service and the pub.xmldata.domeNodetoXMLData service can accept a DOM object as input.
Input Parameters
url
String The URL of the document you want to load. This string must begin with http: or https:. For example:
http://www.rubicon.com/orders/orders.html
—OR—
https://localhost:5555/WmPublic/index.html
You can include a query string (for example, a collection of "name=value" pairs) with the string that you specify. However, you might want to use the data variable for this type of information instead. It is usually a more practical place for "name=value" data, because it allows you to link individual variables in the query string.
method
String Optional. Set this value to specify the HTTP method (GET or POST) that you want the target server to execute on the resource specified in url. This value determines the way in which pub.xml:loadEnhancedXMLNode submits data values (if any) to the resource identified in url.
*If you set method to get, pub.xml:loadEnhancedXMLNode appends the values you specify in data to the value in url. (Note that only certain data elements are valid when you use the GET method). The default is get.
*If you set method to post, pub.xml:loadEnhancedXMLNode sends the values in data in the body of the HTTP or HTTPS request.
auth
Document Optional. Authentication and authorization information that pub.xml:loadEnhancedXMLNode will use if the requested resource is protected.
Note:
If you include your data with the string in url, do not specify a value in data.
Key
Description
type
String Type of authentication pub.xml:loadEnhancedXMLNode will use to submit this request. Leave this field blank, as the only option currently available is basic HTTP authentication.
user
String User name that pub.xml:loadEnhancedXMLNode will submit if the requested resource is protected.
The user name must have authority to access the resource specified in url.
This value defaults to the value of watt.net.httpUser in the server's configuration file (server.cnf).
pass
String Password associated with the user name specified in user. If the user does not require a password, leave pass empty.
This value defaults to the value of watt.net.httpPass in the server's configuration file (server.cf).
data
Document Optional. The data that you want pub.xml:loadEnhancedXMLNode to submit with the request. Specify data using one or more of the following elements.
Note:
When you use more than one element to submit data, args is appended first, table is appended second, and string is appended last.
Key
Description
args
Document Optional. Specifies name=value pairs that pub.xml:loadEnhancedXMLNode is to submit to the resource in url.
You can use args to submit data via either the POST or GET method.
To specify data using args, create one element for each name=value pair that you want to submit, where the key represents the name portion of the pair and the value represents the value portion of the pair.
Note that when you use args, pub.xml:loadEnhancedXMLNode will automatically:
*URL-encode name=value pair, so you do not need to URL-encode the values you specify in args.
*Insert the "&" character between pairs, so you do not need to include it in args.
*Prefix the entire query string with the "?" character if it submits the data in args via a GET. You do not need to include this character in args.
When you submit data using the args variable, Integration Server automatically sets the value of the Content-Type header to application/x-www-form-urlencoded. If you want to explicitly specify a different Content-Type, you must submit your data using the string or bytes variable.
table
String Table Optional. Specifies data that pub.xml:loadEnhancedXMLNode will use to construct a query string to submit to the resource specified in url.
table is similar to args, but it allows you to submit unnamed values in a query string, not just name=value pairs.
To specify data using table, create one row for each value that you want to submit, where:
*The contents of column 0 represent the name portion of the pair (leave this column null to submit an unnamed value, and...
*The contents of column 1 represent the value portion of the pair.
When you submit data using the table variable, the Integration Server automatically sets the value of the Content-Type header to application/x-www-form-urlencoded. If you want to explicitly specify a different Content-Type, you must submit your data using the string or bytes variable.
Note that when you use table, pub.xml:loadEnhancedXMLNode will automatically:
*URL-encode name=value pair, so you do not need to URL-encode the values you specify in table.
*Insert the "&" character between the pairs (or unnamed values) that it constructs, so you do not need to include it in table.
*Prefix the entire query string with the "?" character if it submits the data in table via the GET method. You do not need to include this character in table.
string
String Optional. Text that you want pub.xml:loadEnhancedXMLNode to submit to the resource in url.
You can use string to submit data via either the POST or GET method.
If you use string to specify your data, make sure that you specify the string exactly as you want it presented in the HTTP request. (If you are using the GET method, make sure you URL-encode the contents of string). When performing a POST the string is submitted to the resource as the body of the document.
bytes
byte[ ] Optional. Data that pub.xml:loadEnhancedXMLNode is to submit to the resource in url. You can use bytes only to submit data via the POST method.
Note:
When you use bytes and another element (args, table, or string) to submit data with pub.xml:loadEnhancedXMLNode, the service appends the data from the args, table, or string element to url. The service appends args to url first, table second, and string last. The service encodes the data from the bytes element in the body of the post.
stream
java.io.InputStream Optional. Data that pub.xml:loadEnhancedXMLNode is to submit to the resource in url. You can use stream only to submit data via the POST method.
Note:
When you use stream and another element (args, table, or string) to submit data with pub.xml:loadEnhancedXMLNode, the service appends the data from the args, table, or string element to url. The service appends args to url first, table second, and string last. The service encodes the data from the stream element in the body of the post. If stream is specified, bytes is ignored.
encoding
String Optional. Name of a registered IANA character set.
headers
Document Optional. Fields that you want to explicitly override in the HTTP request header issued by pub.xml:loadEnhancedXMLNode.
Specify one element for each header field that you want to set, where the element's name represents the name of the header field, and the element's value represents the value of that header field.
If headers is not set, pub.xml:loadEnhancedXMLNode will use its default header values.
Note:
You do not need to type a colon after the field name because pub.xml:loadEnhancedXMLNode will automatically insert the colon when it inserts this field into the request header.
If you want to assign specific values to header fields used by pub.xml:loadEnhancedXMLNode, keep the following points in mind:
*When you specify the value of a header field, you override whatever default value webMethods Integration Server is configured to use for HTTP requests. For example, if you set the User-Agent header field to B2B/3.0, the server uses that value instead of the default value specified by the watt.net.userAgent parameter.
*The pub.xml:loadEnhancedXMLNode service automatically determines the value of the Content-Length header field. You cannot specify a value for Content-Length.
*Be aware that when you submit data using the args or table elements, pub.xml:loadEnhancedXMLNode automatically sets the Content-Type header field to application/x-www-formurlencoded. You cannot override this setting using the headers variable. If you want to explicitly specify a content type in headers, make sure to use the string or bytes element to submit your data, not args or table.
*Certain header fields are automatically derived from other input parameters assigned to pub.xml:loadEnhancedXMLNode. For example, the Authorization header field is automatically derived from your auth parameter setting. Except for the Content-Length header field and the Content-Type header field (which, as described above, you cannot override when submitting data via args or table), a value that you specify in headers overrides the value that pub.xml:loadEnhancedXMLNode might otherwise derive from other parameter settings.
*The pub.xml:loadEnhancedXMLNode service does not validate data that you specify in headers. It simply passes it on to the target server in the request header. Make sure you specify header field names and their values correctly. For a complete list of valid request header fields, see http://www.w3.org for the latest HTTP specification published by the W3C.
*To specify request headers in headers, create a string element for each header that you want to specify, where:
*The name of the element defines the name header field (for example, User-Agent, If- Modified-Since, Mail_Address), and…
*The value of the element specifies the value you want assigned to that field.
encoding
String Optional. Character set in which the returned document is encoded. The parser requires this value in order to interpret a document correctly. Set to:
*autoDetect to determine the document's character set from the document, where UTF-8 is the default character set for XML.
*The name of a registered IANA character set to decode the document using that character set (for example, ISO-8859-1).
failOnHTTPError
String Optional. Determines whether pub.xml:loadEnhancedXMLNode will fail (throw an exception) if the requested URL is not loaded correctly based on an HTTP status code. This parameter allows for customized error handling of the load failure. Set to:
*true to throw a service exception if the URL is not loaded as indicated by an HTTP status code between 400 and 599, inclusive.
*false to ignore HTTP errors. If there is an error, pub.xml:loadEnhancedXMLNode returns status and statusMessage. This is the default.
inputProcessing
Document. Optional. Contains a set of input parameters that instruct Integration Server how to read the XML document. The fields are comparable to those in the javax.xml.stream.XMLInputFactory class.
Key
Description
isValidating
String Optional. Determines whether Integration Server performs DTD validation. Set to:
*true to perform DTD validation.
*false to disable DTD validation. This is the default.
isNamespaceAware
String Optional. Determines whether Integration Server provides namespace processing for XML 1.0 support while parsing the XML document. Set to:
*true to enable namespace processing. This is the default.
*false to disable namespace processing.
isCoalescing
String Optional. Determines whether Integration Server coalesces adjacent character data while parsing the XML document. Set to:
*true to coalesce adjacent character data.
*false to indicate that Integration Server does not coalesce adjacent character data. This is the default.

isReplacingEntity References
String Optional. Determines whether, while parsing the XML document, Integration Server replaces internal entity references with replacement text and treats them as characters. Set to:
*true to replace entity references.
*false to indicate entity references will not be replaced. This is the default.

isSupporting ExternalEntities
String Optional. Determines whether Integration Server resolves external parsed entities while parsing the XML document. Set to:
*true to resolve external parsed entities.
*false to indicate Integration Server does not resolve external parsed entities.
The JVM in which Integration Server runs determines the default.
supportDTD
String Optional. Determines whether Integration Server supports DTDs while parsing the XML document. Set to:
*true to support DTDs while parsing the XML document.
*false to disable support of DTDs while parsing the XML document. This is the default.
partitionSize
String Optional. Specifies the size, measured in bytes, of the partitions on the heap where the enhanced XML parser stores parsed document information. Specify a suffix of “k” to indicate kilobytes or “m” to indicate megabytes. For example, 10k or 10m.
If you do not specify a value, Integration Server uses the default partition size value specified on the Settings > Enhanced XML Parsing screen in Integration Server Administrator.
Output Parameters
node
org.w3c.dom.Node Conditional. XML node representing the returned ML document.
The pub.xml:loadEnhancedXMLNode service returns node only when Integration Server parses the XML document successfully.
status
String Conditional. The HTTP status code returned by the target server if an HTTP error occurs when loading the requested URL.
The pub.xml:loadEnhancedXMLNode service returns status when an HTTP error occurs and failOnHTTPError is set to false.
statusMessage
String Conditional. The HTTP status message returned by the target server if an HTTP error occurs when loading the requested URL.
The pub.xml:loadEnhancedXMLNode service returns statusMessage when an HTTP error occurs and failOnHTTPError is set to false.
Usage Notes
If pub.xml:loadEnhancedXMLNode does not receive a response within the timeout period specified in the server's watt.net.timeout parameter, it will throw an exception. For information about the watt.net.timeout parameter, see webMethods Integration Server Administrator’s Guide .
Use the pub.xml:loadXMLNode service to load an XML document and convert it to an XML node using the legacy XML parser. For more information about the legacy XML parser and the enhanced XML parser, see webMethods Integration Server Administrator’s Guide.
Keep the following information in mind when specifying a partitionSize
*The partitionSize is a hint for the enhanced XML parser so that it can estimate the amount of heap space needed to parse the document. Often, it not possible to determine the size of an inbound XML document before parsing.
*As a general rule, Software AG recommends a partitionSize that is 1/2 the size of the unparsed XML document.
*A partitionSize that is considerably larger than 1/2 the size of the unparsed XML document causes the enhanced XML parser to consume more heap space than necessary but might also improve throughput. However, this can impact the overall performance of Integration Server.
*A partitionSize that is considerably smaller than 1/2 the size of the unparsed XML document causes the enhanced XML parser to create a large number of partitions to parse the document. While this might use less heap space, it may reduce the throughput of the parser.
*A partitionSize that is three times smaller or three times larger than 1/2 the size of the unparsed XML document will likely have little impact on the performance.
*At run time, the enhanced XML parser overrides a partitionSize that consumes all of the available heap space.
*At run time, if the partitionSize results in an initial heap allocation that exceeds the single document limit set in the Maximum heap allocation for any single document field the limit for all documents set in the Maximum heap allocation for all documents combined field, the enhanced XML parser reduces the partition size automatically. For more information about heap allocation limits for the enhanced XML parser, see webMethods Integration Server Administrator’s Guide
*If you do not specify partitionSize, the enhanced XML parser uses the default specified in the Default partition size field on the Settings > Enhanced XML Parsing page in Integration Server Administrator.