sqlj.runtime
Class ExecutionContext

java.lang.Object
  |
  +--sqlj.runtime.ExecutionContext

public class ExecutionContext

extends java.lang.Object

An execution context provides the context in which executable sql operations are preformed. An execution context object contains a number of operations for execution control, execution status, and execution cancellation. Execution control operations modify the semantics of subsequent sql operations executed on this context. Execution status operations describe the results of the last sql operation executed on this context. Execution cancellation methods terminate the currently executing sql operation on this context.

Note that concurrently executing sql operations are expected to use distinct execution contexts. The execution context implementation is not expected to support multiple sql operations executing using the same execution context object. The client is responsible for insuring the proper creation of distinct execution context instance where needed, or synchronizing the execution of operations on a particular execution context. It is also assumed that generated calls to methods on this class appear within a schronized block to avoid concurrent calls. Re-entrant SQL execution calls on the same connection context instance are supported.

See Also:

ConnectionContext.getExecutionContext()

Inner Class Summary

Type	Class
static class	ExecutionContext.OracleContext

Field Summary

Type	Field
static int	ADD_BATCH_COUNT Constant returned by getUpdateCount indicating that a statement was added to the pending statement batch.
static int	AUTO_BATCH Constant passed to setBatchLimit to indicate that implicit batch execution should be performed, and that the actual batch size is at the discretion of the SQLJ runtime implementation.
static int	EXCEPTION_COUNT Constant returned by getUpdateCount indicating that an exeception was thrown before the last execution was successfully completed, or no operation has yet been attempted on this context.
static int	EXEC_BATCH_COUNT constant returned by getUpdateCount indicating that a statement batch has been executed.
static int	LIMITED_BATCH Deprecated.
static int	NEW_BATCH_COUNT Constant returned by getUpdateCount indicating that a new statement batch was created.
static int	QUERY_COUNT Constant returned by getUpdateCount indicating that the last execution produced a result set or iterator.
static int	UNLIMITED_BATCH Constant passed to setBatchLimit to indicate that no implicit batch execution should be performed upon reaching a certain batch size.

Constructor Summary

ExecutionContext()
Creates a new ExecutionContext object with default settings.

ExecutionContext(ConnectionContext ctx)
Creates a new ExecutionContext object that reflects the execution settings of a given ConnectionContext's ExecutionContext.

ExecutionContext(ExecutionContext ec)
Creates a new ExecutionContext object that reflects the execution settings of a given ExecutionContext.

Method Summary

Type	Method
void	cancel() The cancel method can be used by one thread to cancel a sql operation that is currently being executed by another thread using this context.
boolean	execute() Performs a generic execute on the currently registered statement.
int[]	executeBatch() Executes the pending statement batch contained in this execution context and returns the result as an array of update counts.
sqlj.runtime.profile.RTResultSet	executeQuery() Performs an execute query on the currently registered statement.
int	executeUpdate() Performs an execute update on the currently registered statement.
int	getBatchLimit()
int[]	getBatchUpdateCounts() Returns an array of update counts containing one element for each command in the last statement batch to successfully complete execution.
int	getFetchDirection() Retrieves the direction for fetching rows from database tables that is the default for scrollable iterator objects generated from this ExecutionContext object.
int	getFetchSize() Retrieves the number of rows that is the current fetch size for iterator objects generated from this ExecutionContext object.
int	getMaxFieldSize() The max field size limit (in bytes) is the maximum amount of data returned for any column value for sql operations subsequently executed using this context; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns.
int	getMaxRows() The max rows limit is the maximum number of rows that any ResultSetIterator or jdbc ResultSet returned by sql operations subsequently executed using this context can contain.
java.sql.ResultSet	getNextResultSet() Moves to the currently registered statement's next result.
ExecutionContext.OracleContext	getOracleContext()
int	getQueryTimeout() The query timeout limit is the maxiumum number of seconds sql opeations subsequently executed using this context may take to complete.
int	getUpdateCount() Returns the number of rows updated by the last sql operation to complete execution using this context.
java.sql.SQLWarning	getWarnings() Returns the first warning reported by the last sql operation to complete execution using this context.
boolean	isBatching() Returns true if batching is currently enabled for this execution context, false if batching is disabled.
static ExecutionContext.OracleContext	raiseNullExecCtx()
sqlj.runtime.profile.RTStatement	registerStatement(ConnectionContext connCtx, java.lang.Object profileKey, int stmtNdx) Creates, registers and returns a statement.
void	releaseStatement() Releases the currently registered statement, signaling that all execution-related operations have completed.
void	setBatching(boolean isBatching) Enables or disbables batching for statements executed on the execution context.
void	setBatchLimit(int batchLimit) Sets the maximum batch size.
void	setFetchDirection(int direction) Gives the SQLJ runtime a hint as to the direction in which rows of scrollable iterator objects are processed.
void	setFetchSize(int rows) Gives the SQLJ runtime a hint as to the number of rows that should be fetched when more rows are needed.
void	setMaxFieldSize(int max) The max field size limit (in bytes) is the maximum amount of data returned for any column value for sql operations subsequently executed using this context; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns.
void	setMaxRows(int max) The max rows limit is the maximum number of rows that any ResultSetIterator or jdbc ResultSet returned by sql operations subsequently executed using this context can contain.
void	setQueryTimeout(int seconds) The query timeout limit is the maxiumum number of seconds sql opeations subsequently executed using this context may take to complete.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

