Interface XQExpression
- All Superinterfaces:
XQDynamicContext
- All Known Implementing Classes:
SaxonXQExpression
XQConnection
and the execution can be done using the executeQuery()
or
executeCommand()
method, passing in the XQuery expression.
All external variables defined in the prolog of the expression to be executed must
be set in the dynamic context of this expression using the bind methods.
Also, variables bound in this expression but not defined as external in
the prolog of the expression to be executed, are simply ignored.
For example, if variables $var1
and $var2
are bound,
but the query only defines $var1
as external, no error
will be reported for the binding of $var2
. It will simply
be ignored.
When the expression is executed using the executeQuery
method, if the execution is successful, then
an XQResultSequence
object is returned.
The XQResultSequence
object is tied to
the XQExpression
from which it was prepared and is
closed implicitly if that XQExpression
is either closed or re-executed.
The XQExpression
object is dependent on
the XQConnection
object from which it was created and is only
valid for the duration of that object.
Thus, if the XQConnection
object is closed then
this XQExpression
object will be implicitly closed
and it can no longer be used.
An XQJ driver is not required to provide finalizer methods for the connection and other objects. Hence it is strongly recommended that users call close method explicitly to free any resources. It is also recommended that they do so under a final block to ensure that the object is closed even when there are exceptions. Not closing this object implicitly or explicitly might result in serious memory leaks.
When the XQExpression
is closed any XQResultSequence
object obtained from it is also implicitly closed.
Example -
XQConnection conn = XQDatasource.getConnection(); XQExpression expr = conn.createExpression(); expr.bindInt(new QName("x"), 21, null); XQSequence result = expr.executeQuery( "declare variable $x as xs:integer external; for $i in $x return $i"); while (result.next()) { // process results ... } // Execute some other expression on the same object XQSequence result = expr.executeQuery("for $i in doc('foo.xml') return $i"); ... result.close(); // close the result expr.close(); conn.close();
-
Method Summary
Modifier and TypeMethodDescriptionvoid
cancel()
Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of anXQExpression
.void
close()
Closes the expression object and release associated resources.void
executeCommand
(Reader cmd) Executes an implementation-defined command.void
executeCommand
(String cmd) Executes an implementation-defined command.executeQuery
(InputStream query) Executes a query expression.executeQuery
(Reader query) Executes a query expression.executeQuery
(String query) Executes a query expression.Gets anXQStaticContext
representing the values for all expression properties.boolean
isClosed()
Checks if the expression is in a closed state.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
-
Method Details
-
cancel
Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of anXQExpression
. This method can be used by one thread to cancel anXQExpression
, 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, anXQException
is thrown, to indicate that it has been aborted, byexecuteQuery
,executeCommand
or any method accessing theXQResultSequence
returned byexecuteQuery
. If applicable, any openXQResultSequence
andXQResultItem
objects will also be implicitly closed in this case.- Throws:
XQException
- if the expression is in a closed state
-
isClosed
boolean isClosed()Checks if the expression is in a closed state.- Returns:
true
if the expression is in a closed state,false
otherwise
-
close
Closes the expression object and release associated resources.Once the expression is closed, all methods on this object other than the
close
orisClosed
will raise exceptions. This also closes any result sequences obtained from this expression. Callingclose
on anXQExpression
object that is already closed has no effect.- Throws:
XQException
- if there are errors when closing the expression
-
executeCommand
Executes an implementation-defined command. Calling this method implicitly closes any previous result sequence obtained from this expression.- Parameters:
cmd
- the input command as a string- Throws:
XQException
- if (1) there are errors when executing the command, or (2) the expression is in a closed state
-
executeCommand
Executes an implementation-defined command. Calling this method implicitly closes any previous result sequence obtained from this expression.- Parameters:
cmd
- the input command as a string reader- Throws:
XQException
- if (1) there are errors when executing the command, (2) the expression is in a closed state, or (3) the execution is cancelled
-
executeQuery
Executes a query expression. This implicitly closes any previous result sequences obtained from this expression.- Parameters:
query
- the input query expression string. Cannot benull
- Returns:
- an
XQResultSequence
object containing the result of the query execution - Throws:
XQException
- if (1) there are errors when executing the query, (2) the expression is in a closed state, (3) the execution is cancelled, (4) the query parameter isnull
-
executeQuery
Executes a query expression. This implicitly closes any previous result sequences obtained from this expression.- Parameters:
query
- the input query expression as a reader object. Cannot benull
- Returns:
- an
XQResultSequence
object containing the result of the query execution - Throws:
XQException
- if (1) there are errors when executing the query, (2) the expression is in a closed state, (3) the execution is cancelled, or (4) the query parameter isnull
-
executeQuery
Executes a query expression. This implicitly closes any previous result sequences obtained from this expression.If the query specifies a version declaration including an encoding, the XQJ implementation may try use this information to parse the query. In absence of the version declaration, the assumed encoding is implementation dependent.
- Parameters:
query
- the input query expression as a input stream object. Cannot benull
- Returns:
- an
XQResultSequence
containing the result of the query execution - Throws:
XQException
- if (1) there are errors when executing the query, (2) the expression is in a closed state, (3) the execution is cancelled, or (4) the xquery parameter isnull
-
getStaticContext
Gets anXQStaticContext
representing the values for all expression properties. Note that these properties cannot be changed; in order to change, a newXQExpression
needs to be created.- Returns:
- an
XQStaticContext
representing the values for all expression properties - Throws:
XQException
- if the expression is in a closed state
-