oracle.ifs.share.sql

Class StatementWrapper

java.lang.Object

oracle.ifs.share.sql.StatementWrapper

Direct Known Subclasses:

IfsStatement, PreparedStatementWrapper

public class StatementWrapper
extends Object

A StatementWrapper object wraps a Statement instance, and delegates to a ConnectionWrapper for execution.

Author:

Dave Long

(Published)

Constructor Summary

Constructors

Constructor and Description
StatementWrapper(Statement stmt, ConnectionWrapper cw) Constructs a StatementWrapper.

Method Summary

Modifier and Type	Method and Description
void	addBatch(String sql) Adds the given SQL command to the current list of commmands for this Statement object.
void	cancel() Cancel can be used by one thread to cancel an Ifstatement that is being executed by another thread.
void	clearBatch() Empties this Statement object's current list of SQL commands.
void	clearWarnings() After this call, getWarnings returns null until a new warning is reported for this StatementWrapper.
void	close() In many cases, it is desirable to immediately release a Statements's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.
static void	closeResultSet(ResultSet rset) Close the specified ResultSet as a best effort; no exceptions thrown.
static void	closeStatement(Statement stmt) Close the specified Statement as a best effort; no exceptions thrown.
static void	closeStatement(StatementWrapper stmt) Close the specified wrapped Statement as a best effort; no exceptions thrown.
void	dispose() Dispose and close the StatementWrapper.
boolean	execute(String sql) Execute a SQL statement that may return multiple results.
int[]	executeBatch() Submits a batch of commands to the database for execution and if all commands execute successfully, returns an array of update counts.
ResultSet	executeQuery(String sql) Execute a SQL statement that returns a single ResultSet.
int	executeUpdate(String sql) Execute a SQL INSERT, UPDATE or DELETE statement.
protected ConnectionWrapper	getConnectionWrapper() Gets the ConnectionWrapper used to construct this instance.
int	getMaxFieldSize() The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns.
int	getMaxRows() The maxRows limit is the maximum number of rows that a ResultSet can contain.
boolean	getMoreResults() Moves to an StatementWrapper's next result.
int	getQueryTimeout() The queryTimeout limit is the number of seconds the driver will wait for an StatementWrapper to execute.
ResultSet	getResultSet() Returns the current result as a ResultSet.
int	getUpdateCount() Returns the current result as an update count; if the result is a ResultSet or there are no more results, -1 is returned.
SQLWarning	getWarnings() The first warning reported by calls on this StatementWrapper is returned.
void	setCursorName(String name) Defines the SQL cursor name that will be used by subsequent Statement execute methods.
void	setEscapeProcessing(boolean enable) If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database.
void	setMaxFieldSize(int max) The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields.
void	setMaxRows(int max) The maxRows limit is set to limit the number of rows that any ResultSet can contain.
void	setQueryTimeout(int seconds) The queryTimeout limit is the number of seconds the driver will wait for an StatementWrapper to execute.

Methods inherited from class java.lang.Object

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

Constructor Detail

StatementWrapper

public StatementWrapper(Statement stmt,
                        ConnectionWrapper cw)

Constructs a StatementWrapper.

Parameters:

stmt - Statement instance to wrap

cw - the ConnectionWrapper context

(Published)

Method Detail

getConnectionWrapper

protected ConnectionWrapper getConnectionWrapper()

Gets the ConnectionWrapper used to construct this instance.

Returns:

the ConnectionWrapper

(Unpublished)

executeQuery

public ResultSet executeQuery(String sql)
                       throws SQLException

Execute a SQL statement that returns a single ResultSet.

Parameters:

sql - typically this is a static SQL SELECT statement

Returns:

a ResultSet that contains the data produced by the query; never null

Throws:

SQLException - if a database-access error occurs.

(Published)

executeUpdate

public int executeUpdate(String sql)
                  throws SQLException

Execute a SQL INSERT, UPDATE or DELETE statement. Although SQL DDL statements can be executed, it is not advised since doing so can cause the iFS repository to be non-functional or irreparable.

Parameters:

sql - a SQL INSERT, UPDATE or DELETE statement or a SQL statement that returns nothing

Returns:

either the row count for INSERT, UPDATE or DELETE or 0 for SQL statements that return nothing

Throws:

SQLException - if a database-access error occurs.

(Published)

execute

public boolean execute(String sql)
                throws SQLException

Execute a SQL statement that may return multiple results.

Parameters:

sql - the SQL string

Returns:

indication of status

Throws:

SQLException - if a database-access error occurs.

See Also:

Statement.execute(java.lang.String)

(Published)

executeBatch

public int[] executeBatch()
                   throws SQLException

Submits a batch of commands to the database for execution and if all commands execute successfully, returns an array of update counts.

Returns:

an array of update counts containing one element for each command in the batch. The elements of the array are ordered according to the order in which commands were added to the batch

Throws:

SQLException - if a database-access error occurs.

(Published)

close

public void close()
           throws SQLException

In many cases, it is desirable to immediately release a Statements's database and JDBC resources instead of waiting for this to happen when it is automatically closed; the close method provides this immediate release.

Note: A Statement is automatically closed when it is garbage collected. When a Statement is closed, its current ResultSet, if one exists, is also closed.

Throws:

SQLException - if a database-access error occurs.

(Published)

getMaxFieldSize

public int getMaxFieldSize()
                    throws SQLException

The maxFieldSize limit (in bytes) is the maximum amount of data returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR columns. If the limit is exceeded, the excess data is silently discarded.

Returns:

the current max column size limit; zero means unlimited

Throws:

SQLException - if a database-access error occurs.

(Published)

setMaxFieldSize

public void setMaxFieldSize(int max)
                     throws SQLException