QUERY_COUNT

public static final int QUERY_COUNT

Constant returned by getUpdateCount indicating that the last execution produced a result set or iterator.

See Also:

getUpdateCount()

EXCEPTION_COUNT

public static final int EXCEPTION_COUNT

Constant returned by getUpdateCount indicating that an exeception was thrown before the last execution was successfully completed, or no operation has yet been attempted on this context.

See Also:

getUpdateCount()

NEW_BATCH_COUNT

public static final int NEW_BATCH_COUNT

Constant returned by getUpdateCount indicating that a new statement batch was created.

See Also:

getUpdateCount()

ADD_BATCH_COUNT

public static final int ADD_BATCH_COUNT

Constant returned by getUpdateCount indicating that a statement was added to the pending statement batch.

See Also:

getUpdateCount()

EXEC_BATCH_COUNT

public static final int EXEC_BATCH_COUNT

constant returned by getUpdateCount indicating that a statement batch has been executed.

UNLIMITED_BATCH

public static final int UNLIMITED_BATCH

Constant passed to setBatchLimit to indicate that no implicit batch execution should be performed upon reaching a certain batch size.

See Also:

setBatchLimit(int), getBatchLimit()

AUTO_BATCH

public static final int AUTO_BATCH

Constant passed to setBatchLimit to indicate that implicit batch execution should be performed, and that the actual batch size is at the discretion of the SQLJ runtime implementation.

See Also:

setBatchLimit(int), getBatchLimit()

LIMITED_BATCH

public static final int LIMITED_BATCH

Deprecated.

Constant passed to setBatchLimit to indicate that implicit batch execution should be performed, and that the actual batch size is at the discretion of the SQLJ runtime implementation.

Note: this constant is deprecated in favor of AUTO_BATCH

See Also:

setBatchLimit(int), getBatchLimit()

Constructor Detail

ExecutionContext

public ExecutionContext()

Creates a new ExecutionContext object with default settings.

ExecutionContext

public ExecutionContext(ExecutionContext ec)

Creates a new ExecutionContext object that reflects the execution settings of a given ExecutionContext.

ExecutionContext

public ExecutionContext(ConnectionContext ctx)

Creates a new ExecutionContext object that reflects the execution settings of a given ConnectionContext's ExecutionContext.

Method Detail

getMaxFieldSize

public int getMaxFieldSize()

