All Packages This Package Previous Next
Class sqlj.runtime.ExecutionContext
java.lang.Object
|
+----sqlj.runtime.ExecutionContext
- public class ExecutionContext
- extends 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:
- getExecutionContext
-
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.
-
QUERY_COUNT
- Constant returned by getUpdateCount indicating that the last execution
produced a result set or iterator.
-
ExecutionContext()
-
-
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.
-
execute()
- Performs a generic execute on the currently registered
statement.
-
executeQuery()
-
Performs an execute query on the currently registered statement.
-
executeUpdate()
-
Performs an execute update on the currently registered statement.
-
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.
-
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.
-
getNextResultSet()
-
Moves to the currently registered statement's next result.
-
getQueryTimeout()
- The query timeout limit is the maxiumum number of seconds sql opeations
subsequently executed using this context may take to complete.
-
getUpdateCount()
- Returns the number of rows updated by the last sql operation to
complete execution using this context.
-
getWarnings()
-
Returns the first warning reported by the last sql operation to
complete execution using this context.
-
registerStatement(ConnectionContext, Object, int)
-
Creates, registers and returns a statement.
-
releaseStatement()
- Releases the currently registered statement, signaling that all
execution-related operations have completed.
-
setMaxFieldSize(int)
- 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.
-
setMaxRows(int)
- 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.
-
setQueryTimeout(int)
-
The query timeout limit is the maxiumum number of seconds sql opeations
subsequently executed using this context may take to complete.
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
ExecutionContext
public ExecutionContext()
getMaxFieldSize
public synchronized 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 synchronized 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 synchronized 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 synchronized 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 synchronized 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 synchronized 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 synchronized 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 synchronized 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
cancel
public void cancel() throws 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: SQLException
- if unable to cancel
- See Also:
- executeUpdate, executeQuery
registerStatement
public RTStatement registerStatement(ConnectionContext connCtx,
Object profileKey,
int stmtNdx) throws 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: SQLException
- if the max fields size, max rows, or query timeout cannot be set on
the registered statement.
- See Also:
- releaseStatement, getStatement, getConnectedProfile
executeUpdate
public int executeUpdate() throws 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: SQLException
- if an error occurs during the execution of the
currently registered statement.
- See Also:
- executeUpdate, registerStatement
executeQuery
public RTResultSet executeQuery() throws 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: SQLException
- if an error occurs during the execution of the
currently registered statement.
- See Also:
- executeRTQuery, registerStatement
execute
public boolean execute() throws 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: SQLException
- if an error occurs during the execution of the currently registered
statement.
- See Also:
- execute, registerStatement, getNextResultSet
getNextResultSet
public synchronized ResultSet getNextResultSet() throws 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: SQLException
- if an error occurs obtaining the next result set.
- See Also:
- getResultSet, getMoreResults, execute, registerStatement
releaseStatement
public void releaseStatement() throws 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: SQLException
- if an error occurs retrieving the warnings
- See Also:
- registerStatement, executeComplete
All Packages This Package Previous Next