net.sf.saxon.query
Class XQueryExpression

java.lang.Object
  |
  +--net.sf.saxon.query.XQueryExpression

public class XQueryExpression
extends java.lang.Object

XQueryExpression represents a compiled query. This object is immutable and thread-safe, the same compiled query may be executed many times in series or in parallel. The object can be created only by using the compileQuery method of the QueryProcessor class.

Various methods are provided for evaluating the query, with different options for delivery of the results.


Constructor Summary
protected XQueryExpression(Expression exp, StaticQueryContext staticEnv, Configuration config)
          The constructor is protected, to ensure that instances can only be created using the compileQuery() methods of QueryProcessor
 
Method Summary
 java.util.List evaluate(DynamicQueryContext env)
          Execute a the compiled Query, returning the results as a List.
 java.lang.Object evaluateSingle(DynamicQueryContext env)
          Execute the compiled Query, returning the first item in the result.
 void explain(NamePool pool)
          Diagnostic method: display a representation of the compiled query on the System.err output stream.
 SequenceIterator iterator(DynamicQueryContext env)
          Get an iterator over the results of the expression.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XQueryExpression

protected XQueryExpression(Expression exp,
                           StaticQueryContext staticEnv,
                           Configuration config)
The constructor is protected, to ensure that instances can only be created using the compileQuery() methods of QueryProcessor

Method Detail

evaluate

public java.util.List evaluate(DynamicQueryContext env)
                        throws javax.xml.transform.TransformerException
Execute a the compiled Query, returning the results as a List.

Parameters:
env - Provides the dynamic query evaluation context
Returns:
The results of the expression, as a List. The List represents the sequence of items returned by the expression. Each item in the list will either be an object representing a node, or an object representing an atomic value. For the types of Java object that may be returned, see the description of the evaluate method of class XPathProcessor
javax.xml.transform.TransformerException

evaluateSingle

public java.lang.Object evaluateSingle(DynamicQueryContext env)
                                throws javax.xml.transform.TransformerException
Execute the compiled Query, returning the first item in the result. This is useful where it is known that the expression will only return a singleton value (for example, a single node, or a boolean).

Parameters:
env - Provides the dynamic query evaluation context
Returns:
The first item in the sequence returned by the expression. If the expression returns an empty sequence, this method returns null. Otherwise, it returns the first item in the result sequence, represented as a Java object using the same mapping as for the evaluate() method
javax.xml.transform.TransformerException

iterator

public SequenceIterator iterator(DynamicQueryContext env)
                          throws javax.xml.transform.TransformerException
Get an iterator over the results of the expression. This returns results without any conversion of the returned items to "native" Java classes. The iterator will deliver a sequence of Item objects, each item being either a NodeInfo (representing a node) or an AtomicValue (representing an atomic value).

To get the results of the query in the form of an XML document in which each item is wrapped by an element indicating its type, use:

QueryResult.wrap(iterator(env))

To serialize the results to a file, use the QueryResult.serialize() method.

Parameters:
env - Provides the dynamic query evaluation context
Returns:
an iterator over the results of the query. The class SequenceIterator is modeled on the standard Java Iterator class, but has extra functionality and can throw exceptions when errors occur.
Throws:
XPathException - if a dynamic error occurs in evaluating the query. Some dynamic errors will not be reported by this method, but will only be reported when the individual items of the result are accessed using the returned iterator.
javax.xml.transform.TransformerException

explain

public void explain(NamePool pool)
Diagnostic method: display a representation of the compiled query on the System.err output stream.