The max field size limit (in bytes) is the maximum amount of data returned for any column value for sql operations subsequently executed using this context; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. These columns may be fetched into Java targets of type byte[], String, or stream. The limit effects both out and in-out parameters passed, and the result returned from any executable sql operation. If the limit is exceeded, the excess data is silently discarded.

By default, the max field size limit is zero (unlimited)

Returns:

the current max field size limit; zero means unlimited

setMaxFieldSize

public void setMaxFieldSize(int max)

The max field size limit (in bytes) is the maximum amount of data returned for any column value for sql operations subsequently executed using this context; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. These columns may be fetched into Java targets of type byte[], String, or stream. The limit effects both out and in-out parameters passed, and the result returned from any executable sql operation. If the limit is exceeded, the excess data is silently discarded. For maximum portability use values greater than 256.

By default, the max field size limit is zero (unlimited)

Note: max field size is an optional feature that may not be supported by some implementations. Setting max field size to a non-default value may cause an SQLException to be raised when an SQL operation is executed using this context.

Parameters:

max - the new max field size limit; zero means unlimited

getMaxRows

public int getMaxRows()

The max rows limit is the maximum number of rows that any ResultSetIterator or jdbc ResultSet returned by sql operations subsequently executed using this context can contain. If the limit is exceeded, the excess rows are silently dropped.

By default, the max rows limit is zero (unlimited)

Returns:

the current max rows limit; zero means unlimited

setMaxRows

public void setMaxRows(int max)

The max rows limit is the maximum number of rows that any ResultSetIterator or jdbc ResultSet returned by sql operations subsequently executed using this context can contain. If the limit is exceeded, the excess rows are silently dropped.

By default, the max rows limit is zero (unlimited)

Note: max rows is an optional feature that may not be supported by some implementations. Setting max rows to a non-default value may cause an SQLException to be raised when an SQL operation is executed using this context.

Parameters:

max - the new max rows limit; zero means unlimited

getQueryTimeout

public int getQueryTimeout()

The query timeout limit is the maxiumum number of seconds sql opeations subsequently executed using this context may take to complete. If execution of the sql operation exceeds the limit, a SQLException is thrown.

By default, the query timeout limit is zero (unlimited)

Returns:

the current query timeout limit in seconds; zero means unlimited

setQueryTimeout

public void setQueryTimeout(int seconds)

The query timeout limit is the maxiumum number of seconds sql opeations subsequently executed using this context may take to complete. If execution of the sql operation exceeds the limit, a SQLException is thrown.

By default, the query timeout limit is zero (unlimited)

Note: query timeout is an optional feature that may not be supported by some implementations. Setting query timeout to a non-default value may cause an SQLException to be raised when an SQL operation is executed using this context.

Parameters:

seconds - the new query timeout limit in seconds; zero means unlimited

getWarnings

public java.sql.SQLWarning getWarnings()

Returns the first warning reported by the last sql operation to complete execution using this context. Subsequent warnings resultant from the same operation will be chained to this SQLWarning. The SQLWarning chain returned represents those warnings which occured during the execution of the last sql operation and the subsequent binding of any output host variables.

Note: If you are processing an iterator, then any warnings associated with iterator column reads will be chained on the iterator object.

Returns:

the first SQLWarning or null if no warnings occurred

getUpdateCount

public int getUpdateCount()

Returns the number of rows updated by the last sql operation to complete execution using this context. 0 is returned if the last sql operation was not a DML statement. QUERY_COUNT is returned if the last sql operation produced an iterator or result set. EXCEPTION_COUNT is returned if an exception occurred before the last sql operation completed execution, or no operation has yet been completed.

Returns:

the number of rows updated by the last operation

setBatching

public void setBatching(boolean isBatching)

Enables or disbables batching for statements executed on the execution context.

isBatching

public boolean isBatching()

Returns true if batching is currently enabled for this execution context, false if batching is disabled. Note that the return value reflects only whether it is possible to batch statements, but not whether a pending statement batch exists.

setBatchLimit

public void setBatchLimit(int batchLimit)

