Integration Server 10.3 | Built-In Services Reference Guide | XML Folder | Summary of Elements in this Folder | pub.xml:loadXMLNode
 
pub.xml:loadXMLNode
WmPublic. Retrieves an XML document via HTTP or HTTPS, parses it using the legacy XML parser, and produces an XML node.
An XML node is a special representation of an XML document that can be consumed by the Integration Server. Most webMethods services that operate on XML documents require an XML node 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:loadXMLNode submits data values (if any) to the resource identified in url. The default is get.
*If you set method to get, pub.xml:loadXMLNode 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).
*If you set method to post, pub.xml:loadXMLNode sends the values in data in the body of the HTTP or HTTPS request.
auth
Document Optional. Authentication and authorization information that pub.xml:loadXMLNode 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:loadXMLNode 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:loadXMLNode 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:loadXMLNode 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:loadXMLNode 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:loadXMLNode 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, 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.
table
String Table Optional. Specifies data that pub.xml:loadXMLNode 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:loadXMLNode 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:loadXMLNode 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:loadXMLNode 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:loadXMLNode, 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:loadXMLNode 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:loadXMLNode, 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:loadXMLNode.
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:loadXMLNode will use its default header values.
Note:
You do not need to type a colon after the field name because pub.xml:loadXMLNode 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:loadXMLNode, 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:loadXMLNode 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:loadXMLNode 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:loadXMLNode. 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:loadXMLNode might otherwise derive from other parameter settings.
*The pub.xml:loadXMLNode 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 based on document type, where:
*ISO-8859-1 is used for HTML.
*UTF-8 is used for XML.
*The name of a registered IANA character set to decode the document using that character set (for example, ISO-8859-1).
If you do not specify an encoding value, pub.xml:loadXMLNode decodes the returned document using the following defaults:
If the document is...
It is decoded using...
HTML
ISO-8859-1
XML
UTF-8
expandDTD
String Optional. Flag indicating whether or not pub.xml:loadXMLNode is to process references to parameter entities in the returned document's DTD. Set to:
*true to expand references to parameter entities to their full definition.
*false to ignore references to parameter entities. This is the default.
Note:
You might want or need to use this variable in cases when you have a syntactically correct document that causes a parse error because it violates a definition in an external parameter-entity reference. By setting expandDTD to false, you can bypass the external definition so that pub.xml:loadXMLNode can parse the document successfully
isXML
String Optional. Flag indicating whether the returned document is XML or HTML. pub.xml:loadXMLNode must know this in order to parse a document correctly. Set to:
*autoDetect to parse the document based on its type. When you use this option, pub.xml:loadXMLNode senses the document's type based on its <!DOCTYPE...\> or <?XML...\> tag. If it cannot determine a document's type, it parses it as HTML. This is the default.
*true to parse the document as XML.
*false to parse the document as HTML.
Note:
: If you know what type of document pub.xml:loadXMLNode will receive, Software AG recommends that you explicitly set isXML instead of using autoDetect. It will cut processing time, because the server will not have to examine the document to determine its type. The default value is autoDetect.
loadAs
String Optional. Flag that specifies the form in which you want pub.xml:loadXMLNode to make the parsed document available to subsequent services. Set to:
*bytes to make the document available as a byte array. This is the default.
Use this option if the document will be used as input to a service that operates on whole documents (for example, pub.xml:queryXMLNode).
*stream to make the document available as an InputStream.
Use this option if the document will be used as input to a service that can process a document incrementally (for example, pub.xml:getXMLNodeIterator).
failOnHTTPError
String Optional. Determines whether pub.xml:loadXMLNode 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, the HTML page returned by the web server will be sent to the parser. This is the default.
expandGeneralEntities
String Optional. Flag indicating whether pub.xml:pub.xml:loadXMLNode should expand references to general entities in the returned document’s DTD. Set to:
*true to expand references to general entities to their full definition. This is the default.
*false to ignore references to general entities.
Output Parameters
node
com.wm.lang.xml.Node XML node representing the returned HTML or XML document.
Usage Notes
If pub.xml:loadXMLNode 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 .
If expandGeneralEntities is not specified, Integration Server uses the value in watt.core.xml.expandGeneralEntities. If watt.core.xml.expandGeneralEntities is not set, the references to general entities are always expanded.
Use the pub.xml:loadEnhancedXMLNode service to load an XML document and convert it too an XML node using the enhanced XML parser. For more information about the legacy XML parser and the enhanced XML parser, see webMethods Integration Server Administrator’s Guide.