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.
Variables declared
in the XStaticContext are only visible to the main module. To make
an external variable visible to a library module, it must be declared
in the prolog of the library module with an external variable declaration.
Declaring the variable in the XStaticContext is optional. If a variable is not declared, the processor assumes that 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);
The bindings for external
variables will be available to the main module and to any library
modules that have an external variable declaration in their prolog
for that variable.
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);
In this information ... | IBM Redbooks, demos, education, and more(Index) Use IBM Suggests to retrieve related content from ibm.com and beyond, identified for your convenience. This feature requires Internet access. Most of the following links will take you to information that is not part of the formal product documentation and is provided "as is." Some of these links go to non-IBM Web sites and are provided for your convenience only and do not in any manner serve as an endorsement by IBM of those Web sites, the material thereon, or the owner thereof. |