net.sf.saxon.xqj
Class SaxonXQPreparedExpression

java.lang.Object
  net.sf.saxon.xqj.Closable
      net.sf.saxon.xqj.SaxonXQDynamicContext
          net.sf.saxon.xqj.SaxonXQPreparedExpression

All Implemented Interfaces:

XQDynamicContext, XQPreparedExpression

public class SaxonXQPreparedExpression
extends SaxonXQDynamicContext
implements XQPreparedExpression

Saxon implementation of the XQJ interface XQPreparedExpression. This represents a compiled XQuery expression, together with the dynamic context for its evaluation. Note that this means the object should not be used in more than one thread concurrently.

Note that an expression is scrollable or not depending on the scrollability property of the XQConnection that was used to compile this expression (at the time it was compiled). If the expression is scrollable then its results are delivered in an XQSequence that supports scrolling backwards as well as forwards.

For full Javadoc details, see the XQJ interface specification.

Field Summary

Fields inherited from class net.sf.saxon.xqj.SaxonXQDynamicContext

connection

Constructor Summary

protected

SaxonXQPreparedExpression(SaxonXQConnection connection, XQueryExpression expression, SaxonXQStaticContext sqc, DynamicQueryContext context)

Method Summary

void	cancel() Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an XQPreparedExpression.
XQResultSequence	executeQuery() Executes the prepared query expression.
protected boolean	externalVariableExists(QName name)
QName[]	getAllExternalVariables() Retrieves all the external variables defined in the prolog of the prepared expression.
QName[]	getAllUnboundExternalVariables() Retrieves the names of all unbound external variables.
protected SaxonXQConnection	getConnection()
protected SaxonXQDataFactory	getDataFactory()
protected DynamicQueryContext	getDynamicContext()
protected SaxonXQStaticContext	getSaxonXQStaticContext()
XQStaticContext	getStaticContext() Gets an XQStaticContext representing the values for all expression properties.
XQSequenceType	getStaticResultType() Gets the static type information of the result sequence.
XQSequenceType	getStaticVariableType(QName name) Retrieves the static type of a given external variable.
protected XQueryExpression	getXQueryExpression()

Methods inherited from class net.sf.saxon.xqj.SaxonXQDynamicContext

bindAtomicValue, bindBoolean, bindByte, bindDocument, bindDocument, bindDocument, bindDocument, bindDocument, bindDouble, bindFloat, bindInt, bindItem, bindLong, bindNode, bindObject, bindSequence, bindShort, bindString, getConfiguration, getImplicitTimeZone, setImplicitTimeZone

Methods inherited from class net.sf.saxon.xqj.Closable

close, isClosed, setClosableContainer

Methods inherited from class java.lang.Object

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

Methods inherited from interface javax.xml.xquery.XQPreparedExpression

close, isClosed

Methods inherited from interface javax.xml.xquery.XQDynamicContext

bindAtomicValue, bindBoolean, bindByte, bindDocument, bindDocument, bindDocument, bindDocument, bindDocument, bindDouble, bindFloat, bindInt, bindItem, bindLong, bindNode, bindObject, bindSequence, bindShort, bindString, getImplicitTimeZone, setImplicitTimeZone

Constructor Detail

SaxonXQPreparedExpression

protected SaxonXQPreparedExpression(SaxonXQConnection connection,
                                    XQueryExpression expression,
                                    SaxonXQStaticContext sqc,
                                    DynamicQueryContext context)
                             throws XQException

Throws:

XQException

Method Detail

getDynamicContext

protected DynamicQueryContext getDynamicContext()

Specified by:

getDynamicContext in class SaxonXQDynamicContext

getConnection

protected SaxonXQConnection getConnection()

getDataFactory

protected SaxonXQDataFactory getDataFactory()
                                     throws XQException

Specified by:

getDataFactory in class SaxonXQDynamicContext

Throws:

XQException

getXQueryExpression

protected XQueryExpression getXQueryExpression()

getSaxonXQStaticContext

protected SaxonXQStaticContext getSaxonXQStaticContext()

cancel

public void cancel()
            throws XQException

Description copied from interface: XQPreparedExpression

Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an XQPreparedExpression. This method can be used by one thread to cancel an XQPreparedExpression, that is being executed in another thread. If cancellation is not supported or the attempt to cancel the execution was not successful, the method returns without any error. If the cancellation is successful, an XQException is thrown, to indicate that it has been aborted, by executeQuery, executeCommand or any method accessing the XQResultSequence returned by executeQuery. If applicable, any open XQResultSequence and XQResultItem objects will also be implicitly closed in this case.

Specified by:

cancel in interface XQPreparedExpression

Throws:

XQException - if the prepared expression is in a closed state

executeQuery

public XQResultSequence executeQuery()
                              throws XQException

Description copied from interface: XQPreparedExpression

Executes the prepared query expression. Calling this method implicitly closes any previous result sequence obtained from this expression.

Specified by:

executeQuery in interface XQPreparedExpression

Returns:

the xquery sequence object containing the result of the query execution

Throws:

XQException - if (1) there are errors when executing the prepared expression, (2) the prepared expression is in a closed state, or (3) the query execution is cancelled

getAllExternalVariables

public QName[] getAllExternalVariables()
                                throws XQException

Description copied from interface: XQPreparedExpression

Retrieves all the external variables defined in the prolog of the prepared expression.

Specified by:

getAllExternalVariables in interface XQPreparedExpression

Returns:

an array of QName objects for all the external variables defined in the prolog of a prepared expression. Empty array if there are no external variables present.

Throws:

XQException - if the prepared expression is in a closed state

getAllUnboundExternalVariables

public QName[] getAllUnboundExternalVariables()
                                       throws XQException

Description copied from interface: XQPreparedExpression

Retrieves the names of all unbound external variables.

Specified by:

getAllUnboundExternalVariables in interface XQPreparedExpression

Returns:

the QName for all the external variables defined in the prolog of a prepared expression that are yet to be bound with a value. If there are no such variables an empty array is returned

Throws:

XQException - if the prepared expression is in a closed state

getStaticContext

public XQStaticContext getStaticContext()
                                 throws XQException

Description copied from interface: XQPreparedExpression

Gets an XQStaticContext representing the values for all expression properties. Note that these properties cannot be changed; in order to change, a new XQPreparedExpression needs to be created.

Specified by:

getStaticContext in interface XQPreparedExpression

Returns:

an XQStaticContext representing the values for all expression properties

Throws:

XQException - if the expression is in a closed state

getStaticResultType

public XQSequenceType getStaticResultType()
                                   throws XQException

Description copied from interface: XQPreparedExpression

Gets the static type information of the result sequence. If an implementation does not do static typing of the query, then this method must return an XQSequenceType object corresponding to the XQuery sequence type item()*.

Specified by:

getStaticResultType in interface XQPreparedExpression

Returns:

XQSequenceType containing the static result information.

Throws:

XQException - if the prepared expression is in a closed state

getStaticVariableType

public XQSequenceType getStaticVariableType(QName name)
                                     throws XQException

Description copied from interface: XQPreparedExpression

Retrieves the static type of a given external variable.

Specified by:

getStaticVariableType in interface XQPreparedExpression

Parameters:

name - the name of the external variable

Returns:

the static type information of the variable as defined in the prolog of the prepared expression

Throws:

XQException - if (1) the variable does not exist in the static context of the expression, or (2) the sequence is in a closed state, or (3) the name parameter is null

externalVariableExists

protected boolean externalVariableExists(QName name)

Specified by:

externalVariableExists in class SaxonXQDynamicContext