pub.xml:getXMLNodeIterator
WmPublic. Creates and returns a NodeIterator.
A NodeIterator iterates over the element node descendants of an XML node and returns the element nodes that satisfy the given criteria. The client application or flow service uses the service
pub.xml:getNextXMLNode to get each node in turn. NodeIterators can only be created for XML nodes (not for HTML nodes).
pub.xml:getXMLNodeIterator is useful for loading and parsing documents on demand. Large or slow documents need only be loaded as far as needed to get the desired data. NodeIterators are also useful for providing service as the pertinent information in the document arrives rather than first waiting for the entire document to load. This service is primarily intended to deal with large documents or documents that arrive slowly.
NodeIterator provides a moving-window mode, in which the only node that is resident in memory is the last node returned by
pub.xml:getNextXMLNode. In this mode, when
pub.xml:getNextXMLNode is called, all nodes preceding the newly returned node become invalid, including all nodes previously returned by
pub.xml:getNextXMLNode. The client must fully complete processing preceding nodes before advancing the window by calling
pub.xml:getNextXMLNode again. In moving-window mode, the document consumes at least enough memory to hold the most recently returned node.
Moving-window mode allows the server to process multi-megabyte XML documents using very little memory. Moving-window mode may only be used on a node that represents an entire XML document and not on any descendant node. In other words, in moving-window mode, the input node must be the top-level node returned by pub.xml:xmlStringToXMLNode or pub.xml:loadXMLNode.
When operating in moving-window mode, the NodeIterator skips XML nodes that do not match the criteria set for the NodeIterator in pub.xml:getXMLNodeIterator. The NodeIterator frees skipped XML nodes after every pub.xml:getNextXMLNode execution. While this is the preferred and more performant behavior, some implementations might rely on earlier behavior where the NodeIterator retains skipped XML nodes until a successful match is found. Retaining skipped XML nodes makes it difficult to iterate over large XML files when there is a large number of intervening non-matching nodes between successful matches. Integration Server provides the server configuration parameter watt.core.nodeIterator.retainFailures to obtain the behavior of retaining skipped XML nodes. When watt.core.nodeIterator.retainFailures is set to true, a NodeIterator operating in moving-window mode retains skipped XML nodes until a successful match is found for the criteria specified in pub.xml:getXMLNodeIterator. NodeIterator purges the skipped XML nodes only after a successful pub.xml:getNextXMLNode. When watt.core.nodeIterator.retainFailures is set to false, a NodeIterator operating in moving-window mode frees skipped XML nodes after every pub.xml:getNextXMLNode execution. The default value is false.
Note:
You can use moving-window mode if the input node is of type com.wm.lang.xml.Node only. Moving-window mode cannot be used with an enhanced XML node.
Order of Node Traversal
The NodeIterator traverses the nodes in XML document order, sometimes called depth-first traversal order. Basically, this is the same order that individual elements appear in the source XML. However, unlike a full traversal, when a node satisfies the search criterion and is returned, the search for the next node ignores the children of the returned node. Instead on the next call to pub.xml:getNextXMLNode, the search resumes with the next peer of the returned element. If there is no next peer, the search resumes with the next peer of the returned node's parent node.
Consider the following input XML document:
For a NodeIterator with search criterion "alpha", a call to pub.xml:getNextXMLNode returns only the document element <alpha id="1">. The children of <alpha id=”1”> are not searched. Subsequent calls to pub.xml:getNextXMLNode return null.
For a NodeIterator with search criterion "beta", a call to pub.xml:getNextXMLNode returns only the element <beta id="2">. The children of <beta id=”2”> are not searched. Subsequent calls to pub.xml:getNextXMLNode return null because there are no elements named beta among the following peer elements.
For a NodeIterator with search criterion "gamma", the first call to pub.xml:getNextXMLNode returns the element <gamma id="3">. The next call to a call to pub.xml:getNextXMLNode returns <gamma id="8"/>.
For a NodeIterator with search criterion "delta", the first call to pub.xml:getNextXMLNode returns the element <delta id="4"/>. Subsequent calls to pub.xml:getNextXMLNode return the element <delta id="5"/> and then the element <delta id="9"/> .
For a NodeIterator with search criteria "gamma" or "delta", the first call to pub.xml:getNextXMLNode returns the element <gamma id="3">. Subsequent calls to pub.xml:getNextXMLNode return the element <gamma id="8"/> and then the element <delta id="9"/>. Elements <delta id="4"/> and <delta id="5"/> are not returned because they are children of <gamma id="3"> which satisfied the search request in the first call to pub.xml:getNextXMLNode. As a result, the children of <gamma id="3"> are not searched in subsequent calls to pub.xml:getNextXMLNode.
Input Parameters
node | The XML node or enhanced XML node for which you want to produce a NodeIterator. This parameter supports the following types of input:  com.wm.lang.xml.Node XML node for which you want to produce a NodeIterator. The node can represent either an XML document or an element of an XML document; however, if the NodeIterator will be used in moving-window mode, a whole XML document must be used. This is because moving window mode is only meaningful for managing the loading process of a document, and to operate on a node is to have already loaded the node |
criteria | String List Optional. Pattern strings identifying 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. <prefix> and <localName> can each optionally take the value "*" (asterisk) 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. For example, to define the URIs associated with two prefixes called GSX and TxMon, you would set nsDecls as follows: |
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 return 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 prior to 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. Note:
If node is an enhanced XML node, set movingWindow to false. |
Output Parameters