Sets the maximum batch size. When batching is enabled and the maximum batch size is exceeded, implicit batch execution is performed. The following remarks assume that batching is enabled.

• When the constant UNLIMITED_BATCH is specified, the maximum batch size is unlimited, and can not be exceeded. New ExecutionContext objects are always created with UNLIMITED_BATCH.
• When a positive, non-zero batchLimit is specified, an implict batch execution will be performed, whenever the number of batched statements reaches batchLimit.
• When the constant AUTO_BATCH is specified, the maximum batch size is finite but unspecified. Whenever a batch-compatible statement is added to a batch, the SQLJ runtime implementation may decide to do one of the following:
  • add the statement to the batch, or
  • execute the current non-empty batch and create a new singleton batch that contains the statement, or
  • add the statement to the current batch and execute the batch. As a special case of this situation, given an empty batch, the implementation may also simply go ahead and execute the statement.

The implementation should reasonably avoid creating out-of-memory conditions due to implicit batching with AUTO_BATCH.

This method only affects statements encountered after it is called. It does not affect statements that have previously been or are currently being executed, nor does it affect the pending statement batch.

Parameters:

batchLimit - UNLIMITED_BATCH if the maximum batch size is unlimited, AUTO_BATCH if the maximum batch size is finite and implementation dependent, or n>0 for a maximum batch size of n.

getBatchLimit

public int getBatchLimit()

getBatchUpdateCounts

public int[] getBatchUpdateCounts()

Returns an array of update counts containing one element for each command in the last statement batch to successfully complete execution. Returns null if no statement batch has completed execution.

Returns:

An array of update counts resulting from the last statement batch executed, or null if no statement batch has completed execution.

getFetchSize

public int getFetchSize()

Retrieves the number of rows that is the current fetch size for iterator objects generated from this ExecutionContext object. If this ExecutionContext object has not set a fetch size by calling setFetchSize, then the value returned is zero. If this ExecutionContext object has set a non negative fetch size by calling the method setFetchSize, then the return value is the fetch size specified on setFetchSize.

Returns:

the default fetch size for iterator objects generated from this ExecutionContext object.

Throws:

java.sql.SQLException - if a database access error occurs.

setFetchSize

public void setFetchSize(int rows)
                  throws java.sql.SQLException

Gives the SQLJ runtime a hint as to the number of rows that should be fetched when more rows are needed. The number of rows specified affects only iterator objects created using this ExecutionContext object.

Parameters:

rows - the default fetch size for iterator objects generated from this Statement object.

Throws:

java.sql.SQLException - if rows < 0 or rows > maxRows

getFetchDirection

public int getFetchDirection()

Retrieves the direction for fetching rows from database tables that is the default for scrollable iterator objects generated from this ExecutionContext object. If this ExecutionContext object has not set a fetch direction by calling the method setFetchDirection, the return value is FETCH_FORWARD

Returns:

the default fetch direction for scrollable iterator objects generated from this ExecutionContext object.

Throws:

java.sql.SQLException - if a database access error occurs

setFetchDirection

public void setFetchDirection(int direction)
                       throws java.sql.SQLException

Gives the SQLJ runtime a hint as to the direction in which rows of scrollable iterator objects are processed. The hint applies only to scrollable iterator objects created using this ExecutionContext object. The default value is sqlj.runtime.ResultSetIterator.FETCH_FORWARD.

Parameters:

direction - the initial fetch direction for scrollable iterator objects generated from this ExecutionContext.

Throws:

java.sql.SQLException - if the given direction is not one of ResultSetIterator.FETCH_FORWARD, ResultSetIterator.FETCH_REVERSE, or ResultSetIterator.FETCH_UNKNOWN.

cancel

public void cancel()
            throws java.sql.SQLException

The cancel method can be used by one thread to cancel a sql operation that is currently being executed by another thread using this context. Note that this method has no effect if there is no statement currently being executed for this execution context.

Throws:

java.sql.SQLException - if unable to cancel

See Also:

executeUpdate(), executeQuery()

registerStatement