The maxFieldSize limit (in bytes) is set to limit the size of data that can be returned for any column value; it only applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. If the limit is exceeded, the excess data is silently discarded. For maximum portability use values greater than 256.

Parameters:

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

Throws:

SQLException - if a database-access error occurs.

(Published)

getMaxRows

public int getMaxRows()
               throws SQLException

The maxRows limit is the maximum number of rows that a ResultSet can contain. If the limit is exceeded, the excess rows are silently dropped.

Returns:

the current max row limit; zero means unlimited

Throws:

SQLException - if a database-access error occurs.

(Published)

setMaxRows

public void setMaxRows(int max)
                throws SQLException

The maxRows limit is set to limit the number of rows that any ResultSet can contain. If the limit is exceeded, the excess rows are silently dropped.

Parameters:

max - the new max rows limit; zero means unlimited

Throws:

SQLException - if a database-access error occurs.

(Published)

setEscapeProcessing

public void setEscapeProcessing(boolean enable)
                         throws SQLException

If escape scanning is on (the default), the driver will do escape substitution before sending the SQL to the database. Note: Since prepared statements have usually been parsed prior to making this call, disabling escape processing for prepared statements will like have no affect.

Parameters:

enable - true to enable; false to disable

Throws:

SQLException - if a database-access error occurs.

(Published)

getQueryTimeout

public int getQueryTimeout()
                    throws SQLException

The queryTimeout limit is the number of seconds the driver will wait for an StatementWrapper to execute. If the limit is exceeded, a SQLException is thrown.

Returns:

the current query timeout limit in seconds; zero means unlimited

Throws:

SQLException - if a database-access error occurs.

(Published)

setQueryTimeout

public void setQueryTimeout(int seconds)
                     throws SQLException

The queryTimeout limit is the number of seconds the driver will wait for an StatementWrapper to execute. If the limit is exceeded, a SQLException is thrown.

Parameters:

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

Throws:

SQLException - if a database-access error occurs.

(Published)

cancel

public void cancel()
            throws SQLException

Cancel can be used by one thread to cancel an Ifstatement that is being executed by another thread. Note: NT does not support out-of-band breaks, therefore cancel() is unavailable for NT.

Throws:

SQLException - if a database-access error occurs.

(Published)

getWarnings

public SQLWarning getWarnings()
                       throws SQLException

The first warning reported by calls on this StatementWrapper is returned. An StatementWrapper's execute methods clear its SQLWarning chain. Subsequent StatementWrapper warnings will be chained to this SQLWarning.

The warning chain is automatically cleared each time a statement is (re)executed.

Note: If you are processing a ResultSet then any warnings associated with ResultSet reads will be chained on the ResultSet object.

Returns:

the first SQLWarning or null

Throws:

SQLException - if a database-access error occurs.

(Published)

clearWarnings

public void clearWarnings()
                   throws SQLException

After this call, getWarnings returns null until a new warning is reported for this StatementWrapper.

Throws:

SQLException - if a database-access error occurs.

(Published)

setCursorName

public void setCursorName(String name)
                   throws SQLException

Defines the SQL cursor name that will be used by subsequent Statement execute methods. This name can then be used in SQL positioned update/delete statements to identify the current row in the ResultSet generated by this statement. If the database doesn't support positioned update/delete, this method is a noop.

Note: By definition, positioned update/delete execution must be done by a different Statement than the one which generated the ResultSet being used for positioning. Also, cursor names must be unique within a Connection.

Parameters:

name - the new cursor name.

Throws:

SQLException - if a database-access error occurs.

(Published)

getResultSet

public ResultSet getResultSet()
                       throws SQLException

Returns the current result as a ResultSet. It should only be called once per result.

Returns:

the current result as a ResultSet; null if the result is an update count or there are no more results

Throws:

SQLException - if a database-access error occurs.

(Published)

getUpdateCount

public int getUpdateCount()
                   throws SQLException

Returns the current result as an update count; if the result is a ResultSet or there are no more results, -1 is returned. It should only be called once per result.

Returns:

the current result as an update count; -1 if it is a ResultSet or there are no more results

Throws:

SQLException - if a database-access error occurs.

(Published)

getMoreResults

public boolean getMoreResults()
                       throws SQLException

Moves to an StatementWrapper's next result. It returns true if this result is a ResultSet. getMoreResults also implicitly closes any current ResultSet obtained with getResultSet. There are no more results when (!getMoreResults() && (getUpdateCount() == -1)

Returns:

true if the next result is a ResultSet; false if it is an update count or there are no more results

Throws:

SQLException - if a database-access error occurs.

(Published)

addBatch

public void addBatch(String sql)
              throws SQLException

Adds the given SQL command to the current list of commmands for this Statement object. The commands in this list can be executed as a batch by calling the method executeBatch.

Parameters:

sql - SQL string

Throws:

SQLException - if a database-access error occurs.

(Published)

clearBatch

public void clearBatch()
                throws SQLException

Empties this Statement object's current list of SQL commands.

Throws:

SQLException - if a database-access error occurs.

(Published)

dispose

public void dispose()

Dispose and close the StatementWrapper. This closes the statement. If the close fails, catch and do not re-throw the SQLException.

(Published)

closeStatement

public static void closeStatement(Statement stmt)

Close the specified Statement as a best effort; no exceptions thrown.

Parameters:

stmt - the Statement to close

(Unpublished)

closeStatement

public static void closeStatement(StatementWrapper stmt)

Close the specified wrapped Statement as a best effort; no exceptions thrown.

Parameters:

stmt - the wrapped Statement to close

(Unpublished)

closeResultSet

public static void closeResultSet(ResultSet rset)

Close the specified ResultSet as a best effort; no exceptions thrown.

Parameters:

rset - the ResultSet to close

(Unpublished)