Execution Contexts

An execution context is an instance of the sqlj.runtime.ExecutionContext class and provides a context in which SQL operations are executed. An execution context instance is associated either implicitly or explicitly with each SQL operation in your SQLJ application.

The ExecutionContext class contains methods for execution control, execution status, execution cancellation, and update-batching operations which function in the following ways:

• Execution control operations of a given execution context instance modify the semantics of subsequent SQL operations executed using that instance.

• Execution status operations of a given execution context instance describe the results of the most recent SQL operation that completed using that instance.

• Execution cancellation operations of a given execution context instance terminate the SQL operation that is currently executing using that instance.

• Update-batching operations of a given execution context instance include enabling and disabling update batching, setting the batch limit, and getting update counts. (For information about update batching, see "Update Batching".)

  Note: There is only one execution context class, unlike connection context classes where you declare additional classes as desired. Every execution context is an instance of the ExecutionContext class. So while the term connection context refers to a class that you have declared, the term execution context refers to an instance of the ExecutionContext class. This document specifies connection context class, connection context instance, and execution context instance to avoid confusion.

Relation of Execution Contexts to Connection Contexts

Each connection context instance implicitly has its own default execution context instance, which you can retrieve by using the getExecutionContext() method of the connection context instance.

A single execution context instance will be sufficient for a connection context instance except in the following circumstances:

• You are using multiple threads with a single connection context instance.

  When using multithreading, each thread must have its own execution context instance.

• You want to use different SQL execution control operations on different SQLJ statements that employ the same connection context instance.

• You want to retain different sets of SQL status information from multiple SQL operations that employ the same connection context instance.

  As you execute successive SQL operations that employ the same execution context instance, the status information from each operation overwrites the status information from the previous operation.

Although execution context instances might appear to be associated with connection context instances (given that each connection context instance has a default execution context instance, and you can specify a connection context instance and an execution context instance together for a particular SQLJ statement), they actually operate independently. You can employ different execution context instances in statements that employ the same connection context instance, and vice versa.

For example, it is useful to use multiple execution context instances with a single connection context instance if you use multithreading, with a separate execution context instance for each thread. And you can use multiple connection context instances with a single execution context instance if your program is single-threaded and you want the same set of SQL control parameters to apply to all the connection context instances. (See "ExecutionContext Methods" for information about SQL control settings.)

To employ different execution context instances with a single connection context instance, you must create additional instances of the ExecutionContext class and specify them appropriately with your SQLJ statements.

Creating and Specifying Execution Context Instances

To employ an execution context instance other than the default with a given connection context instance, you must construct another execution context instance. There are no input parameters for the ExectionContext constructor:

ExecutionContext myExecCtx = new ExecutionContext();

You can then specify this execution context instance for use with any particular SQLJ statement, much as you would specify a connection context instance. The general syntax is as follows:

#sql [<conn_context><, ><exec_context>] { SQL operation };

For example, if you declare and instantiate a connection context class MyConnCtxClass and create an instance myConnCtx, you can use the following statement:

#sql [myConnCtx, myExecCtx] { DELETE FROM emp WHERE sal > 30000 };

You can subsequently use different execution context instances with myConnCtx or different connection context instances with myExecCtx.

You can optionally specify an execution context instance while using the default connection context instance, as follows:

#sql [myExecCtx] { DELETE FROM emp WHERE sal > 30000 };

Notes: If you specify a connection context instance without an execution context instance, then the default execution context instance of that connection context instance is used. If you specify an execution context instance without a connection context instance, then the execution context instance is used with the default connection context instance of your application. If you specify no connection context instance and no execution context instance, then SQLJ uses your default connection and its default execution context instance.

Execution Context Synchronization

ExecutionContext methods (discussed in "ExecutionContext Methods") are all synchronized methods. Therefore, generally speaking, anytime a statement tries to use an execution context instance (in essence, tries to use a method of an execution context instance) already in use, the second statement will be blocked until the first statement completes.

In a client application, this typically involves multithreading situations. A thread that tries to use an execution context instance currently in use by another thread will be blocked.

To avoid such blockage, you must specify a separate execution context instance for each thread that you use, as discussed in "Multithreading in SQLJ".

The exception to the preceding discussion is for recursion, which is encountered only in the server. Multiple SQLJ statements are allowed to simultaneously use the same execution context instance if this situation results from recursive calls. An example of this is where a SQLJ stored procedure (or function) has a call to another SQLJ stored procedure (or function). If both use the default execution context instance, as is typical, then the SQLJ statements in the second procedure will use this execution context while the SQLJ call statement from the first procedure is also still using it. This is allowed, and is further discussed in "Recursive SQLJ Calls in the Server".

ExecutionContext Methods

This section lists the methods of the ExecutionContext class, categorized as status methods, control methods, cancellation method, and update batching methods.

Status Methods

Use the following methods of an execution context instance to obtain status information about the most recent SQL operation that completed using that instance:

• getWarnings()--Returns a java.sql.SQLWarning object containing the first warning reported by the most recent SQL operation that completed using this execution context instance. Warnings are returned in a chain--use the getWarnings() method of the execution context instance to get the first warning, then use the getNextWarning() method of each SQLWarning object to get the next warning. The chain contains all warnings generated during the execution of the SQL operation.

