XML services

Input parameters for documentToXMLBytes

• document: Document - Document that is to be converted to XML. Note that 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.

• 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 "@".
• 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 To not HTML-encode the data. This is the default. For example, the string expression 5 < 6 would be converted to <expr>5 < 6</expr>, which is invalid.

• strictEncodeElements: String. Optional. Controls the behavior of the encode parameter. If this parameter is set to true when the encode parameter is true, then only the strictEncodeElements < > & characters in the element content are HTML-encoded (the apostrophe and quote characters are not HTML-encoded).

  Default value is false.

• preserveRefs: String Optional - Flag indicating whether the leading & (ampersand) of a well-formed entity or character reference is left as & or further encoded as & 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 To encode the leading & (ampersand) as & when the & appears in an entity or character reference. This is the default. The service ignores the value of preserveRefs when encode is set to false.

• documentTypeName: String (picklist). Optional. Document type that describes the structure and format of the output document. You can use this parameter to ensure that the output includes elements that might not be present in document at run time, or to describe the order in which elements are to appear in the resulting XML String. If you are using derived type processing, you must provide this parameter.

• generateRequiredTags: String. Optional. Flag indicating whether empty tags are to be included in the output document if a mandatory element appears in the document generateRequiredTags type specified in documentTypeName but does not appear in document. Set to:

  • true to include mandatory elements if they are not present in document.
  • false to omit mandatory elements if they are not present in document.

  Default value is false.

  Note: The generateRequiredTags is only applicable if documentTypeName is provided.

• generateNilTags: String. Optional. Flag indicating whether the resulting XML string includes the attribute xsi:nil for elements that are null. Set to:

  • true to generate the xsi:nil attribute for an element if the Allow null property for the corresponding field is set to true and the field is null in document.
  Note: generateRequiredTags must also be set to true to generate the xsi:nil attribute in the XML String.
  • false to omit the xsi:nil attribute even if a nillable field is, in fact, null.

  Default value is 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.

• dtdHeaderInfo: String. Optional. Contents of the DOCTYPE header to be inserted into the XML String.

• bufferSize: String. Optional. Initial size (in bytes) of the String buffer that documentToXMLString uses to assemble the output XML String. If the String bufferSize buffer fills up before documentToXMLString is finished generating the XML String, it reallocates the buffer, expanding it by this amount each time the buffer becomes full.

Output parameters for documentToXMLBytes

• xmlBytes: Object. XML content bytes (byte array) produced from 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.

Input parameters for documentToXMLStream

• document: Document - Document that is to be converted to XML. Note that 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.
• 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 "@".

• 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 < 6 would be converted to <expr>5 < 6</expr>, which is invalid.

• strictEncodeElements: String. Optional. Controls the behavior of the encode parameter. If this parameter is set to true when the encode parameter is true, then only the strictEncodeElements < > & characters in the element content are HTML-encoded (the apostrophe and quote characters are not HTML-encoded).

  Default value is false.

• preserveRefs: String Optional - Flag indicating whether the leading & (ampersand) of a well-formed entity or character reference is left as & or further encoded as & 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 & when the & appears in an entity or character reference. This is the default. The service ignores the value of preserveRefs when encode is set to false.

• documentTypeName: String (picklist). Optional. Document type that describes the structure and format of the output document. You can use this parameter to ensure that the output includes elements that might not be present in document at run time, or to describe the order in which elements are to appear in the resulting XML String. If you are using derived type processing, you must provide this parameter.

• generateRequiredTags: String. Optional. Flag indicating whether empty tags are to be included in the output document if a mandatory element appears in the document generateRequiredTags type specified in documentTypeName but does not appear in document. Set to:

  • true to include mandatory elements if they are not present in document.

  • false to omit mandatory elements if they are not present in document.

  Default value is false.

  Note: The generateRequiredTags is only applicable if documentTypeName is provided.

