|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface XQPreparedExpression
This interface describes an expression that can be prepared for multiple subsequent executions. A prepared expression can be created from the connection.
The preparation of the expression does the static analysis of the expression using the static context information.
The dynamic context information, such as values for bind variables, can then be set using the setter methods. When setting values for bind variables, these variables should be present as external variables in the prolog of the prepared expression.
The static type information of the query can also be retrieved if the XQuery
implementation provides it using the getStaticResultType
method.
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 XQPreparedExpression
from which it was prepared and is
closed implicitly if that expression is either closed or if re-executed.
The XQPreparedExpression
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 XQPreparedExpression
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 XQPreparedExpression
is closed any
XQResultSequence
object obtained from it
is also implicitly closed.
Example -
XQConnection conn = XQDataSource.getconnection(); XQPreparedExpression expr = conn.prepareExpression ("for $i in (1) return 'abc' "); // get the sequence type out.. This would be something like xs:string * XQSequenceType type = expr.getStaticResultType(); XQSequence result1 = expr.executeQuery(); // process the result.. result1.next(); System.out.println(" First result1 "+ result1.getAtomicValue()); XQResultSequence result2 = expr.executeQuery(); // result1 is implicitly closed // recommended to close the result sequences explicitly. // process the result.. while (result2.next()) System.out.println(" result is "+ result2.getAtomicValue()); result2.close(); expr.close(); // closing expression implicitly closes all result sequence or // items obtained from this expression. conn.close(); // closing connections will close expressions and results.
Method Summary | |
---|---|
void |
cancel()
Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an XQPreparedExpression . |
void |
close()
Closes the expression object and release all resources associated with this prepared expression. |
XQResultSequence |
executeQuery()
Executes the prepared query expression. |
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. |
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. |
boolean |
isClosed()
Checks if the prepared expression 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 |
---|
void cancel() throws XQException
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.
XQException
- if the prepared expression is in a closed stateboolean isClosed()
true
if the prepared expression is in
a closed state, false
otherwise.void close() throws XQException
close
or isClosed
will raise exceptions.
Calling close on an XQExpression
object that is already closed has no
effect.
XQException
- if there are errors when closing the expressionXQResultSequence executeQuery() throws XQException
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 cancelledQName[] getAllExternalVariables() throws XQException
QName
objects for all the external
variables defined in the prolog of a prepared expression.
Empty array if there are no external variables present.
XQException
- if the prepared expression is in a closed stateQName[] getAllUnboundExternalVariables() throws XQException
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
XQException
- if the prepared expression is in a closed stateXQSequenceType getStaticResultType() throws XQException
XQSequenceType
object
corresponding to the XQuery sequence type item()*
.
XQSequenceType
containing the static
result information.
XQException
- if the prepared expression is in a closed stateXQSequenceType getStaticVariableType(QName name) throws XQException
name
- the name of the external variable
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
XQStaticContext getStaticContext() throws XQException
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.
XQStaticContext
representing
the values for all expression properties
XQException
- if the expression is in a closed state
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |