com.ddtek.xquery3
Interface XQExpression

All Superinterfaces:

XQDynamicContext

public interface XQExpression

extends XQDynamicContext

This interface describes the execute immediate functionality for expressions. This object can be created from the 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. Only the external variables bound in the prolog of the expression to be executed are used during the evaluation of that expression.

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

void	cancel() Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an XQExpression.
void	clearWarnings() Clears the list of warnings associated with this expression
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.
XQResultSequence	executeQuery(InputStream xquery) Executes a query expression.
XQResultSequence	executeQuery(Reader query) Executes a query expression.
XQResultSequence	executeQuery(String query) Executes a query expression.
XQStaticContext	getStaticContext() Gets an XQStaticContext representing the values for all expression properties.
XQWarning	getWarnings() Gets the first warning in a chained list of warnings associated with this expression.
boolean	isClosed() Checks if the expression is in a closed state.

Methods inherited from interface com.ddtek.xquery3.XQDynamicContext

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

Method Detail

cancel

public void cancel()
            throws XQException

Attempts to cancel the execution if both the XQuery engine and XQJ driver support aborting the execution of an XQExpression. This method can be used by one thread to cancel an XQExpression, 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.

Throws:

XQException - if the expression is in a closed state

clearWarnings

public void clearWarnings()
                   throws XQException

Clears the list of warnings associated with this expression

Throws:

XQException - if the expression is in a closed state

isClosed

public boolean isClosed()

Checks if the expression is in a closed state.

Returns:

true if the expression is in a closed state, false otherwise

close

public void close()
           throws XQException

Closes the expression object and release associated resources. Once the expression is closed, all methods on this object other than the close or isClosed will raise exceptions. This also closes any result sequences obtained from this expression. Calling close on an XQExpression object that is already closed has no effect.

Throws:

XQException - if there are errors when closing the expression

executeCommand

public void executeCommand(String cmd)
                    throws XQException

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

public void executeCommand(Reader cmd)
                    throws XQException

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

public XQResultSequence executeQuery(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

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, or (3) the execution is cancelled

executeQuery

public XQResultSequence executeQuery(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

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, or (3) the execution is cancelled

executeQuery

public XQResultSequence executeQuery(InputStream xquery)
                              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:

xquery - the input query expression as a input stream object

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, or (3) the execution is cancelled

getWarnings

public XQWarning getWarnings()
                      throws XQException

Gets the first warning in a chained list of warnings associated with this expression.

Returns:

warnings associated with this expression

Throws:

XQException - if the expression is in a closed state

getStaticContext

public XQStaticContext getStaticContext()
                                 throws XQException

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

Returns:

an XQStaticContext representing the values for all expression properties.

Throws:

XQException - if the connection is in a closed state.