• generateNilTags: String. Optional. Flag indicating whether the resulting XML string includes the attribute xsi:nil for elements that are null. Set to:

  • true to generate the xsi:nil attribute for an element if the Allow null property for the corresponding field is set to true and the field is null in document.
  Note: generateRequiredTags must also be set to true to generate the xsi:nil attribute in the XML String.
  • false to omit the xsi:nil attribute even if a nillable field is, in fact, null.

  Default value is 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.

• dtdHeaderInfo: String. Optional. Contents of the DOCTYPE header to be inserted into the XML String.

• bufferSize: String. Optional. Initial size (in bytes) of the String buffer that documentToXMLString uses to assemble the output XML String. If the String bufferSize buffer fills up before documentToXMLString is finished generating the XML String, it reallocates the buffer, expanding it by this amount each time the buffer becomes full.

Output parameters for documentToXMLStream

• xmlStream: java.io.InputStream - XML content stream produced from 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.

Input parameters for documentToXMLString

• 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.

• 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 "@".

• 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 < 6 would be converted to <expr>5 < 6</expr>, which is invalid.

• strictEncodeElements: String. Optional. Controls the behavior of the encode parameter. If this parameter is set to true when the encode parameter is true, then only the strictEncodeElements < > & characters in the element content are HTML-encoded (the apostrophe and quote characters are not HTML-encoded).

  Default value is false.

• preserveRefs: String Optional - Flag indicating whether the leading & (ampersand) of a well-formed entity or character reference is left as & or further encoded as & 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 & when the & appears in an entity or character reference. This is the default. The service ignores the value of preserveRefs when encode is set to false.

• documentTypeName: String (picklist). Optional. Document type that describes the structure and format of the output document. You can use this parameter to ensure that the output includes elements that might not be present in document at run time, or to describe the order in which elements are to appear in the resulting XML String. If you are using derived type processing, you must provide this parameter.

• generateRequiredTags: String. Optional. Flag indicating whether empty tags are to be included in the output document if a mandatory element appears in the document generateRequiredTags type specified in documentTypeName but does not appear in document. Set to:

  • true to include mandatory elements if they are not present in document.

  • false to omit mandatory elements if they are not present in document.

  Default value is false.

  Note: The generateRequiredTags is only applicable if documentTypeName is provided.

• generateNilTags: String. Optional. Flag indicating whether the resulting XML string includes the attribute xsi:nil for elements that are null. Set to:

  • true to generate the xsi:nil attribute for an element if the Allow null property for the corresponding field is set to true and the field is null in document.
  Note: generateRequiredTags must also be set to true to generate the xsi:nil attribute in the XML String.
  • false to omit the xsi:nil attribute even if a nillable field is, in fact, null.

  Default value is 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.

• dtdHeaderInfo: String. Optional. Contents of the DOCTYPE header to be inserted into the XML String.

• bufferSize: String. Optional. Initial size (in bytes) of the String buffer that documentToXMLString uses to assemble the output XML String. If the String bufferSize buffer fills up before documentToXMLString is finished generating the XML String, it reallocates the buffer, expanding it by this amount each time the buffer becomes full.

Output parameters for documentToXMLString

• xmlString: Object - XML document string produced from 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 the 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.

Input parameters for getXMLNodeType

• rootNode: com.wm.lang.xml.Document - XML node about which you want information.

Output parameters for getXMLNodeType

• systemID: String Conditional - System identifier, as provided by the DTD associated with rootNode. If rootNode does not have a system identifier, this value is null.

• publicID: String Conditional - Public identifier, as provided by the DTD associated with rootNode. If rootNode does not have a public identifier, this value is null.

• rootNamespace: String - URI of the XML namespace to which rootNode's root element belongs.

• rootNSPrefix: String Conditional - Namespace prefix of root element in rootNode, if any.

• rootLocalName: String Conditional - Local name (excluding the namespace prefix) of the root element in rootNode, if any.

Input parameters for queryXMLNode

