com.bluestream.xdb
Interface XStatement

All Superinterfaces:

Statement

public interface XStatement

extends Statement

XStatement represents a statement being executed. An XStatement may be either in START, EXECUTING or CANCELLING state. When in EXECUTING state the XStatement will wait until the result set is returned. Only one XResultSet object per XStatement object can be open at any point in time. Therefore, if the reading of one XResultSet object is interleaved with the reading of another, each must have been generated by different XStatement objects. All XStatement execute methods implicitly close an XStatment's current XResultSet object if an open one exists. Note: Flags below are additive.

Field Summary

static String	OPT_QUERYTYPE This option is set by the server when it receives and prepares the query string.
static String	OPT_STMT_MAXVALUE Sets the maximum number of results to be cached in a single call to getResults.
static String	OPT_STMT_TIMEOUT Used to set a statement timeout (in seconds).
static String	OPTVAL_QT_READONLY ReadOnly type means there are NO "root update" expressions such as: INSERT DOCUMENT..., REPLACE DOCUMENT....
static String	OPTVAL_QT_UPDATE Update type means there are one or more "root update" expressions such as: INSERT DOCUMENT..., REPLACE DOCUMENT....
static short	SF_DEFAULT
static short	SF_FOR_UPDATE SF_FOR_UPDATE: causes all read requests to be locked for update.
static short	SF_IGNORE_VERSION SF_IGNORE_VERSION: when executing either a REPLACE DOCUMENT or a DELETE DOCUMENT statement, this flag will cause the document version check to be ignored, allowing the operation to succeed even if the version numbers differ.
static short	SF_SUPPRESS_TRIGGERS SF_TRAVERSE_ALL: causes all the results to be traversed automatically and thus there is no ResultSet returned.
static short	SF_TRAVERSE_ALL SF_TRAVERSE_ALL: causes all the results to be traversed automatically and thus there is no ResultSet returned.

Method Summary

XResultSet

execute(String stmtStr, short flags) Execute the given statement.

Methods inherited from interface com.bluestream.xdb.Statement

cancel, close, getWarnings, setStatementOption

Field Detail

SF_IGNORE_VERSION

public static final short SF_IGNORE_VERSION

SF_IGNORE_VERSION: when executing either a REPLACE DOCUMENT or a DELETE DOCUMENT statement, this flag will cause the document version check to be ignored, allowing the operation to succeed even if the version numbers differ.

See Also:

Constant Field Values

SF_FOR_UPDATE

public static final short SF_FOR_UPDATE

SF_FOR_UPDATE: causes all read requests to be locked for update. This is handy to avoid deadlocks since UPDATE locks are incompatible, causing the second reader to wait until the first reader releases.

See Also:

Constant Field Values

SF_TRAVERSE_ALL

public static final short SF_TRAVERSE_ALL

SF_TRAVERSE_ALL: causes all the results to be traversed automatically and thus there is no ResultSet returned. This is useful for DML statements.

See Also:

Constant Field Values

SF_SUPPRESS_TRIGGERS

public static final short SF_SUPPRESS_TRIGGERS

SF_TRAVERSE_ALL: causes all the results to be traversed automatically and thus there is no ResultSet returned. This is useful for DML statements.

See Also:

Constant Field Values

SF_DEFAULT

public static final short SF_DEFAULT

See Also:

Constant Field Values

OPT_STMT_TIMEOUT

public static final String OPT_STMT_TIMEOUT

Used to set a statement timeout (in seconds). If retrieving results takes longer than this, statement is cancelled with an exception thrown.

See Also:

setStatementOption(...), Constant Field Values

OPT_STMT_MAXVALUE

public static final String OPT_STMT_MAXVALUE

Sets the maximum number of results to be cached in a single call to getResults. Allows a client app to limit the results cached to match a client defined cursor size. (# of rows displayed on a page for example)

See Also:

setStatementOption(...), Constant Field Values

OPT_QUERYTYPE

public static final String OPT_QUERYTYPE

This option is set by the server when it receives and prepares the query string. The query type is either re

See Also:

Constant Field Values

OPTVAL_QT_READONLY

public static final String OPTVAL_QT_READONLY

ReadOnly type means there are NO "root update" expressions such as: INSERT DOCUMENT..., REPLACE DOCUMENT.... or DELETE DOCUMENT.

See Also:

Constant Field Values

OPTVAL_QT_UPDATE

public static final String OPTVAL_QT_UPDATE

Update type means there are one or more "root update" expressions such as: INSERT DOCUMENT..., REPLACE DOCUMENT.... or DELETE DOCUMENT.

See Also:

Constant Field Values

Method Detail

execute

public XResultSet execute(String stmtStr,
                          short flags)
                   throws XDBException

Execute the given statement. This can be either an XQuery, DML or DDL statement. If a result set is already outstanding then a close() will occur automatically on that result set, since there can only be one result set outstanding for any given statement.

Parameters:

stmtStr - A valid XQuery statement.

flags -

• SF_TRAVERSE_ALL: causes all the results to be traversed automatically and thus there is no ResultSet returned. This is useful for DML statements where you are not interested in the results. SF_TRAVERSE_ALL is equivalent to executing and then performing a fsbGetAll on the returned XResultSet, except TRAVERSE_ALL is faster since it is entirely server side.
• SF_FOR_UPDATE: causes all reads in the query to have a READ_FOR_UPDATE instead of just a READ lock. This is useful to avoid deadlocks.
• SF_IGNORE_VERSION: when executing either a REPLACE DOCUMENT or a DELETE DOCUMENT statement, this flag will cause the document version check to be ignored, allowing the operation to succeed even if the version numbers differ.

Returns:

XResultSet. This is the resulting ResultSet for a query, and null for DDL statements or if SF_TRAVERSE_ALL is set. Important note for DML statements: Since DML statements are embedded in XQuery syntax, an XResultSet is returned when a DML statement is executed. Due to this fact, it is necessary to call fsbGetAll on the result set to cause the executions to occur.

Throws:

XDBException - - EC_Compile: There was a compile error. Rollback will occur automatically. - EC_DeadLockRollBack: A deadlock occurred and this thread, as the victim, was rolled back to break deadlock. Transaction will be rolled back. - EC_DuplicateKeyFound: An attempt to insert a duplicate key into an index was detected. The transaction will be rolled back to recover from this. - EC_SchemaValidation: A schema validation failed. The transaction will be rolled back to recover from this. - EC_AccessedDenied: Access to perform this operation has been denied, the transaction will be rolled back automatically. - EC_Deleted: A request was made to delete a document that is already deleted. Transaction will be rolled back automatically. - EC_VersionMismatch: An attempt to either REPLACE or DELETE a document where the document has been updated by another party since it was originally retrieved.