Class XQueryExpression
- All Implemented Interfaces:
SourceLocator
,Container
Various methods are provided for evaluating the query, with different options for delivery of the results.
-
Constructor Summary
ConstructorsModifierConstructorDescriptionprotected
XQueryExpression
(Expression exp, Executable exec, StaticQueryContext staticEnv, Configuration config) The constructor is protected, to ensure that instances can only be created using the compileQuery() methods of StaticQueryContext -
Method Summary
Modifier and TypeMethodDescriptionExecute a the compiled Query, returning the results as a List.Execute the compiled Query, returning the first item in the result.void
explain
(Configuration config) Diagnostic method: display a representation of the compiled query on the System.err output stream.int
Return the character position where the current document event ends.Deprecated.since 8.5.1 - use newController()Get the Executable (representing a complete stylesheet or query) of which this Container forms partGet the expression wrapped in this XQueryExpression objectint[]
Get a list containing the fingerprints of the names of the external variables in the queryint
Get the host language (XSLT, XQuery, XPath) used to implement the code in this containerint
Return the line number where the current document event ends.Get the LocationProvider allowing location identifiers to be resolved.Return the public identifier for the current document event.Get the static context in which this expression was compiled.Return the system identifier for the current document event.Get an iterator over the results of the expression.Get a controller that can be used to execute functions in this compiled query.void
pull
(DynamicQueryContext dynamicEnv, Result destination, Properties outputProperties) Run the query in pull mode.boolean
replaceSubExpression
(Expression original, Expression replacement) Replace one subexpression by a replacement subexpression.void
run
(DynamicQueryContext env, Result result, Properties outputProperties) Run the query, sending the results directly to a JAXP Result object.
-
Constructor Details
-
XQueryExpression
protected XQueryExpression(Expression exp, Executable exec, StaticQueryContext staticEnv, Configuration config) throws XPathException The constructor is protected, to ensure that instances can only be created using the compileQuery() methods of StaticQueryContext- Throws:
XPathException
-
-
Method Details
-
getExpression
Get the expression wrapped in this XQueryExpression object- Returns:
- the underlying expression
-
replaceSubExpression
Replace one subexpression by a replacement subexpression. For internal use only- Specified by:
replaceSubExpression
in interfaceContainer
- Parameters:
original
- the original subexpressionreplacement
- the replacement subexpression- Returns:
- true if the original subexpression is found
-
getStaticContext
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.- Returns:
- the internal copy of the StaticQueryContext. This is available for inspection, but should not be modified or reused by the application.
-
getExternalVariableNames
public int[] getExternalVariableNames()Get a list containing the fingerprints of the names of the external variables in the query- Returns:
- an array of integers, being the integer fingerprints of external variables
-
evaluate
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 - Throws:
XPathException
-
evaluateSingle
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 - Throws:
XPathException
-
iterator
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.
-
run
public void run(DynamicQueryContext env, Result result, Properties outputProperties) throws XPathException 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 contextresult
- the destination for the results of the query. The query is effectively wrapped in a document{} constructor, so that the items in the result are concatenated to form a single document; this is then written to the requested Result destination, which may be (for example) a DOMResult, a SAXResult, or a StreamResultoutputProperties
- Supplies serialization properties, in JAXP format, if the result is to be serialized. This parameter can be defaulted to null.- Throws:
XPathException
- if the query fails.
-
pull
public void pull(DynamicQueryContext dynamicEnv, Result destination, Properties outputProperties) throws XPathException Run the query in pull mode. For maximum effect this method should be used when lazyConstructionMode has been set in the Configuration.- Throws:
XPathException
- See Also:
-
newController
Get a controller that can be used to execute functions in this compiled query. Functions in the query module can be found usingStaticQueryContext.getUserDefinedFunction(java.lang.String, java.lang.String, int)
. They can then be called directly from the Java application usingUserFunction.call(net.sf.saxon.om.ValueRepresentation[], net.sf.saxon.expr.XPathContextMajor)
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. -
getController
Deprecated.since 8.5.1 - use newController()Deprecated synonym fornewController()
-
explain
Diagnostic method: display a representation of the compiled query on the System.err output stream. -
getExecutable
Get the Executable (representing a complete stylesheet or query) of which this Container forms part- Specified by:
getExecutable
in interfaceContainer
-
getLocationProvider
Get the LocationProvider allowing location identifiers to be resolved.- Specified by:
getLocationProvider
in interfaceContainer
-
getPublicId
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.
- Specified by:
getPublicId
in interfaceSourceLocator
- Returns:
- A string containing the public identifier, or null if none is available.
- See Also:
-
getSystemId
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.
- Specified by:
getSystemId
in interfaceSourceLocator
- Returns:
- A string containing the system identifier, or null if none is available.
- See Also:
-
getLineNumber
public int getLineNumber()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.
- Specified by:
getLineNumber
in interfaceSourceLocator
- Returns:
- The line number, or -1 if none is available.
- See Also:
-
getColumnNumber
public int getColumnNumber()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.
- Specified by:
getColumnNumber
in interfaceSourceLocator
- Returns:
- The column number, or -1 if none is available.
- See Also:
-
getHostLanguage
public int getHostLanguage()Get the host language (XSLT, XQuery, XPath) used to implement the code in this container- Specified by:
getHostLanguage
in interfaceContainer
- Returns:
- typically
Configuration.XSLT
orConfiguration.XQUERY
-