• node: The XML node that you want to query. This parameter supports the following types of input:

  • com.wm.lang.xml.Node - XML node that you want to query. An XML node can be produced by xmlStringToXMLNode or an XML content handler.

• nsDecls: Document Optional - Namespaces associated with any namespace prefixes used element to specify elements in fields/query. 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.

• fields: Document List Optional - Parameters describing how data is to be extracted from node. Each document in the list contains parameters for a single query, as follows:

  • name: String: Name to assign to resulting value.
  • resultType: String - Object type that the query is to yield. The following shows the allowed underlying value and the corresponding data type for resultType.

    Object: ObjectObject[]

    Object ListRecord

    - DocumentRecord[]

    - Document List

    - String - StringString[]

    - String ListString[]

    String Table

  • query: String - Query identifying the data to be extracted from node.
  • queryType: String - Query language in which query is expressed. Valid values are WQL and XQL.
  • onnull: String - Code indicating what you want queryXMLNode to do when the result is null. Set to one of the following:

    - continue - To indicate that all result values are acceptable for this query (including null).

    fail - To indicate that the service should fail if the result of this query is null and continue in all other cases.

    fail - To indicate that the service should fail if the result of this query is null and continue in all other cases.

    fail - To indicate that the service should fail if the result of this query is null and continue in all other cases.

    succeed - To indicate that the service should continue if the result of this query is null and fail in all other cases.

  • fields []: Document List - Parameters that support recursive execution of bindings. Each fields list defines bindings for one level of the output with the top level being the pipeline and the first level down being contents of a document or document list in the pipeline.

Output parameters for queryXMLNode

• Document: Results from the queries specified in fields. This service returns one element for each query specified in fields. The specific names and types of the returned elements are determined by the fields/name and field/resultType parameters of the individual queries.

Usage notes for queryXMLNode

Input parameters for xmlBytesToDocument

• xmlBytes: Object - XML content bytes that is to be converted to a document.

• nsDecls: Document Optional - Namespace prefixes to use for the conversion. This parameter specifies the prefixes that will be used when namespace-qualified elements are converted to key names in the resulting Document. For example, if you want elements belonging to a particular namespace to have the prefix GSX in the resulting Document (for example, GSX:acctNum), you would associate the prefix GSX with that namespace in nsDecls. This is important because incoming XML documents can use any prefix for a given namespace, but the key names expected by a target service will have a fixed prefix. Namespace prefixes in nsDecls also define the prefixes used by the arrays, documents, and collect parameters. 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.

• preserveUndeclaredNS: String Optional - Flag indicating whether or not webMethods Integration keeps undeclared namespaces in the resulting document. An undeclared namespace is one that is not specified as part of the nsDecls input parameter.

  Set to:

  • true to preserve undeclared namespaces in the resulting document. For each namespace declaration in the XML document that is not specified in the nsDecls parameter, webMethods Integration adds the xmlns attribute as a String variable to the document. webMethods Integration gives the variable a name that begins with "@xmlns" and assigns the variable the namespace value specified in the XML document. webMethods Integration preserves the position of the undeclared namespace in the resulting document.

  • falseto ignore namespace declarations in the XML document that are not specified in the nsDecls parameter. This is the default.

• preserveNSPositions: String Optional - Flag indicating whether or not webMethods Integration maintains the position of namespaces declared in the nsDecls parameter in the resulting document.

  Set to:

  • true to preserve the position of namespaces declared in nsDecls in the resulting document. For each namespace specified in the nsDecls parameter, webMethods Integration adds the xmlns attribute to the document (IData) as a String variable named "@xmlns:NSprefix" where "NSprefix" is the prefix name specified in nsDecls. webMethods Integration assigns the variable the namespace value specified in the XML document. This variable maintains the position of the xmlns attribute declaration within the XML document.

  • falseto not maintain the position of the namespace declarations specified in nsDecls in the resulting document. This is the default.

Output parameters for xmlBytesToDocument

• document: Document - Document representation of nodes and attributes in node.

