Package net.sf.saxon.s9api
Class XQueryEvaluator
- java.lang.Object
-
- net.sf.saxon.s9api.XQueryEvaluator
-
- All Implemented Interfaces:
java.lang.Iterable<XdmItem>
public class XQueryEvaluator extends java.lang.Object implements java.lang.Iterable<XdmItem>
AnXQueryEvaluator
represents a compiled and loaded stylesheet ready for execution. TheXQueryEvaluator
holds details of the dynamic evaluation context for the stylesheet.An
XQueryEvaluator
must not be used concurrently in multiple threads. It is safe, however, to reuse the object within a single thread to run the same stylesheet several times. Running the stylesheet does not change the context that has been established.An
XQueryEvaluator
is always constructed by running theLoad
method of anXQueryExecutable
.An
XQueryEvaluator
is itself aIterable
. This makes it possible to evaluate the results in a for-each expression.
-
-
Constructor Summary
Constructors Modifier Constructor Description protected
XQueryEvaluator(Processor processor, XQueryExpression expression)
Protected constructor
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description XdmValue
evaluate()
Perform the query, returning the results as an XdmValue.XdmItem
getContextItem()
Get the initial context item for the query, if one has been setjavax.xml.transform.ErrorListener
getErrorListener()
Get the error listener.XdmValue
getExternalVariable(QName name)
Get the value that has been set for an external variablejava.io.PrintStream
getTraceFunctionDestination()
Get the destination for output from the fn:trace() function.TraceListener
getTraceListener()
Get the registered TraceListener, if anyDynamicQueryContext
getUnderlyingQueryContext()
Get the underlying dynamic context object.java.util.Iterator<XdmNode>
getUpdatedDocuments()
After executing an updating query using therun()
method, iterate over the root nodes of the documents updated by the query.javax.xml.transform.URIResolver
getURIResolver()
Get the URI resolver.java.util.Iterator<XdmItem>
iterator()
Get an iterator over the results of the query.void
run()
Perform the query.void
run(Destination destination)
Perform the query, sending the results to a specified destination.void
setContextItem(XdmItem item)
Set the initial context item for the queryvoid
setDestination(Destination destination)
Set the destination to be used for the query resultsvoid
setErrorListener(javax.xml.transform.ErrorListener listener)
Set the error listener.void
setExternalVariable(QName name, XdmValue value)
Set the value of external variable defined in the queryvoid
setSource(javax.xml.transform.Source source)
Set the source document for the query.void
setTraceFunctionDestination(java.io.PrintStream stream)
Set the destination for output from the fn:trace() function.void
setTraceListener(TraceListener listener)
Set a TraceListener which will receive messages relating to the evaluation of all expressions.void
setURIResolver(javax.xml.transform.URIResolver resolver)
Set an object that will be used to resolve URIs used in fn:doc() and related functions.
-
-
-
Constructor Detail
-
XQueryEvaluator
protected XQueryEvaluator(Processor processor, XQueryExpression expression)
Protected constructor- Parameters:
processor
- the Saxon processorexpression
- the XQuery expression
-
-
Method Detail
-
setSource
public void setSource(javax.xml.transform.Source source) throws SaxonApiException
Set the source document for the query. This method is equivalent to building a document from the supplied source object, and then supplying the document node of the resulting document as the initial context node.- Parameters:
source
- the principal source document for the transformation- Throws:
SaxonApiException
-
setContextItem
public void setContextItem(XdmItem item)
Set the initial context item for the query- Parameters:
item
- the initial context item, or null if there is to be no initial context item
-
getContextItem
public XdmItem getContextItem()
Get the initial context item for the query, if one has been set- Returns:
- the initial context item, or null if none has been set. This will not necessarily be the same object as was supplied, but it will be an XdmItem object that represents the same underlying node or atomic value.
-
setExternalVariable
public void setExternalVariable(QName name, XdmValue value)
Set the value of external variable defined in the query- Parameters:
name
- the name of the external variable, as a QNamevalue
- the value of the external variable, or null to clear a previously set value
-
getExternalVariable
public XdmValue getExternalVariable(QName name)
Get the value that has been set for an external variable- Parameters:
name
- the name of the external variable whose value is required- Returns:
- the value that has been set for the external variable, or null if no value has been set
-
setURIResolver
public void setURIResolver(javax.xml.transform.URIResolver resolver)
Set an object that will be used to resolve URIs used in fn:doc() and related functions.- Parameters:
resolver
- An object that implements the URIResolver interface, or null.
-
getURIResolver
public javax.xml.transform.URIResolver getURIResolver()
Get the URI resolver.- Returns:
- the user-supplied URI resolver if there is one, or the system-defined one otherwise
-
setErrorListener
public void setErrorListener(javax.xml.transform.ErrorListener listener)
Set the error listener. The error listener receives reports of all run-time errors and can decide how to report them.- Parameters:
listener
- the ErrorListener to be used
-
getErrorListener
public javax.xml.transform.ErrorListener getErrorListener()
Get the error listener.- Returns:
- the ErrorListener in use
-
setTraceListener
public void setTraceListener(TraceListener listener)
Set a TraceListener which will receive messages relating to the evaluation of all expressions. This option has no effect unless the query was compiled to enable tracing.- Parameters:
listener
- the TraceListener to use
-
getTraceListener
public TraceListener getTraceListener()
Get the registered TraceListener, if any- Returns:
- listener the TraceListener in use, or null if none has been set
-
setTraceFunctionDestination
public void setTraceFunctionDestination(java.io.PrintStream stream)
Set the destination for output from the fn:trace() function. By default, the destination is System.err. If a TraceListener is in use, this is ignored, and the trace() output is sent to the TraceListener.- Parameters:
stream
- the PrintStream to which trace output will be sent. If set to null, trace output is suppressed entirely. It is the caller's responsibility to close the stream after use.- Since:
- 9.1
-
getTraceFunctionDestination
public java.io.PrintStream getTraceFunctionDestination()
Get the destination for output from the fn:trace() function.- Returns:
- the PrintStream to which trace output will be sent. If no explicitly destination has been set, returns System.err. If the destination has been set to null to suppress trace output, returns null.
- Since:
- 9.1
-
setDestination
public void setDestination(Destination destination)
Set the destination to be used for the query results- Parameters:
destination
- the destination to which the results of the query will be sent
-
run
public void run() throws SaxonApiException
Perform the query.- In the case of a non-updating query, the results are sent to the registered Destination.
- In the case of an updating query, all updated documents will be available after query
execution as the result of the
getUpdatedDocuments()
method.
- Throws:
SaxonApiException
- if any dynamic error occurs during the queryjava.lang.IllegalStateException
- if this is a non-updating query and no Destination has been supplied for the query results
-
run
public void run(Destination destination) throws SaxonApiException
Perform the query, sending the results to a specified destination. This method must not be used with an updating query- Parameters:
destination
- The destination where the result document will be sent- Throws:
SaxonApiException
- if any dynamic error occurs during the queryjava.lang.IllegalStateException
- if this is an updating query
-
evaluate
public XdmValue evaluate() throws SaxonApiException
Perform the query, returning the results as an XdmValue. This method must not be used with an updating query- Returns:
- an XdmValue representing the results of the query
- Throws:
SaxonApiException
- if the query fails with a dynamic errorjava.lang.IllegalStateException
- if this is an updating query
-
iterator
public java.util.Iterator<XdmItem> iterator() throws SaxonApiUncheckedException
Get an iterator over the results of the query. This method must not be used with an updating query- Specified by:
iterator
in interfacejava.lang.Iterable<XdmItem>
- Throws:
SaxonApiUncheckedException
- if a dynamic error is detected while constructing the iterator. It is also possible for an SaxonApiUncheckedException to be thrown by the hasNext() method of the returned iterator if a dynamic error occurs while evaluating the result sequence.java.lang.IllegalStateException
- if this is an updating query
-
getUpdatedDocuments
public java.util.Iterator<XdmNode> getUpdatedDocuments()
After executing an updating query using therun()
method, iterate over the root nodes of the documents updated by the query.The results remain available until a new query is executed. This method returns the results of the most recently executed query. It does not consume the results.
- Returns:
- an iterator over the root nodes of documents (or other trees) that were updated by the query
- Since:
- 9.1
-
getUnderlyingQueryContext
public DynamicQueryContext getUnderlyingQueryContext()
Get the underlying dynamic context object. This provides an escape hatch to the underlying implementation classes, which contain methods that may change from one release to another.- Returns:
- the underlying object representing the dynamic context for query execution
-
-