Package com.saxonica.ee.optim

Class XQueryExpressionEE

java.lang.Object

net.sf.saxon.query.XQueryExpression

com.saxonica.ee.optim.XQueryExpressionEE

All Implemented Interfaces:

javax.xml.transform.SourceLocator, ExpressionOwner, Locatable, Location, Traceable, TraceableComponent, org.xml.sax.Locator

public class XQueryExpressionEE
extends XQueryExpression

Saxon-EE version of XQueryExpression. Supports additional EE features including XQuery update, bytecode generation, document projection, streaming

Field Summary

Fields inherited from class net.sf.saxon.query.XQueryExpression

executable, expression, mainModule, stackFrameMap

Constructor Summary

Constructors

Constructor	Description
XQueryExpressionEE(Expression exp, QueryModule mainModule, boolean streaming)

Method Summary

Modifier and Type	Method	Description
void	explainPathMap()	Output the path map of the query for diagnostics
PathMap	getPathMap()	Get the path map for the query expression
boolean	isDocumentProjectionAllowed()	Ask whether document projection is allowed
boolean	isUpdateQuery()	Ask whether this is an update query
Controller	newController(DynamicQueryContext env)	Get a controller that can be used to execute functions in this compiled query.
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.
void	setAllowDocumentProjection(boolean allowed)	Indicate that document projection is or is not allowed

Methods inherited from class net.sf.saxon.query.XQueryExpression

closeStreamIfNecessary, evaluate, evaluateSingle, explain, getBody, getChildExpression, getColumnNumber, getConfiguration, getExecutable, getExpression, getExternalVariableNames, getHostLanguage, getLineNumber, getLocation, getMainModule, getObjectName, getPackageData, getPublicId, getStackFrameMap, getSystemId, getTracingTag, initialContext, iterator, run, saveLocation, setBody, setChildExpression, usesContextItem, validateOutputProperties

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.sf.saxon.trace.Traceable

gatherProperties

Constructor Detail

XQueryExpressionEE

public XQueryExpressionEE(Expression exp,
                          QueryModule mainModule,
                          boolean streaming)
                   throws XPathException

Throws:

XPathException

Method Detail

isUpdateQuery

public boolean isUpdateQuery()

Ask whether this is an update query

Overrides:

isUpdateQuery in class XQueryExpression

Returns:

true if the body of the query is an updating expression (as defined by the XQuery Update specification). Note that a query can use Update syntax (notably the copy-modify syntax) without being an updating expression.

setAllowDocumentProjection

public void setAllowDocumentProjection(boolean allowed)

Indicate that document projection is or is not allowed

Overrides:

setAllowDocumentProjection in class XQueryExpression

Parameters:

allowed - true if projection is allowed

isDocumentProjectionAllowed

public boolean isDocumentProjectionAllowed()

Ask whether document projection is allowed

Overrides:

isDocumentProjectionAllowed in class XQueryExpression

Returns:

true if document projection is allowed

getPathMap

public PathMap getPathMap()

Get the path map for the query expression

Returns:

the path map (which is constructed if this has not already been done)

newController

public Controller newController(DynamicQueryContext env)
                         throws XPathException

Get a controller that can be used to execute functions in this compiled query. Functions in the query module can be found using 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.

Overrides:

newController in class XQueryExpression

Parameters:

env - the dynamic context for evaluation

Returns:

a newly constructed Controller

Throws:

XPathException - if evaluation fails with a dynamic error

runUpdate

public java.util.Set<MutableNodeInfo> runUpdate(DynamicQueryContext dynamicEnv)
                                         throws XPathException

Run an updating query

Overrides:

runUpdate in class XQueryExpression

Parameters:

dynamicEnv - the dynamic context for query execution

Returns:

a set of nodes representing the roots of trees that have been modified as a result of executing the update. Note that this method will never modify persistent data on disk; it returns the root nodes of the affected documents (which will often be document nodes whose document-uri can be ascertained), and it is the caller's responsibility to decide what to do with them.

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.

Throws:

XPathException - if evaluation of the update query fails, or it this is not an updating query

runUpdate

public void runUpdate(DynamicQueryContext dynamicEnv,
                      UpdateAgent agent)
               throws XPathException

Run an updating query, writing back eligible updated node to persistent storage.

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

Overrides:

runUpdate in class XQueryExpression

Parameters:

dynamicEnv - the dynamic context for query execution

agent - a callback class that is called to process each document updated by the query

Throws:

XPathException - if evaluation of the update query fails, or it this is not an updating query

runStreamed

public void runStreamed(DynamicQueryContext dynamicEnv,
                        javax.xml.transform.Source source,
                        javax.xml.transform.Result result,
                        java.util.Properties outputProperties)
                 throws XPathException

Run the query in streaming mode, assuming it has been compiled for streaming

Overrides:

runStreamed in class XQueryExpression

Parameters:

dynamicEnv - the dynamic execution context

source - the input document, as a SAXSource or StreamSource

result - the destination for the query results

outputProperties - serialization options for the query result

Throws:

XPathException - if streamed evaluation of the query fails

explainPathMap

public void explainPathMap()

Output the path map of the query for diagnostics

Overrides:

explainPathMap in class XQueryExpression