public sqlj.runtime.profile.RTStatement registerStatement(ConnectionContext connCtx,
                                                          java.lang.Object profileKey,
                                                          int stmtNdx)
                                                   throws java.sql.SQLException

Creates, registers and returns a statement. This method is called by generated code. Most programmers will not need to call it directly.

The statement is created by accessing the connected profile within connection context "connCtx" that has the key "profileKey". The statement at index "stmtNdx" in the connected profile is created using the getStatement method.

The statement created is registered and becomes the current statement of this execution context.

For each of the max rows, max field size, and query timeout attributes of this execution context, if the attribute has a non-default value, then the corresponding attribute of the registered statement is set to this value. An exception is raised if the statement does not support setting the attribute. The attributes of the execution context contained by the passed connection context are not used by this method. Note that if this method throws an exception, no statement will be registered.

Note: It is assumed that this method is called within a block that is synchronized on this execution context instance. Subsequent calls to execute and release the statement returned should also appear within the same synchronized block. If there is another statement currently registered on this execution context, it is assumed that this method is a recursive callin initiated by the currently registered statement. In such cases, state involving the currently registered statement is saved, and the statement returned by this method becomes the currently registered statement. Once this new statement completes execution and is released, the previous statement is restored as the currently registered statement.

Parameters:

connCtx - the connection context that contains the profile that contains the statement to register.

profileKey - the key of the connected profile within the connection context.

stmtNdx - the 0-based index of the statement within the profile to be registered.

Throws:

java.sql.SQLException - if the max fields size, max rows, or query timeout cannot be set on the registered statement.

See Also:

releaseStatement(), ConnectedProfile.getStatement(int), ConnectionContext.getConnectedProfile(java.lang.Object)

executeUpdate

public int executeUpdate()
                  throws java.sql.SQLException

Performs an execute update on the currently registered statement. When the statement is released, the update count is updated accordingly.

This method is called by generated code. Most programmers will not need to call it directly.

Note: It is assumed that this method is called within a block that is synchronized on this execution context instance. Furthermore, it is also assumed that the previous call to register and the subsequent call to release the current statement also appear within the same synchronized block.

Returns:

the result of calling executeUpdate on the currently registered statement

Throws:

java.sql.SQLException - if an error occurs during the execution of the currently registered statement.

See Also:

RTStatement.executeUpdate(), registerStatement(sqlj.runtime.ConnectionContext, java.lang.Object, int)

executeBatch

public int[] executeBatch()
                   throws java.sql.SQLException

Executes the pending statement batch contained in this execution context and returns the result as an array of update counts. If no pending statement batch exists for this execution context, null is returned.

Upon direct or exceptional return from this method, update count is set to EXEC_BATCH_COUNT. If this method returns successfully, the batch update counts of this execution context are updated to reflect the return result.

Once this method is called, the statement batch is emptied even if the call results in an exception. If a new statement batch is created as a result of executing the current batch, the new batch is implicitly executed. Subsequent calls to this method will return null until another batchable statement is added.

Note that exceptions returned by this method will generally be instances of java.sql.BatchUpdateException.

Returns:

An array of update counts containing one element for each command in the batch, or null if no statement batch exists. The array is ordered according to the order in which commands were inserted into the batch.

Throws:

java.sql.SQLException - if a database access error occurs while executing the statement batch.

executeQuery

public sqlj.runtime.profile.RTResultSet executeQuery()
                                              throws java.sql.SQLException

Performs an execute query on the currently registered statement. When the statement is released, the update count is set to QUERY_COUNT.

This method is called by generated code. Most programmers will not need to call it directly.

Note: It is assumed that this method is called within a block that is synchronized on this execution context instance. Furthermore, it is also assumed that the previous call to register and the subsequent call to release the current statement also appear within the same synchronized block.

Returns:

the result of calling executeRTQuery on the currently registered statement

Throws:

java.sql.SQLException - if an error occurs during the execution of the currently registered statement.

See Also:

