| java.lang.Object
 net.sf.saxon.query.XQueryExpression
| XQueryExpression | | public class XQueryExpression implements Container(Code) | | 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.
|
| Method Summary | |
| public List | evaluate(DynamicQueryContext env)
Execute a the compiled Query, returning the results as a List.
Parameters:
env - Provides the dynamic query evaluation context The results of the expression, as a List. | | public Object | evaluateSingle(DynamicQueryContext env)
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 The first item in the sequence returned by the expression. | | public void | explain(NamePool pool)
Diagnostic method: display a representation of the compiled query on the
System.err output stream. | | public int | getColumnNumber()
Return the character position where the current document event ends. | | public Controller | getController()
| | public Executable | getExecutable()
| | public Expression | getExpression()
| | public int | getLineNumber()
Return the line number where the current document event ends. | | public LocationProvider | getLocationProvider()
Get the LocationProvider allowing location identifiers to be resolved. | | public String | getPublicId()
Return the public identifier for the current document event. | | public StaticQueryContext | getStaticContext()
Get the static context in which this expression was compiled. | | public String | getSystemId()
Return the system identifier for the current document event. | | public SequenceIterator | iterator(DynamicQueryContext env)
Get an iterator over the results of the expression. | | public Controller | newController()
Get a controller that can be used to execute functions in this compiled query.
Functions in the query module can be found using
StaticQueryContext.getUserDefinedFunction .
They can then be called directly from the Java application using
net.sf.saxon.instruct.UserFunction.call The same Controller can be used for a series of function calls.
Note, this method is poorly named. | | public void | pull(DynamicQueryContext dynamicEnv, Result destination, Properties outputProperties)
Run the query in pull mode. | | public void | run(DynamicQueryContext env, Result result, Properties outputProperties)
Run the query, sending the results directly to a JAXP Result object. | | protected void | setDocumentInstruction(DocumentInstr doc)
|
| evaluate | | public List evaluate(DynamicQueryContext env) throws XPathException(Code) | | Execute a the compiled Query, returning the results as a List.
Parameters:
env - Provides the dynamic query evaluation context The results of the expression, as a List. The List represents the sequenceof items returned by the expression. Each item in the list will either be anobject representing a node, or an object representing an atomic value.For the types of Java object that may be returned, see the description of thenet.sf.saxon.xpath.XPathEvaluator.evaluate evaluate methodof class XPathProcessor |
| evaluateSingle | | public Object evaluateSingle(DynamicQueryContext env) throws XPathException(Code) | | 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 The first item in the sequence returned by the expression. If the expressionreturns an empty sequence, this method returns null. Otherwise, it returns the firstitem in the result sequence, represented as a Java object using the same mapping as forthe XQueryExpression.evaluate evaluate method |
| explain | | public void explain(NamePool pool)(Code) | | Diagnostic method: display a representation of the compiled query on the
System.err output stream.
|
| getColumnNumber | | public int getColumnNumber()(Code) | | Return the character position where the current document event ends.
Warning: The return value from the method
is intended only as an approximation for the sake of error
reporting; it is not intended to provide sufficient information
to edit the character content of the original XML document.
The return value is an approximation of the column number
in the document entity or external parsed entity where the
markup that triggered the event appears.
The column number, or -1 if none is available.
See Also: XQueryExpression.getLineNumber |
| getExecutable | | public Executable getExecutable()(Code) | | Get the Executable (representing a complete stylesheet or query) of which this Container forms part
|
| getExpression | | public Expression getExpression()(Code) | | Get the expression wrapped in this XQueryExpression object
the underlying expression |
| getLineNumber | | public int getLineNumber()(Code) | | Return the line number where the current document event ends.
Warning: The return value from the method
is intended only as an approximation for the sake of error
reporting; it is not intended to provide sufficient information
to edit the character content of the original XML document.
The return value is an approximation of the line number
in the document entity or external parsed entity where the
markup that triggered the event appears.
The line number, or -1 if none is available.
See Also: XQueryExpression.getColumnNumber |
| getLocationProvider | | public LocationProvider getLocationProvider()(Code) | | Get the LocationProvider allowing location identifiers to be resolved.
|
| getPublicId | | public String getPublicId()(Code) | | Return the public identifier for the current document event.
The return value is the public identifier of the document
entity or of the external parsed entity in which the markup that
triggered the event appears.
A string containing the public identifier, ornull if none is available.
See Also: XQueryExpression.getSystemId |
| getStaticContext | | public StaticQueryContext getStaticContext()(Code) | | Get the static context in which this expression was compiled. Note, this will be an internal
copy of the original user-created StaticQueryContext object. The user-created object is not modified
by Saxon, whereas the copy includes additional information found in the query prolog.
the internal copy of the StaticQueryContext |
| getSystemId | | public String getSystemId()(Code) | | Return the system identifier for the current document event.
The return value is the system identifier of the document
entity or of the external parsed entity in which the markup that
triggered the event appears.
If the system identifier is a URL, the parser must resolve it
fully before passing it to the application.
A string containing the system identifier, or nullif none is available.
See Also: XQueryExpression.getPublicId |
| iterator | | public SequenceIterator iterator(DynamicQueryContext env) throws XPathException(Code) | | 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 an iterator over the results of the query. The class SequenceIteratoris modeled on the standard Java Iterator class, but has extra functionalityand can throw exceptions when errors occur.
throws:
XPathException - if a dynamic error occurs in evaluating the query. Somedynamic errors will not be reported by this method, but will only be reportedwhen the individual items of the result are accessed using the returned iterator. |
| newController | | public Controller newController()(Code) | | Get a controller that can be used to execute functions in this compiled query.
Functions in the query module can be found using
StaticQueryContext.getUserDefinedFunction .
They can then be called directly from the Java application using
net.sf.saxon.instruct.UserFunction.call The same Controller can be used for a series of function calls.
Note, this method is poorly named. It creates a new Controller each time it is called: which is useful
when a query is to be executed repeatedly.
|
| run | | public void run(DynamicQueryContext env, Result result, Properties outputProperties) throws XPathException(Code) | | Run the query, sending the results directly to a JAXP Result object. This way of executing
the query is most efficient in the case of queries that produce a single document (or parentless
element) as their output, because it avoids constructing the result tree in memory: instead,
it is piped straight to the serializer.
Parameters:
env - the dynamic query context
Parameters:
result - the destination for the results of the query. The query is effectively wrappedin a document{} constructor, so that the items in the result are concatenated to form a singledocument; this is then written to the requested Result destination, which may be (for example)a DOMResult, a SAXResult, or a StreamResult
Parameters:
outputProperties - Supplies serialization properties, in JAXP format, if the result is tobe serialized. This parameter can be defaulted to null.
throws:
XPathException - if the query fails. |
|
|