com.marklogic.xdbc
Interface XDBCStatement

public interface XDBCStatement

The XDBCStatement encapsulates a single XQuery query, This includes statically declared namespaces as well as inline function definitions.

The result of executing an XQuery statement is a sequence of XQuery values drawn from the database. Elements that are XML nodes may be processed by a standard SAX or DOM implementation.

Method Summary

void	cancel() Cancel the execution of this XQuery statement.
void	clearVariables() Clears the value of all external variables for this statement.
void	clearWarnings() Clear all the warnings reported on this XQuery statement.
void	close() Release this XQuery statement's database and XDBC resources immediately instead of waiting for this to be done by the Java runtime.
XDBCResultSequence	executeQuery(String xquery) Evaluate an XQuery query and return a sequence of results.
int	getBufferSize() Returns the current buffer size, which is the number of bytes that that should be fetched from the database in a single read of results.
XDBCConnection	getConnection() Retrieves the connection object that generated this statement.
int	getQueryTimeout() Retrieve the number of seconds the driver will wait for an XQuery statement object to execute.
int	getResultSequenceConcurrency() Gets the concurrency setting for the XDBCResultSequence objects generated by evaluating this statement.
XDBCWarning	getWarnings() Retrieves the warnings reported by calls on this XQuery statement.
XDBCResultSequence	invoke(String module, String database, XDBCXName[] argNames) Invokes an XQuery module and return a sequence of results.
boolean	isClosed() Tests if this XDBCStatement is closed.
void	setAnyURI(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setBase64Binary(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setBoolean(XDBCXName name, boolean value) Binds the variable's value to the argument value.
void	setBufferSize(int size) Gives the XDBC driver a hint about the number of bytes that should be fetched from the database in a single read of results.
void	setDate(XDBCXName name, Date value) Binds the variable's value to the argument value.
void	setDate(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setDateTime(XDBCXName name, Date value) Binds the variable's value to the argument value.
void	setDateTime(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setDayTimeDuration(XDBCXName name, XDBCDuration value) Binds the variable's value to the argument value.
void	setDecimal(XDBCXName name, BigDecimal value) Binds the variable's value to the argument value.
void	setDecimal(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setDouble(XDBCXName name, double value) Binds the variable's value to the argument value.
void	setDuration(XDBCXName name, XDBCDuration value) Binds the variable's value to the argument value.
void	setFloat(XDBCXName name, float value) Binds the variable's value to the argument value.
void	setGDay(XDBCXName name, GregorianCalendar value) Binds the variable's value to the argument value.
void	setGMonth(XDBCXName name, GregorianCalendar value) Binds the variable's value to the argument value.
void	setGMonthDay(XDBCXName name, GregorianCalendar value) Binds the variable's value to the argument value.
void	setGYear(XDBCXName name, GregorianCalendar value) Binds the variable's value to the argument value.
void	setGYearMonth(XDBCXName name, GregorianCalendar value) Binds the variable's value to the argument value.
void	setHexBinary(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setInteger(XDBCXName name, BigInteger value) Binds the variable's value to the argument value.
void	setInteger(XDBCXName name, int value) Binds the variable's value to the argument value.
void	setInteger(XDBCXName name, long value) Binds the variable's value to the argument value.
void	setNull(XDBCXName name) Removes any value from the variable, effectively clearing the value of the variable.
void	setQName(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setQName(XDBCXName name, XDBCXName value) Binds the variable's value to the argument value.
void	setQueryTimeout(int seconds) Sets the maximum number of seconds the driver will wait for an XDBCStatement to execute.
void	setString(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setTime(XDBCXName name, Date value) Binds the variable's value to the argument value.
void	setTime(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setUntypedAtomic(XDBCXName name, String value) Binds the variable's value to the argument value.
void	setYearMonthDuration(XDBCXName name, XDBCDuration value) Binds the variable's value to the argument value.

Method Detail

executeQuery

public XDBCResultSequence executeQuery(String xquery)
                                throws XDBCException

Evaluate an XQuery query and return a sequence of results.

Parameters:

xquery - a String XQuery expression to be evaluated.

Returns:

an XDBCResultSequence of XML nodes returned from the database.

Throws:

XDBCException - if a database access error occurs.

invoke

public XDBCResultSequence invoke(String module,
                                 String database,
                                 XDBCXName[] argNames)
                          throws XDBCException

Invokes an XQuery module and return a sequence of results.

Parameters:

module - the path to the module to be evaluated. This is resolved against the root of the XDBC server.

database - the name or id of a database to use as the context for executing the module. Default is null, which means use the XDBC server's default database.

argNames - an ordered array of XDBCXName objects representing the names of arguments to the module. Null means no arguments.

Returns:

an XDBCResultSequence of values returned from executing the module.

Throws:

XDBCException - if a database access error occurs.

cancel

public void cancel()
            throws XDBCException

Cancel the execution of this XQuery statement. This method may not be supported by the XDBC driver or the XML database.

Throws:

XDBCException - if a database access error occurs.

close

public void close()
           throws XDBCException

Release this XQuery statement's database and XDBC resources immediately instead of waiting for this to be done by the Java runtime.

Calling this method frees up resources immediately and its use is strongly encouraged.

Throws:

XDBCException - if a database access error occurs.

getConnection

public XDBCConnection getConnection()
                             throws XDBCException

Retrieves the connection object that generated this statement.

Returns:

the XDBCConnection object.

Throws:

XDBCException - if a database access error occurs.

getResultSequenceConcurrency

public int getResultSequenceConcurrency()
                                 throws XDBCException

Gets the concurrency setting for the XDBCResultSequence objects generated by evaluating this statement.

Returns:

the concurrency level for the XDBCResultSequence objects.

Throws:

XDBCException - if a database access error occurs.

See Also:

XDBC_CONCUR_READ_ONLY, XDBC_CONCUR_UPDATABLE

getWarnings

public XDBCWarning getWarnings()
                        throws XDBCException

Retrieves the warnings reported by calls on this XQuery statement. The warnings form a linked list, and this method returns the first warning in the list. New warnings will be appended to the end of the list.

Returns:

the first XDBCWarning in the linked list of warnings for this statement, or null if no warnings have occurred.

Throws:

XDBCException - if a database access error occurs.

clearWarnings

public void clearWarnings()
                   throws XDBCException

Clear all the warnings reported on this XQuery statement. After this method is called, getWarnings() will return null until another warning occurs.

Throws:

XDBCException - if a database access error occurs.

isClosed

public boolean isClosed()
                 throws XDBCException

Tests if this XDBCStatement is closed.

Returns:

true if this XDBCStatement is closed, false if it is still open.

Throws:

XDBCException - if a database access error occurs

setBufferSize

public void setBufferSize(int size)

Gives the XDBC driver a hint about the number of bytes that should be fetched from the database in a single read of results. Normally this value does not need to be changed. A suitable default is used.

This setting applies to all subsequence XDBCResultSequences created from this statement. However, unlike similar methods on the XDBCResultSequence object, these must be set before the statement is executed to have any effect.

Since this is a hint only, the XDBC driver may choose to ignore this value.

Parameters:

size - the integer number of bytes to fetch at one time; must be greater than 0.

See Also:

getBufferSize()

getBufferSize

public int getBufferSize()

Returns the current buffer size, which is the number of bytes that that should be fetched from the database in a single read of results.

Returns:

the integer number of bytes.

See Also:

setBufferSize(int)

setQueryTimeout

public void setQueryTimeout(int seconds)
                     throws XDBCException

Sets the maximum number of seconds the driver will wait for an XDBCStatement to execute.

After this number of seconds, an XDBCException is thrown.

Parameters:

seconds - integer number of seconds to wait; a value of zero means unlimited; must be zero or positive.

Throws:

XDBCException - if a database access error occurs

getQueryTimeout

public int getQueryTimeout()
                    throws XDBCException

Retrieve the number of seconds the driver will wait for an XQuery statement object to execute.

Returns:

the number of seconds before query execution times out; a value of zero means unlimited.

Throws:

XDBCException - if a database access error occurs.

clearVariables

public void clearVariables()
                    throws XDBCException

Clears the value of all external variables for this statement.

Throws:

XDBCException

setNull

public void setNull(XDBCXName name)
             throws XDBCException

Removes any value from the variable, effectively clearing the value of the variable.

Parameters:

name - the XDBCXName of the variable to set.

Throws:

XDBCException

setAnyURI

public void setAnyURI(XDBCXName name,
                      String value)
               throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:AnyURI.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException

setBase64Binary

public void setBase64Binary(XDBCXName name,
                            String value)
                     throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:base64Binary.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException

setBoolean

public void setBoolean(XDBCXName name,
                       boolean value)
                throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:Boolean.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java boolean value to set.

Throws:

XDBCException

setDateTime

public void setDateTime(XDBCXName name,
                        Date value)
                 throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:dateTime.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java Date value to set.

Throws:

XDBCException

setDateTime

public void setDateTime(XDBCXName name,
                        String value)
                 throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:dateTime.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException

setDecimal

public void setDecimal(XDBCXName name,
                       BigDecimal value)
                throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:decimal.

Note that this conversion may involve some loss of precision due to differences in Java and XQuery types.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java BigDecimal value to set.

Throws:

XDBCException

setDecimal

public void setDecimal(XDBCXName name,
                       String value)
                throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:decimal.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException

setInteger

public void setInteger(XDBCXName name,
                       BigInteger value)
                throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:integer.

Note that this conversion may involve some loss of precision due to differences in Java and XQuery types.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java BigInteger value to set.

Throws:

XDBCException

setInteger

public void setInteger(XDBCXName name,
                       int value)
                throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:integer.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java int value to set.

Throws:

XDBCException

setInteger

public void setInteger(XDBCXName name,
                       long value)
                throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:integer.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java long value to set.

Throws:

XDBCException

setDouble

public void setDouble(XDBCXName name,
                      double value)
               throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:double.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java double value to set.

Throws:

XDBCException

setDuration

public void setDuration(XDBCXName name,
                        XDBCDuration value)
                 throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:duration.

Parameters:

name - the XDBCXName of the variable to set.

value - the XDBCDuration value to set.

Throws:

XDBCException

setDayTimeDuration

public void setDayTimeDuration(XDBCXName name,
                               XDBCDuration value)
                        throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:dayTimeDuration.

Parameters:

name - the XDBCXName of the variable to set.

value - the XDBCDuration value to set.

Throws:

XDBCException

setYearMonthDuration

public void setYearMonthDuration(XDBCXName name,
                                 XDBCDuration value)
                          throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:yearMonthDuration.

Parameters:

name - the XDBCXName of the variable to set.

value - the XDBCDuration value to set.

Throws:

XDBCException

setFloat

public void setFloat(XDBCXName name,
                     float value)
              throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:float.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java float value to set.

Throws:

XDBCException

setGDay

public void setGDay(XDBCXName name,
                    GregorianCalendar value)
             throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:gDay.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java GregorianCalendar value to set.

Throws:

XDBCException

setGMonth

public void setGMonth(XDBCXName name,
                      GregorianCalendar value)
               throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:gMonth.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java GregorianCalendar value to set.

Throws:

XDBCException

setGMonthDay

public void setGMonthDay(XDBCXName name,
                         GregorianCalendar value)
                  throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:gMonthDay.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java GregorianCalendar value to set.

Throws:

XDBCException

setGYear

public void setGYear(XDBCXName name,
                     GregorianCalendar value)
              throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:gYear.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java GregorianCalendar value to set.

Throws:

XDBCException

setGYearMonth

public void setGYearMonth(XDBCXName name,
                          GregorianCalendar value)
                   throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:gYearMonth.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java GregorianCalendar value to set.

Throws:

XDBCException

setHexBinary

public void setHexBinary(XDBCXName name,
                         String value)
                  throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:hexBinary.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException

setQName

public void setQName(XDBCXName name,
                     String value)
              throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:QName.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException

setQName

public void setQName(XDBCXName name,
                     XDBCXName value)
              throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:QName.

Parameters:

name - the XDBCXName of the variable to set.

value - the XDBCXName value to set.

Throws:

XDBCException

setString

public void setString(XDBCXName name,
                      String value)
               throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:string.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException

setDate

public void setDate(XDBCXName name,
                    Date value)
             throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:date.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java Date value to set.

Throws:

XDBCException

setDate

public void setDate(XDBCXName name,
                    String value)
             throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:date.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException

setTime

public void setTime(XDBCXName name,
                    Date value)
             throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:time.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java Date value to set.

Throws:

XDBCException

setTime

public void setTime(XDBCXName name,
                    String value)
             throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xs:time.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException

setUntypedAtomic

public void setUntypedAtomic(XDBCXName name,
                             String value)
                      throws XDBCException

Binds the variable's value to the argument value. The variable should be of type xdt:untypedAtomic.

Parameters:

name - the XDBCXName of the variable to set.

value - the Java String value to set.

Throws:

XDBCException