Oracle8i SQLJ Developer's Guide and Reference Release 3 (8.1.7) Part Number A83723-01 |
Library | Service | Contents | Index

## 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.

| Copyright © 1996-2000, Oracle Corporation. All Rights Reserved. |
Library | Service | Contents | Index