Input parameters for xmlNodeToDocument

• node: XML node that is to be converted to a document. This parameter supports the com.wm.lang.xml.Node and org.w3c.dom.Node types of input.

• attrPrefix: String Optional - Prefix that is to be used to designate keys containing attribute values. The default is "@".

• arrays []: String List Optional - Names of elements that are to be generated as arrays, regardless of whether they appear multiple times in node. For example, if arrays contained rep and address for an XML document, xmlNodeToDocument would generate element rep as a String List and element address as a Document List. If you include namespace prefixes in the element names that you specify in arrays, you must define the namespaces associated with those prefixes in nsDecls.

• makeArrays: String Optional - Flag indicating whether you want xmlNodeToDocument to automatically create an array for every element that appears in node more than once.

  Set to:

  • true to automatically create arrays for every element that appears more than once in node. This is the default.

  • falseto create arrays for only those elements specified in arrays.

• collect: Document Optional - Elements that are to be placed into a new, named array (that is, a "collection"). Within collect, use key names to specify the names of the elements that are to be included in the collection. Then set the value of each key to specify the name of the collection in which you want that element placed. For example, if you want to place the name and rep elements in an array called originator, you would set collect as follows:

  • Key: name
  • Value: originator
  • Key: rep
  • Value: originator

  If the set of elements in a collection are all simple elements, a String List is produced. However, if the set is made up of complex elements, or a combination of simple and complex elements, a Document List is produced. When this is the case, each member of the array will include a child element called *name that contains the name of the element from which that member was derived. You may optionally include namespace prefixes in the element names that you specify in collect; however, if you do, you must define the namespaces associated with those prefixes in nsDecls. You cannot include an element in more than one collection.

• nsDecls: Document Optional - Namespace prefixes to use for the conversion. This parameter specifies the prefixes that will be used when namespace-qualified elements are converted to key names in the resulting Document. For example, if you want elements belonging to a particular namespace to have the prefix GSX in the resulting Document (for example, GSX:acctNum), you would associate the prefix GSX with that namespace in nsDecls. This is important because incoming XML documents can use any prefix for a given namespace, but the key names expected by a target service will have a fixed prefix. Namespace prefixes in nsDecls also define the prefixes used by the arrays, documents, and collect parameters. 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.

• documents[]: String List Optional - Names of any simple elements that are to be generated as documents instead of Strings. The document produced for each element specified in documents[] will have the same name as the source element from which it is derived. It will contain a String element named *body that holds the element's value. If you include namespace prefixes in the element names that you specify, you must define the namespaces associated with those prefixes in nsDecls.

• documentTypeName: String (picklist). Optional. Document type that describes the structure and format of the output document. You can use this parameter to ensure that the output includes elements that might not be present in document at run time, or to describe the order in which elements are to appear in the resulting XML String. If you are using derived type processing, you must provide this parameter.

• mixedModel: String Optional - Flag specifying how mixed-content elements (elements containing both text values and child elements) are to be converted.

  Set to:

  • true to place top-level text in an element named *body.

  • falseto omit top-level text and include only the child elements from mixed-content elements.

• preserveUndeclaredNS: String Optional - Flag indicating whether or not webMethods Integration keeps undeclared namespaces in the resulting document. An undeclared namespace is one that is not specified as part of the nsDecls input parameter.

  Set to:

  • true to preserve undeclared namespaces in the resulting document. For each namespace declaration in the XML document that is not specified in the nsDecls parameter, webMethods Integration adds the xmlns attribute as a String variable to the document. webMethods Integration gives the variable a name that begins with "@xmlns" and assigns the variable the namespace value specified in the XML document. webMethods Integration preserves the position of the undeclared namespace in the resulting document.

  • falseto ignore namespace declarations in the XML document that are not specified in the nsDecls parameter. This is the default.

