public class XQueryExpression extends java.lang.Object implements Location, ExpressionOwner
Various methods are provided for evaluating the query, with different options for delivery of the results.
Modifier and Type | Field and Description |
---|---|
protected Executable |
executable |
protected Expression |
expression |
protected QueryModule |
mainModule |
protected SlotManager |
stackFrameMap |
Constructor and Description |
---|
XQueryExpression(Expression exp,
QueryModule mainModule,
boolean streaming)
The constructor is protected, to ensure that instances can only be
created using the compileQuery() methods of StaticQueryContext
|
Modifier and Type | Method and Description |
---|---|
java.util.List<java.lang.Object> |
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(ExpressionPresenter out)
Diagnostic method: display a representation of the compiled query on the
selected output stream.
|
void |
explainPathMap()
Output the path map of the query for diagnostics
|
int |
getColumnNumber()
Return the character position where the current document event ends.
|
Configuration |
getConfiguration()
Get the Configuration to which this Container belongs
|
Executable |
getExecutable()
Get the Executable (representing a complete stylesheet or query) of which this Container forms part
|
Expression |
getExpression()
Get the expression wrapped in this XQueryExpression object
|
StructuredQName[] |
getExternalVariableNames()
Get a list containing the names of the external variables in the query.
|
int |
getHostLanguage()
Get the host language (XSLT, XQuery, XPath) used to implement the code in this container
|
int |
getLineNumber()
Return the line number where the current document event ends.
|
QueryModule |
getMainModule()
Get the static context in which this expression was compiled.
|
PackageData |
getPackageData()
Get data about the unit of compilation (XQuery module, XSLT package) to which this
container belongs
|
java.lang.String |
getPublicId()
Return the public identifier for the current document event.
|
SlotManager |
getStackFrameMap()
Get the stack frame map used for the outermost level of this query
|
java.lang.String |
getSystemId()
Return the system identifier for the current document event.
|
protected XPathContextMajor |
initialContext(DynamicQueryContext dynamicEnv,
Controller controller) |
boolean |
isDocumentProjectionAllowed()
Ask whether document projection is allowed
|
boolean |
isUpdateQuery()
Ask whether this is an update query
|
SequenceIterator |
iterator(DynamicQueryContext env)
Get an iterator over the results of the expression.
|
Controller |
newController(DynamicQueryContext env)
Get a controller that can be used to execute functions in this compiled query.
|
void |
pull(DynamicQueryContext dynamicEnv,
javax.xml.transform.Result destination,
java.util.Properties outputProperties)
Deprecated.
since 9.8.
|
void |
pull(DynamicQueryContext dynamicEnv,
SequenceReceiver destination)
Deprecated.
since 9.8.
|
void |
run(DynamicQueryContext env,
javax.xml.transform.Result result,
java.util.Properties outputProperties)
Run the query, sending the results directly to a JAXP Result object.
|
void |
runStreamed(DynamicQueryContext dynamicEnv,
javax.xml.transform.Source source,
javax.xml.transform.Result result,
java.util.Properties outputProperties)
Run the query in streaming mode, assuming it has been compiled for streaming.
|
java.util.Set<MutableNodeInfo> |
runUpdate(DynamicQueryContext dynamicEnv)
Run an updating query
|
void |
runUpdate(DynamicQueryContext dynamicEnv,
UpdateAgent agent)
Run an updating query, writing back eligible updated node to persistent storage.
|
Location |
saveLocation()
Get an immutable copy of this Location object.
|
void |
setAllowDocumentProjection(boolean allowed)
Indicate that document projection is or is not allowed
|
void |
setChildExpression(Expression expr) |
boolean |
usesContextItem()
Ask whether this query uses the context item
|
protected java.util.Properties |
validateOutputProperties(Controller controller,
java.util.Properties outputProperties) |
protected Expression expression
protected SlotManager stackFrameMap
protected Executable executable
protected QueryModule mainModule
public XQueryExpression(Expression exp, QueryModule mainModule, boolean streaming) throws XPathException
exp
- an expression to be wrapped as an XQueryExpressionmainModule
- the static context of the main modulestreaming
- true if streamed execution is requestedXPathException
- if an error occurspublic Expression getExpression()
public PackageData getPackageData()
public Configuration getConfiguration()
public boolean usesContextItem()
public boolean isUpdateQuery()
public SlotManager getStackFrameMap()
public void explainPathMap()
public QueryModule getMainModule()
public StructuredQName[] getExternalVariableNames()
Changed in Saxon 9.0 to return an array of StructuredQName objects rather than integer fingerprints.
public java.util.List<java.lang.Object> evaluate(DynamicQueryContext env) throws XPathException
env
- Provides the dynamic query evaluation contextevaluate
method
of class XPathProcessorXPathException
- if a dynamic error occurs during query evaluationpublic java.lang.Object evaluateSingle(DynamicQueryContext env) throws XPathException
env
- Provides the dynamic query evaluation contextevaluate
methodXPathException
- if evaluation fails with a dynamic errorpublic SequenceIterator iterator(DynamicQueryContext env) throws XPathException
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.
env
- Provides the dynamic query evaluation contextXPathException
- 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.public void run(DynamicQueryContext env, javax.xml.transform.Result result, java.util.Properties outputProperties) throws XPathException
If the output method specified in the outputProperties, or declared in the query itself, is one of XML, HTML, XHTML, or TEXT, or if it is defaulted to XML, then the query is implicitly wrapped in a document node constructor to implement the "sequence normalization" phase described in the Serialization specification. If the output method is JSON or ADAPTIVE then this phase is skipped and the items produced by the query are piped straight into the serializer.
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.XPathException
- if the query fails.public void runStreamed(DynamicQueryContext dynamicEnv, javax.xml.transform.Source source, javax.xml.transform.Result result, java.util.Properties outputProperties) throws XPathException
dynamicEnv
- the dynamic execution contextsource
- the input document, as a SAXSource or StreamSourceresult
- the destination for the query resultsoutputProperties
- serialization options for the query resultXPathException
- if streamed evaluation of the query failsprotected java.util.Properties validateOutputProperties(Controller controller, java.util.Properties outputProperties) throws XPathException
XPathException
public void pull(DynamicQueryContext dynamicEnv, javax.xml.transform.Result destination, java.util.Properties outputProperties) throws XPathException
run(DynamicQueryContext, Result, Properties)
dynamicEnv
- the dynamic context for query evaluationdestination
- the Receiver to accept the query results *usually a serializer)XPathException
- if a dynamic error occurs during the evaluationpublic void pull(DynamicQueryContext dynamicEnv, SequenceReceiver destination) throws XPathException
run(DynamicQueryContext, Result, Properties)
(supplying the default serialization properties from the configuration as the third argument)dynamicEnv
- the dynamic context for query evaluationdestination
- the Receiver to accept the query results *usually a serializer)XPathException
- if a dynamic error occurs during the evaluationpublic java.util.Set<MutableNodeInfo> runUpdate(DynamicQueryContext dynamicEnv) throws XPathException
dynamicEnv
- the dynamic context for query executionOn completion of this method it is generally unsafe to rely on the contents or relationships of NodeInfo objects that were obtained before the updating query was run. Such objects may or may not reflect the results of the update operations. This is especially true in the case of nodes that are part of a subtree that has been deleted (detached from its parent). Instead, the new updated tree should be accessed by navigation from the root nodes returned by this method.
XPathException
- if evaluation of the update query fails, or it this is not an updating querypublic void runUpdate(DynamicQueryContext dynamicEnv, UpdateAgent agent) throws XPathException
A node is eligible to be written back to disk if it is present in the document pool, which generally means that it was originally read using the doc() or collection() function.
On completion of this method it is generally unsafe to rely on the contents or relationships of NodeInfo objects that were obtained before the updating query was run. Such objects may or may not reflect the results of the update operations. This is especially true in the case of nodes that are part of a subtree that has been deleted (detached from its parent). Instead, the new updated tree should be accessed by navigation from the root nodes returned by this method.
If one or more eligible updated nodes cannot be written back to disk, perhaps because the URI identifies a non-updatable location, then an exception is thrown. In this case it is undefined
dynamicEnv
- the dynamic context for query executionagent
- a callback class that is called to process each document updated by the queryXPathException
- if evaluation of the update query fails, or it this is not an updating queryprotected XPathContextMajor initialContext(DynamicQueryContext dynamicEnv, Controller controller) throws XPathException
XPathException
public Controller newController(DynamicQueryContext env) throws XPathException
QueryModule.getUserDefinedFunction(java.lang.String, java.lang.String, int)
.
They can then be called directly from the Java application using UserFunction.call(net.sf.saxon.expr.XPathContext, net.sf.saxon.om.Sequence[])
The same Controller can be used for a series of function calls. Note that the Controller should only be used
in a single thread.env
- the dynamic context for evaluationXPathException
- if evaluation fails with a dynamic errorpublic void explain(ExpressionPresenter out) throws XPathException
out
- an ExpressionPresenter to which the XML representation of the compiled query
will be sentXPathException
public Executable getExecutable()
public void setAllowDocumentProjection(boolean allowed)
allowed
- true if projection is allowedpublic boolean isDocumentProjectionAllowed()
public java.lang.String getPublicId()
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.
getPublicId
in interface javax.xml.transform.SourceLocator
getPublicId
in interface Location
getPublicId
in interface org.xml.sax.Locator
getSystemId()
public java.lang.String getSystemId()
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.
getSystemId
in interface javax.xml.transform.SourceLocator
getSystemId
in interface Location
getSystemId
in interface org.xml.sax.Locator
getPublicId()
public int getLineNumber()
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.
getLineNumber
in interface javax.xml.transform.SourceLocator
getLineNumber
in interface Location
getLineNumber
in interface org.xml.sax.Locator
getColumnNumber()
public int getColumnNumber()
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.
getColumnNumber
in interface javax.xml.transform.SourceLocator
getColumnNumber
in interface Location
getColumnNumber
in interface org.xml.sax.Locator
getLineNumber()
public Location saveLocation()
saveLocation
in interface Location
public int getHostLanguage()
Configuration.XSLT
or Configuration.XQUERY
public void setChildExpression(Expression expr)
setChildExpression
in interface ExpressionOwner
Copyright (c) 2004-2018 Saxonica Limited. All rights reserved.