Package javax.xml.xquery
Interface XQExpression
-
- All Superinterfaces:
XQDynamicContext
- All Known Implementing Classes:
SaxonXQExpression
public interface XQExpression extends XQDynamicContext
This interface describes the execute immediate functionality for expressions. This object can be created from theXQConnectionand the execution can be done using theexecuteQuery()orexecuteCommand()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$var1and$var2are bound, but the query only defines$var1as external, no error will be reported for the binding of$var2. It will simply be ignored. When the expression is executed using theexecuteQuerymethod, if the execution is successful, then anXQResultSequenceobject is returned. TheXQResultSequenceobject is tied to theXQExpressionfrom which it was prepared and is closed implicitly if thatXQExpressionis either closed or re-executed.
TheXQExpressionobject is dependent on theXQConnectionobject from which it was created and is only valid for the duration of that object. Thus, if theXQConnectionobject is closed then thisXQExpressionobject 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 theXQExpressionis closed anyXQResultSequenceobject 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
All Methods Instance Methods Abstract Methods Modifier and Type Method Description voidcancel()Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of anXQExpression.voidclose()Closes the expression object and release associated resources.voidexecuteCommand(java.io.Reader cmd)Executes an implementation-defined command.voidexecuteCommand(java.lang.String cmd)Executes an implementation-defined command.XQResultSequenceexecuteQuery(java.io.InputStream query)Executes a query expression.XQResultSequenceexecuteQuery(java.io.Reader query)Executes a query expression.XQResultSequenceexecuteQuery(java.lang.String query)Executes a query expression.XQStaticContextgetStaticContext()Gets anXQStaticContextrepresenting the values for all expression properties.booleanisClosed()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 Detail
-
cancel
void cancel() throws XQExceptionAttempts 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, anXQExceptionis thrown, to indicate that it has been aborted, byexecuteQuery,executeCommandor any method accessing theXQResultSequencereturned byexecuteQuery. If applicable, any openXQResultSequenceandXQResultItemobjects 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:
trueif the expression is in a closed state,falseotherwise
-
close
void close() throws XQExceptionCloses the expression object and release associated resources. Once the expression is closed, all methods on this object other than thecloseorisClosedwill raise exceptions. This also closes any result sequences obtained from this expression. Callingcloseon anXQExpressionobject that is already closed has no effect.- Throws:
XQException- if there are errors when closing the expression
-
executeCommand
void executeCommand(java.lang.String cmd) throws XQExceptionExecutes 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
void executeCommand(java.io.Reader cmd) throws XQExceptionExecutes 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
XQResultSequence executeQuery(java.lang.String query) throws XQException
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
XQResultSequenceobject 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
XQResultSequence executeQuery(java.io.Reader query) throws XQException
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
XQResultSequenceobject 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
XQResultSequence executeQuery(java.io.InputStream query) throws XQException
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
XQResultSequencecontaining 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
XQStaticContext getStaticContext() throws XQException
Gets anXQStaticContextrepresenting the values for all expression properties. Note that these properties cannot be changed; in order to change, a newXQExpressionneeds to be created.- Returns:
- an
XQStaticContextrepresenting the values for all expression properties - Throws:
XQException- if the expression is in a closed state
-
-