nux.xom.xquery
Class XQueryUtil

java.lang.Object
  nux.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	update(Node contextNode, String select, String morpher) EXPERIMENTAL; Convenience morphing method.
static void	update(Nodes nodes, XQuery morpher, Map variables) EXPERIMENTAL; Simple yet powerful and efficient in-place morphing for use as an XQuery/XPath insert, update and delete facility; particularly useful for structurally small tree transformations without requiring (potentially huge) XML tree copies.
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

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

update

public static void update(Nodes nodes,
                          XQuery morpher,
                          Map variables)

EXPERIMENTAL; Simple yet powerful and efficient in-place morphing for use as an XQuery/XPath insert, update and delete facility; particularly useful for structurally small tree transformations without requiring (potentially huge) XML tree copies. Morphing is not in general intended as a replacement for constructive XQuery or XSLT.

To get started, see the example use cases and observe that various types of insert, update and delete can be concisely expressed via morphing.

The morphing algorithm works as follows: For each node N in the given nodes sequence, let results be the node sequence returned by morpher.execute(N, null, vars). Now...

• If results is the empty sequence then N is detached (i.e. deleted) from its parent.
• Otherwise, let atomic be the string concatenation of the standard XPath string value of all atomic values in results (separating string values by a single space character), and let nonAtomic be the list of all non-atomic items in results. If there is at least one atomic value, replace the content of N with atomic. If there is at least one non-atomic value, replace N with nonAtomic, updating the parent of N.

Atomic types include xs:string, xs:integer, xs:double, xs:boolean, etc, all of which are not XML nodes.

Note that if a morpher result sequence contains multiple identical nodes, copies of those nodes will be made.

Example usage:

     // read document from file
     Document doc = new Builder().build(new File("samples/data/articles.xml"));
 
     // make all articles a bit cheaper
     XQueryUtil.update(doc, "//article/prize", ". * 0.95");
 
     // delete all chairs
     XQueryUtil.update(doc, "//article[@name='chair']", "()");
 
     // write updated document to file
     FileOutputStream out = new FileOutputStream("samples/data/articles2.xml");
     Serializer ser = new Serializer(out);
     ser.write(doc);
     out.close();
 

Parameters:

nodes - the list of nodes to morph

morpher - an XQuery or XPath query morphing each node in nodes into a new form (may be null in which case all nodes will be detached, i.e. deleted)

variables - the morpher's external global variables (may be null).

Throws:

RuntimeException - if an XQueryException occurs (unchecked exception for convenience)

update

public static void update(Node contextNode,
                          String select,
                          String morpher)

EXPERIMENTAL; Convenience morphing method. Equivalent to

 XQuery xmorpher = XQueryPool.GLOBAL_POOL.getXQuery(morpher, null);
 update(xquery(contextNode, select), xmorpher, null);
 

Parameters:

contextNode - the context node to execute the select query against

select - an XQuery or XPath query selecting the nodes to morph.

morpher - an XQuery or XPath query morphing each node in xquery(contextNode, select) into a new form (may be null in which case all nodes will be detached, i.e. deleted)

Throws:

RuntimeException - if an XQueryException occurs (unchecked exception for convenience)