• preserveNSPositions: String Optional - Flag indicating whether or not webMethods Integration maintains the position of namespaces declared in the nsDecls parameter in the resulting document.

  Set to:

  • true to preserve the position of namespaces declared in nsDecls in the resulting document. For each namespace specified in the nsDecls parameter, webMethods Integration adds the xmlns attribute to the document (IData) as a String variable named "@xmlns:NSprefix" where "NSprefix" is the prefix name specified in nsDecls. webMethods Integration assigns the variable the namespace value specified in the XML document. This variable maintains the position of the xmlns attribute declaration within the XML document.

  • false to not maintain the position of the namespace declarations specified in nsDecls in the resulting document. This is the default.

• useNamespacesOfDocumentType: String. Optional. Flag indicating whether or not webMethods Integration uses the namespaces defined in the document type specified for the useNamespacesOf DocumentType documentTypeName input parameter when creating a document from an XML string. Set to:

  • True to use the namespaces defined in the document type specified in documentTypeName and those in nsDecls when creating elements in the output document.

  • False to use the namespaces defined in the nsDecls parameter only.

  Default value is false.

Output parameters for xmlNodeToDocument

• document: Document - Document representation of the nodes and attributes in node.

Input parameters for xmlStreamToDocument

• xmlStream: java.io.InputStream - XML content stream that is to be converted to a document.

• nsDecls []: Document Optional - Namespace prefixes to use for the conversion. This parameter specifies the prefixes that will be used when namespace-qualified elements are converted to key names in the resulting document object. For example, if you want elements belonging to a particular namespace to have the prefix GSX in the resulting document, for example, GSX:acctNum, you would associate the prefix GSX with that namespace in nsDecls . This is important because incoming XML documents can use any prefix for a given namespace, but the key names expected by a target service will have a fixed prefix. Namespace prefixes in nsDecls also define the prefixes used by the arrays, documents, documentTypeName, and collect parameters. 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. Parameters for nsDecls [] are:

  • prefix: Key name.
  • uri: Key value.

• preserveUndeclaredNS: String Optional - Flag indicating whether or not webMethods Integration keeps undeclared namespaces in the resulting document. An undeclared namespace is one that is not specified as part of the nsDecls input parameter.

  Set to:

  • true to preserve undeclared namespaces in the resulting document. For each namespace declaration in the XML document that is not specified in the nsDecls parameter, webMethods Integration adds the xmlns attribute as a String variable to the document. webMethods Integration gives the variable a name that begins with "@xmlns" and assigns the variable the namespace value specified in the XML document. webMethods Integration preserves the position of the undeclared namespace in the resulting document.

  • false to ignore namespace declarations in the XML document that are not specified in the nsDecls parameter. This is the default.

• preserveNSPositions: String Optional - Flag indicating whether or not webMethods Integration maintains the position of namespaces declared in the nsDecls parameter in the resulting document.

  Set to:

  • true to preserve the position of namespaces declared in nsDecls in the resulting document. For each namespace specified in the nsDecls parameter, webMethods Integration adds the xmlns attribute to the document as a String variable named "@xmlns:NSprefix" where "NSprefix" is the prefix name specified in nsDecls. webMethods Integration assigns the variable the namespace value specified in the XML document. This variable maintains the position of the xmlns attribute declaration within the XML document.

  • false to not maintain the position of the namespace declarations specified in nsDecls in the resulting document. This is the default.

Output parameters for xmlStreamToDocument

• document: Document - Document representation of nodes and attributes in node.

Input parameters for xmlStringToDocument

• xmlString: String - XML string that is to be converted to a document.

• nsDecls []: Document Optional - Namespace prefixes to use for the conversion. This parameter specifies the prefixes that will be used when namespace-qualified elements are converted to key names in the resulting document object. For example, if you want elements belonging to a particular namespace to have the prefix GSX in the resulting document, for example, GSX:acctNum, you would associate the prefix GSX with that namespace in nsDecls . This is important because incoming XML documents can use any prefix for a given namespace, but the key names expected by a target service will have a fixed prefix. Namespace prefixes in nsDecls also define the prefixes used by the arrays, documents, documentTypeName, and collect parameters. 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. Parameters for nsDecls [] are:

  • prefix: Key name.
  • uri: Key value.