RTStatement.executeRTQuery(), registerStatement(sqlj.runtime.ConnectionContext, java.lang.Object, int)

execute

public boolean execute()
                throws java.sql.SQLException

Performs a generic execute on the currently registered statement. Under some situations a single SQL CALL statement may return multiple result sets. The "execute" and "getNextResultSet" methods allow navigation through multiple results.

The "execute" method executes the currently registered statement and returns true if it produced a side-channel result set, false otherwise. The getNextResultSet method is used to obtain the result set. When the statement is released, the update count will be set to QUERY_COUNT.

Notes:

• This method is called by generated code. Most programmers will not need to call it directly. Instead, they will use only "getNextResultSet" to navigate multiple results.
• If the current operation produces multiple results, it is not released until all results have been processed, and getNextResultSet returns null.
• If this operation also produces side-channel update counts, they are silently discarded.
• If an error occurs executing the SQL operation, the current statement is released and an SQLException is raised. Subsequent calls to "getNextResultSet" will return null.
• It is assumed that this method is called within a block that is synchronized on this execution context instance. Furthermore, it is also assumed that the previous call to register and the subsequent call to release the current statement also appear within the same synchronized block.

Returns:

true if the statement produced a side-channel result set, false otherwise.

Throws:

java.sql.SQLException - if an error occurs during the execution of the currently registered statement.

See Also:

RTStatement.execute(), registerStatement(sqlj.runtime.ConnectionContext, java.lang.Object, int), getNextResultSet()

getNextResultSet

public java.sql.ResultSet getNextResultSet()
                                    throws java.sql.SQLException

Moves to the currently registered statement's next result. The first time this method is called after a SQL operation is executed, the first side-channel result set is returned (if any). Further calls to getNextResultSet will move to any subsequent results. getNextResultSet implicitly closes any open result set previously obtained with getNextResultSet.

getNextResultSet returns null when there are no further results. null is also returned if the last SQL operation executed did not produce side-channel results, or an SQL operation has not yet been executed on this execution context.

Notes:

• If the last SQL operation executed on this execution context produced multiple results, its resources are not released until all results have been processed, and getNextResultSet returns null. If this execution context is used to execute a SQL operation while results are still pending from the previous operation, or a statement execution completes while results from a recursive callin are still pending, the results are silently closed and discarded, and resources are released.
• If this operation also produces side-channel update counts, they are silently discarded.
• If an error occurs during a call to getNextResultSet, the current statement is released and an SQLException is raised. Subsequent calls to getNextResultSet will return null.

Returns:

the next side-channel result set, or null if there are no further results.

Throws:

java.sql.SQLException - if an error occurs obtaining the next result set.

See Also:

RTStatement.getResultSet(), RTStatement.getMoreResults(), execute(), registerStatement(sqlj.runtime.ConnectionContext, java.lang.Object, int)

releaseStatement

public void releaseStatement()
                      throws java.sql.SQLException

Releases the currently registered statement, signaling that all execution-related operations have completed. After this method has been returned from, it is safe to call registerStatement again. The SQL warnings and updated count are updated as reflected by the registered statement and the execution results.

This method calls the executeComplete method of the registered statement.

If the execution of the currently registered statement produced multiple results and not all results have been processed, then this operation is a no-op. In such cases, this method will be automatically called to release the statement once all results have been processed and getNextResultSet returns null.

This method is called by generated code. Most programmers will not need to call it directly.

Note: It is assumed that this method is called within a block that is synchronized on this execution context instance. Furthermore, it is also assumed that the previous calls to register and execute the current statement also appeared within the same synchronized block.

Throws:

java.sql.SQLException - if an error occurs retrieving the warnings

See Also:

registerStatement(sqlj.runtime.ConnectionContext, java.lang.Object, int), RTStatement.executeComplete()

getOracleContext

public ExecutionContext.OracleContext getOracleContext()

raiseNullExecCtx

public static ExecutionContext.OracleContext raiseNullExecCtx()
                                                       throws java.sql.SQLException