Nux 1.0

nux.xom.xquery
Class XQueryUtil

java.lang.Object
  extended bynux.xom.xquery.XQueryUtil

public class XQueryUtil
extends Object

Various utilities avoiding redundant code in several classes.

Author:
whoschek.AT.lbl.DOT.gov, $Author: hoschek3 $

Method Summary
static void normalizeTexts(ParentNode node)
          Recursively walks the given node subtree and merges runs of consecutive (adjacent) Text nodes (if present) into a single Text node containing their string concatenation; Empty Text nodes are removed.
static Nodes xquery(Node contextNode, String query)
          Executes the given W3C XQuery or XPath against the given context node (subtree); convenience method.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

normalizeTexts

public static void normalizeTexts(ParentNode node)
Recursively walks the given node subtree and merges runs of consecutive (adjacent) Text nodes (if present) into a single Text node containing their string concatenation; Empty Text nodes are removed.

If present, CDATA nodes are treated as Text nodes. The semantics are the same as with the DOM method org.w3c.dom.Node.normalize().

Note that documents built by a Builder with the default NodeFactory are guaranteed to never have adjacent or empty Text nodes. However, subsequent manual removal or insertion of nodes to the tree can cause Text nodes to become adjacent, and updates can cause Text nodes to become empty.

Text normalization is necessary to achieve strictly standards-compliant XPath and XQuery semantics if a query compares or extracts the value of individual Text nodes that (unfortunately) happen to be adjacent to other Text nodes. Luckily, such use cases are rare in practical real-world scenarios and thus a user hardly ever needs to call this method before passing a XOM tree into XQuery or XPath.

Example Usage:

 Element foo = new Element("foo");
 foo.appendChild("");
 foo.appendChild("bar");
 foo.appendChild("");
 
 Element elem = new Element("elem");
 elem.appendChild("");
 elem.appendChild(foo);
 elem.appendChild("hello");
 elem.appendChild("world");
 elem.appendChild(foo.copy());
 elem.appendChild("");
 
 XQueryUtil.normalizeTexts(elem);
 
 for (int i = 0; i < elem.getChildCount(); i++) {
     System.out.println(elem.getChild(i).toString());
     if (elem.getChild(i) instanceof Element) {
         Element nested = (Element) elem.getChild(i);
         for (int j = 0; j < nested.getChildCount(); j++) {
             System.out.println("    " + nested.getChild(j).toString());
         }
     }  
 }
 
returns the following normalized output:
 [nu.xom.Element: foo]
     [nu.xom.Text: bar]
 [nu.xom.Text: helloworld]
 [nu.xom.Element: foo]
     [nu.xom.Text: bar]	
 

Parameters:
node - the subtree to normalize

xquery

public static Nodes xquery(Node contextNode,
                           String query)
Executes the given W3C XQuery or XPath against the given context node (subtree); convenience method. Equivalent to
 return XQueryPool.GLOBAL_POOL.getXQuery(query, null).execute(contextNode).toNodes();
 
Example usage:
 // find the atom named 'Zinc' in the periodic table:
 Document doc = new Builder().build(new File("samples/data/periodic.xml"));
 Node result = XQueryUtil.xquery(doc, "/PERIODIC_TABLE/ATOM[NAME = 'Zinc']").get(0);
 System.out.println("result=" + result.toXML());
 

Parameters:
contextNode - the context node to execute the query against. The context node is available to the query as the value of the query expression ".". If this parameter is null, the context node will be undefined.
query - the XQuery or XPath string
Returns:
the nodes of the result sequence.
Throws:
RuntimeException - if an XQueryException occurs (unchecked exception for convenience)
See Also:
XQuery, XQueryPool

Nux 1.0