• preserveUndeclaredNS: String Optional - Flag indicating whether or not webMethods Integration keeps undeclared namespaces in the resulting document. An undeclared namespace is one that is not specified as part of the nsDecls input parameter.

  Set to:

  • true to preserve undeclared namespaces in the resulting document. For each namespace declaration in the XML document that is not specified in the nsDecls parameter, webMethods Integration adds the xmlns attribute as a String variable to the document. webMethods Integration gives the variable a name that begins with "@xmlns" and assigns the variable the namespace value specified in the XML document. webMethods Integration preserves the position of the undeclared namespace in the resulting document.

  • false to ignore namespace declarations in the XML document that are not specified in the nsDecls parameter. This is the default.

• preserveNSPositions: String Optional - Flag indicating whether or not webMethods Integration maintains the position of namespaces declared in the nsDecls parameter in the resulting document.

  Set to:

  • true to preserve the position of namespaces declared in nsDecls in the resulting document. For each namespace specified in the nsDecls parameter, webMethods Integration adds the xmlns attribute to the document as a String variable named "@xmlns:NSprefix" where "NSprefix" is the prefix name specified in nsDecls. webMethods Integration assigns the variable the namespace value specified in the XML document. This variable maintains the position of the xmlns attribute declaration within the XML document.

  • false to not maintain the position of the namespace declarations specified in nsDecls in the resulting document. This is the default.

• arrays []: String List Optional - Names of elements that are to be generated as arrays, regardless of whether they appear multiple times. For example, if arrays contained the following values for an XML document: rep and address, xmlStringToDocument would generate element rep as a String List and element address as a Document List. If you include namespace prefixes in the element names that you specify in arrays, you must define the namespaces associated with those prefixes in nsDecls.

• makeArrays: String Optional - Flag indicating whether you want xmlStringToDocument to automatically create an array for every element that appears more than once.

  Set to:

  • true to automatically create arrays for every element that appears more than once. This is the default.

  • false to create arrays for only those elements specified in arrays.

Output parameters for xmlStringToDocument

• document: Document - Document representation of nodes and attributes in node.

Input parameters for xmlStringToXMLNode

• xmldata: String Optional - String containing the XML document to convert to an XML node. If you specify xmldata, do not specify $filedata or $filestream.

• $filedata: byte[] Optional - byte[] containing the XML document to convert to an XML node. If you specify $filedata, do not specify xmldata or $filestream.

• $filestream: java.io.InputStream Optional - InputStream containing the XML document to convert to an XML node. If you specify $filestream, do not specify xmldata or $filedata.

• encoding: String Optional - Character encoding in which text is represented. Specify UTF-8 for XML files and ISO-8859-1 for HTML files. To have the parser attempt to detect the type of encoding, specify autoDetect, (which is the default, if encoding is not specified).

• expandDTD: String. Optional. Flag indicating whetherreferences to parameter entities in the XML document's DTD are to be processed. Set to:

  • true to expand references to parameter entities to theirfull definition.

  • false to ignore references to parameter entities.

  Default value is false.

• isXML: String Optional - Flag specifying whether the input document is XML or HTML. (xmlStringToXMLNode must know this so that it can parse the document correctly.) Set to:

  • autoDetect - To parse the document based on its type. When you use this option, xmlStringToXMLNode detects the document's type based on its document type declaration as indicated by a <!DOCTYPE...\> or <?XML...\> tag. If it cannot determine the document type, it parses it as HTML. This is the default.

  • true to parse the document as XML.

  • false to parse the document as HTML.

• expandGeneralEntities: String. Optional. Flag indicating whether service should expand references to general entities in the XML document’s DTD. Set to:

  • true to expand references to general entities to their full definition.

  • false to ignore references to general entities.

  Default value is true.

