When using an XQuery expression that uses external variables, supply (or bind) values for each variable using an XDynamicContext instance and optionally declare the types of the variables using an XStaticContext instance.
This step is optional. If a variable is not declared, the processor assumes its type is item()*. In other words, the value of the variable can be a sequence of any length consisting of items of any type. Declaring a type for your variables can help the processor detect some usage errors statically during preparation.
Method Signature | Purpose |
---|---|
declareVariable(QName name, QName type) | Use when value of the variable is a single atomic
value The QName must refer to a built-in type or a global type declared in a schema that has been registered on the XFactory instance used to create the XStaticContext instance. If the QName refers to a non-atomic type, then the processor will treat the variable as having the type element(*, ns:type), where ns:type is the given QName. The XTypeConstants interface has convenient constants available that provide a QName object for each built-in type. |
declareVariable(QName name, XSequenceType type) | Use when value of the variable is a single node or a sequence of atomic values or nodes |
declare namespace xs = "http://www.w3.org/2001/XMLSchema"; declare variable $searchTerms as xs:string+ external; <table> <tr><td>Title</td><td>Author</td></tr> { for $book in /library/book let $value := $book/@*[local-name()=$searchField] where exists(for $term in $searchTerms return if (contains($value, $term)) then true() else ()) return <tr> <td>{ string($book/@title) }</td> <td>{ string($book/@author) }</td> </tr> } </table>The variable not declared in the XQuery expression itself can be optionally declared using an XStaticContext instance to provide the processor with type information.
// Create the factory XFactory factory = XFactory.newInstance(); // Create a new static context from the factory XStaticContext staticContext = factory.newStaticContext(); // Define a QName for the name of the variable to be declared final QName searchField = new QName("searchField"); // Declare a variable called "searchField" as an xs:string staticContext.declareVariable(searchField, XTypeConstants.STRING_QNAME); // Prepare the XQuery expression XQueryExecutable xquery = factory.prepareXQuery(xquerySource, staticContext);
An error is raised if you do not supply a value for a variable that is used when executing the XQuery expression.
Method | Purpose |
---|---|
bind | Use when binding a single atomic value There is one form of this method for each of the Java™ types that is used in the standard mapping of built-in types to Java types. There are two additional forms—one that takes a node and one that takes a source. These are used for binding any node from a DOM tree and parsing a new source to yield a document node, respectively. |
bindItem | Use when binding a single item as an XItemView
object An XItemView object can be obtained from the result of executing another expression or constructed using an XItemFactory instance. |
bindSequence | Use when binding sequences of less than or greater
than one item There is one form of this method for each of the Java types that is used in the standard mapping of built-in types to Java types; each accepts an array of values the given type. There is an additional form that takes an XSequenceCursor. An XSequenceCursor can be the result of executing another expression or can be constructed using an XItemFactory instance. |
// Create a new dynamic context from the factory XDynamicContext dynamicContext = factory.newDynamicContext(); // Bind an atomic value for the "searchField" variable dynamicContext.bind(searchField, "title"); // Bind a sequence of atomic values for the "searchTerms" variable dynamicContext.bindSequence(new QName("searchTerms"), new String[] {"Lost", "Gables"}); // Create an XML input document String xml = "<library>" + "<book title='Lost in the Barrens' author='Farley Mowat'/>" + "<book title='Anne of Green Gables' author='L. M. Montgomery'/>" + "</library>"; StreamSource source = new StreamSource(new StringReader(xml)); // Execute the expression XSequenceCursor result = xquery.execute(source, dynamicContext);