• getUpdateCount()--Except when update batching is enabled, this returns an int value specifying the number of rows updated by the last SQL operation that completed using this execution context instance. Zero (0) is returned if the last SQL operation was not a DML statement. The constant QUERY_COUNT is returned if the last SQL operation produced an iterator or result set. The constant EXCEPTION_COUNT is returned if the last SQL operation terminated before completing execution, or if no operation has yet been attempted using this execution context instance.

  For batch-enabled applications, the value returned by getUpdateCount() would be one of several batch-related constant values--NEW_BATCH_COUNT, ADD_BATCH_COUNT, or EXEC_BATCH_COUNT. See "Execution Context Update Counts" for more information.

Control Methods

Use the following methods of an execution context instance to control the operation of future SQL operations executed using that instance (operations that have not yet started):

• getMaxFieldSize()--Returns an int value specifying the maximum amount of data (in bytes) that would be returned from a SQL operation subsequently, using this execution context instance. (This can be modified using the setMaxFieldSize() method.) This applies only to columns of type BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, or LONGVARCHAR.

  By default this parameter is set to 0, meaning there is no size limit.

• setMaxFieldSize()--Takes an int value as input to modify the field-size maximum.

• getMaxRows()--Returns an int value specifying the maximum number of rows that can be contained by any SQLJ iterator or JDBC result set created using this execution context instance. (You can modify this using the setMaxRows() method.) If the limit is exceeded, the excess rows are silently dropped without any error report or warning.

  By default, this parameter is set to 0, meaning there is no row limit.

• setMaxRows()--Takes an int value as input to modify the row maximum.

• getQueryTimeout()--Returns an int value specifying the timeout limit, in seconds, for any SQL operation that uses this execution context instance. (You can modify this using the setQueryTimeout() method.) If a SQL operation exceeds this limit, a SQL exception is thrown.

  By default, this parameter is set to 0, meaning there is no query timeout limit.

• setQueryTimeout()--Takes an int value as input to modify the query timeout limit.

• 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().

• setFetchSize()--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. Specifying zero means that an implementation-depenent default value will be used for the fetch size.

• getFetchDirection()--Retrieves the direction for fetching rows from database tables that is the default for scrollable iterator objects that are 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.

• setFetchDirection()--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 that are created using this ExecutionContext object. The default value is:

  sqlj.runtime.ResultSetIterator.FETCH_FORWARD.
  
  

  This method throws a SQLException if the given direction is not one of FETCH_FORWARD, FETCH_REVERSE, or FETCH_UNKNOWN.

Cancellation Method

Use the following method to cancel SQL operations in a multithreading environment or to cancel a pending statement batch if update batching is enabled:

• cancel()--In a multithreading environment, use this method in one thread to cancel a SQL operation currently executing in another thread. It cancels the most recent operation that has started, but not completed, using this execution context instance. This method has no effect if no statement is currently being executed using this execution context instance.

  In a batch-enabled environment, use this to cancel a pending statement batch. The batch is emptied, and none of the statements in the batch are executed. After you cancel a batch, the next batchable statement encountered will be added to a new batch. ( "Canceling a Batch" discusses this.)

Update Batching Methods

Use the following methods to control update batching if you want your application to use that performance enhancement feature (these methods, and update batching in general, are further discussed in "Update Batching"):

• setBatching()--Takes a boolean value to enable update batching. See "Enabling and Disabling Update Batching" for more information.

  Update batching is disabled by default.

• isBatching()--Returns a boolean value indicating whether update batching is enabled (but does not indicate whether there is currently a pending batch).

• getBatchLimit()--Returns an int value indicating the current batch limit. If there is a batch limit, a pending batch is implicitly executed once it contains that number of statements. See "Setting a Batch Limit" for more information.

  By default, the batch limit is set to the ExecutionContext class static constant value UNLIMITED_BATCH, meaning there is no batch limit.

• setBatchLimit()--Takes a positive, non-zero int value as input to set the current batch limit. Two special values you can input are UNLIMITED_BATCH--which means there is no limit--and AUTO_BATCH--which lets the SQLJ runtime dynamically determine a batch limit.

• executeBatch()--Executes the pending statement batch, returning an array of int update counts that have meanings as described in "Execution Context Update Counts". See "Explicit and Implicit Batch Execution" for more information. Regarding error conditions, see "Error Conditions During Batch Execution".

• getBatchUpdateCounts()--Returns an array of int update counts for the last batch executed, with meanings as described in "Execution Context Update Counts". This method is useful in situations where the batch was executed implicitly.

Example: Use of ExecutionContext Methods

The following code demonstrates the use of some ExecutionContext methods:

ExecutionContext execCtx =
   DefaultContext.getDefaultContext().getExecutionContext();

// Wait only 3 seconds for operations to complete
execCtx.setQueryTimeout(3);

// delete using execution context of default connection context
#sql { DELETE FROM emp WHERE sal > 10000 };

System.out.println
     ("removed " + execCtx.getUpdateCount() + " employees");

Relation of Execution Contexts to Multithreading

Do not use multiple threads with a single execution context. If you do, and two SQLJ statements try to use the same execution context simultaneously, then the second statement will be blocked until the first statement completes. Furthermore, status information from the first operation will likely be overwritten before it can be retrieved.

Therefore, if you are using multiple threads with a single connection context instance, you should take the following steps:

1. Instantiate a unique execution context instance for use with each thread.

2. Specify execution contexts with your #sql statements so that each thread uses its own execution context (see "Specifying an Execution Context" above).

If you are using a different connection context instance with each thread, then no instantiation and specification of execution context instances is necessary, because each connection context instance implicitly has its own default execution context instance.

See "Multithreading in SQLJ" for more information about multithreading.

---