• validateXML: String. Optional. Flag indicating whether webMethods Integration validates the incoming XML document to determine whether it is well-formed XML before converting the XML document. Set to:

  • true to validate the incoming XML. If validation fails, the service ends with a ServiceException.

  • false to skip validation.

  Default value is false.

Output parameters for xmlStringToXMLNode

• node: com.wm.lang.xml.Node - XML node representation of the XML document in xmlData. This object can be used as input to services that consume XML nodes.

Usage notes for xmlStringToXMLNode

• The input parameters xmldata, $filedata, and $filestream are mutually exclusive. Specify only one of the preceding parameters. webMethods Integration checks the parameters in the following order: $filedata, $filestream, and xmldata, and uses the value of the first parameter with a value.

Input parameters for getXMLNodeIterator

• Node: The XML node for which you want to create a NodeIterator can represent either an entire XML document or an element within an XML document. However, if the NodeIterator will be used in moving-window mode, it is necessary to use a complete XML document. This is because moving window mode is only meaningful for managing the loading process of a document, and operating on a node implies that the node has already been loaded.

• Criteria: String List Optional. Pattern strings identify the nodes that the iterator is to return. A pattern string may take either the form <localname> or the form <prefix>:<localname>. When a pattern takes the first form, it identifies an element whose local name is <localname> and that belongs to the default XML namespace. When a pattern takes the second form, it identifies an element whose local name is <localname> and whose XML namespace is given by the prefix <prefix>. If the input parameter nsDecls declares this prefix, the namespace URI of the element must match the URI declared for the prefix. If the prefix is not declared in nsDecls, the prefix is matched against prefixes found in the XML. Both <prefix> and <localname> can each optionally take the value "*" to match any namespace or local name. A "*" prefix also matches elements residing in the default namespace. If you do not specify criteria, all element node children of the root element are returned.

• nsDecls: Document Optional. Namespaces associated with any namespace prefixes used in criteria. 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.

• movingWindow: String Optional. Flag indicating whether the NodeIterator is to iterate using a moving window, as described above. In moving-window mode, the entire document preceding the node most recently returned by getXMLNodeIterator is discarded. Subsequent attempts to return preceding portions of the document will yield either the repeating text PURGED or the proper data, depending on whether the data falls within an area that the server was able to discard. When iterating with a moving window, the current node should be queried and completely examined before requesting the next node. Set to:

  • true to use the NodeIterator in moving-window mode.
  • false to use the NodeIterator in normal mode. This is the default.

Output parameters for getXMLNodeIterator

Iterator: NodeIterator for use with the service getNextXMLNode.

Input parameters for getNextXMLNode

Iterator: NodeIterator from which to retrieve the next node.

Output parameters for getNextXMLNode

Next Document Conditional. The requested node. It is null when the NodeIterator has no more nodes to return. Otherwise, next will contain the following:

Following are the service descriptions:

• next: String Element type name of the node. If the element belongs to a namespace and the namespace was declared at the time the NodeIterator was constructed, name will have the prefix declared for that namespace. If the namespace is not declared, name will use prefix that occurs in the XML.
• node: XML node identified by the input criteria used to originally generate the NodeIterator.

It is possible that all calls to getNextXMLNode on a given NodeIterator will yield the same document instance, with varying values for the instance's entries. Therefore, applications should assume that each call to getNextXMLNode invalidates the document returned by the previous call. This approach maximizes server speed and minimizes resource usage.

Usage notes for getNextXMLNode

A NodeIterator is acquired via the service getXMLNodeIterator. The output of that service is a document containing the element type name of the node and the node itself. The instance of this document is only valid until the next getNextXMLNode call on the same NodeIterator, because getNextXMLNode uses the same document object for each call.

Input Parameters for freeXMLNode

rootNode: XML node whose resources you want to release. Specify the same type of input that you supplied to getXMLNodeIterator.

Output Parameters for freeXMLNode

None.