org.firebirdsql.jdbc

Class AbstractStatement

Implemented Interfaces:
FirebirdStatement, Statement, Synchronizable
Known Direct Subclasses:
AbstractPreparedStatement

public abstract class AbstractStatement
extends java.lang.Object
implements FirebirdStatement, Synchronizable

The object used for executing a static SQL statement and obtaining the results produced by it.

Only one ResultSet object per Statement object can be open at any point in time. Therefore, if the reading of one ResultSet object is interleaved with the reading of another, each must have been generated by different Statement objects. All statement execute methods implicitly close a statment's current ResultSet object if an open one exists.

Author:
David Jencks
See Also:
Connection.createStatement, ResultSet

Field Summary

protected boolean
completed
protected int
fetchSize
protected SQLWarning
firstWarning
protected org.firebirdsql.gds.impl.AbstractIscStmtHandle
fixedStmt
protected org.firebirdsql.gds.impl.GDSHelper
gdsHelper
protected boolean
hasMoreResults
protected boolean
isResultSet
protected int
maxRows
protected FBObjectListener.StatementListener
statementListener

Fields inherited from interface org.firebirdsql.jdbc.FirebirdStatement

CLOSE_ALL_RESULTS, CLOSE_CURRENT_RESULT, KEEP_CURRENT_RESULT

Constructor Summary

AbstractStatement(org.firebirdsql.gds.impl.GDSHelper c, int rsType, int rsConcurrency, int rsHoldability, FBObjectListener.StatementListener statementListener)

Method Summary

void
addBatch(String sql)
Adds an SQL command to the current batch of commmands for this Statement object.
protected void
addWarning(SQLWarning warning)
void
cancel()
Cancels this Statement object if both the DBMS and driver support aborting an SQL statement.
void
clearBatch()
Makes the set of commands in the current batch empty.
void
clearWarnings()
Clears all the warnings reported on this Statement object.
void
close()
Releases this Statement object's database and JDBC resources immediately instead of waiting for this to happen when it is automatically closed.
void
completeStatement()
boolean
execute(String sql)
Executes an 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)
Executes an SQL statement that returns a single ResultSet object.
int
executeUpdate(String sql)
Executes an SQL INSERT, UPDATE or DELETE statement.
protected void
finalize()
void
forgetResultSet()
Connection
getConnection()
Returns the Connection object that produced this Statement object.
ResultSet
getCurrentResultSet()
int
getDeletedRowsCount()
int
getFetchDirection()
Retrieves the direction for fetching rows from database tables that is the default for result sets generated from this Statement object.
int
getFetchSize()
Retrieves the number of result set rows that is the default fetch size for result sets generated from this Statement object.
int
getInsertedRowsCount()
String
getLastExecutionPlan()
int
getMaxFieldSize()
Returns the maximum number of bytes allowed for any column value.
int
getMaxRows()
Retrieves the maximum number of rows that a ResultSet object can contain.
boolean
getMoreResults()
Moves to a Statement object's next result.
boolean
getMoreResults(int mode)
int
getQueryTimeout()
Retrieves the number of seconds the driver will wait for a Statement object to execute.
ResultSet
getResultSet()
Returns the current result as a ResultSet object.
ResultSet
getResultSet(boolean trimStrings)
int
getResultSetConcurrency()
Retrieves the result set concurrency for ResultSet objects generated by this Statement object.
int
getResultSetHoldability()
Retrieves the result set holdability for ResultSet objects generated by this Statement object.
int
getResultSetType()
Retrieves the result set type for ResultSet objects generated by this Statement object.
Object
getSynchronizationObject()
Get synchronization object for this statement object.
int
getUpdateCount()
Returns the current result as an update count; if the result is a ResultSet object or there are no more results, -1 is returned.
int
getUpdatedRowsCount()
SQLWarning
getWarnings()
Retrieves the first warning reported by calls on this Statement object.
boolean
hasOpenResultSet()
protected boolean
internalExecute(String sql)
protected boolean
isExecuteProcedureStatement(String sql)
This method checks if supplied statement is executing procedure or it is generic statement.
boolean
isValid()
protected String
nativeSQL(String sql)
protected void
notifyStatementCompleted()
protected void
notifyStatementCompleted(boolean success)
protected void
notifyStatementStarted()
protected void
notifyStatementStarted(boolean closeResultSet)
protected void
prepareFixedStatement(String sql, boolean describeBind)
void
setCursorName(String name)
Defines the SQL cursor name that will be used by subsequent Statement object execute methods.
void
setEscapeProcessing(boolean enable)
Sets escape processing on or off.
void
setFetchDirection(int direction)
Gives the driver a hint as to the direction in which the rows in a result set will be processed.
void
setFetchSize(int rows)
Gives the JDBC driver a hint as to the number of rows that should be fetched from the database when more rows are needed.
void
setMaxFieldSize(int max)
Sets the limit for the maximum number of bytes in a column to the given number of bytes.
void
setMaxRows(int max)
Sets the limit for the maximum number of rows that any ResultSet object can contain to the given number.
void
setQueryTimeout(int seconds)
Sets the number of seconds the driver will wait for a Statement object to execute to the given number of seconds.
protected int[]
toArray(Collection list)
Convert collection of Integer elements into array of int.

Field Details

completed

protected boolean completed

fetchSize

protected int fetchSize

firstWarning

protected SQLWarning firstWarning

fixedStmt

protected org.firebirdsql.gds.impl.AbstractIscStmtHandle fixedStmt

gdsHelper

protected org.firebirdsql.gds.impl.GDSHelper gdsHelper

hasMoreResults

protected boolean hasMoreResults

isResultSet

protected boolean isResultSet

maxRows

protected int maxRows

statementListener

protected FBObjectListener.StatementListener statementListener

Constructor Details

AbstractStatement

protected AbstractStatement(org.firebirdsql.gds.impl.GDSHelper c,
                            int rsType,
                            int rsConcurrency,
                            int rsHoldability,
                            FBObjectListener.StatementListener statementListener)
            throws SQLException

Method Details

addBatch

public void addBatch(String sql)
            throws SQLException
Adds an SQL command to the current batch of commmands for this Statement object. This method is optional.
Parameters:
sql - typically this is a static SQL INSERT or UPDATE statement
Since:
1.2

addWarning

protected void addWarning(SQLWarning warning)

cancel

public void cancel()
            throws SQLException
Cancels this Statement object if both the DBMS and driver support aborting an SQL statement. This method can be used by one thread to cancel a statement that is being executed by another thread.

clearBatch

public void clearBatch()
            throws SQLException
Makes the set of commands in the current batch empty. This method is optional.
Since:
1.2

clearWarnings

public void clearWarnings()
            throws SQLException
Clears all the warnings reported on this Statement object. After a call to this method, the method getWarnings will return null until a new warning is reported for this Statement object.

close

public void close()
            throws SQLException
Releases this Statement object's database and JDBC resources immediately instead of waiting for this to happen when it is automatically closed. It is generally good practice to release resources as soon as you are finished with them to avoid tying up database resources.

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


completeStatement

public void completeStatement()
            throws SQLException

execute

public boolean execute(String sql)
            throws SQLException
Executes an SQL statement that may return multiple results. Under some (uncommon) situations a single SQL statement may return multiple result sets and/or update counts. Normally you can ignore this unless you are (1) executing a stored procedure that you know may return multiple results or (2) you are dynamically executing an unknown SQL string. The methods execute, getMoreResults, getResultSet, and getUpdateCount let you navigate through multiple results. The execute method executes an SQL statement and indicates the form of the first result. You can then use the methods getResultSet or getUpdateCount to retrieve the result, and getMoreResults to move to any subsequent result(s).
Parameters:
sql - any SQL statement
Returns:
true if the next result is a ResultSet object; false if it is an update count or there are no more results

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. The int elements of the array that is returned are ordered to correspond to the commands in the batch, which are ordered according to the order in which they were added to the batch. The elements in the array returned by the method executeBatch may be one of the following:
  1. A number greater than or equal to zero -- indicates that the command was processed successfully and is an update count giving the number of rows in the database that were affected by the command's execution
  2. A value of -2 -- indicates that the command was processed successfully but that the number of rows affected is unknown

    If one of the commands in a batch update fails to execute properly, this method throws a BatchUpdateException, and a JDBC driver may or may not continue to process the remaining commands in the batch. However, the driver's behavior must be consistent with a particular DBMS, either always continuing to process commands or never continuing to process commands. If the driver continues processing after a failure, the array returned by the method BatchUpdateException.getUpdateCounts will contain as many elements as there are commands in the batch, and at least one of the elements will be the following:

  3. A value of -3 -- indicates that the command failed to execute successfully and occurs only if a driver continues to process commands after a command fails

A driver is not required to implement this method. The possible implementations and return values have been modified in the Java 2 SDK, Standard Edition, version 1.3 to accommodate the option of continuing to proccess commands in a batch update after a BatchUpdateException obejct has been thrown.

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.
Since:
1.3

executeQuery

public ResultSet executeQuery(String sql)
            throws SQLException
Executes an SQL statement that returns a single ResultSet object.
Parameters:
sql - typically this is a static SQL SELECT statement
Returns:
a ResultSet object that contains the data produced by the given query; never null

executeUpdate

public int executeUpdate(String sql)
            throws SQLException
Executes an SQL INSERT, UPDATE or DELETE statement. In addition, SQL statements that return nothing, such as SQL DDL statements, can be executed.
Parameters:
sql - an SQL INSERT, UPDATE or DELETE statement or an SQL statement that returns nothing
Returns:
either the row count for INSERT, UPDATE or DELETE statements, or 0 for SQL statements that return nothing

finalize

protected void finalize()
            throws Throwable

forgetResultSet

public void forgetResultSet()

getConnection

public Connection getConnection()
            throws SQLException
Returns the Connection object that produced this Statement object.
Returns:
the connection that produced this statement

getCurrentResultSet

public ResultSet getCurrentResultSet()
            throws SQLException
Specified by:
getCurrentResultSet in interface FirebirdStatement

getDeletedRowsCount

public int getDeletedRowsCount()
            throws SQLException
Specified by:
getDeletedRowsCount in interface FirebirdStatement

getFetchDirection

public int getFetchDirection()
            throws SQLException
Retrieves the direction for fetching rows from database tables that is the default for result sets generated from this Statement object. If this Statement object has not set a fetch direction by calling the method setFetchDirection, the return value is implementation-specific.
Returns:
the default fetch direction for result sets generated from this Statement object
Since:
1.2

getFetchSize

public int getFetchSize()
            throws SQLException
Retrieves the number of result set rows that is the default fetch size for result sets generated from this Statement object. If this Statement object has not set a fetch size by calling the method setFetchSize, the return value is implementation-specific.
Returns:
the default fetch size for result sets generated from this Statement object
Since:
1.2

getInsertedRowsCount

public int getInsertedRowsCount()
            throws SQLException
Specified by:
getInsertedRowsCount in interface FirebirdStatement

getLastExecutionPlan

public String getLastExecutionPlan()
            throws SQLException
Specified by:
getLastExecutionPlan in interface FirebirdStatement

getMaxFieldSize

public int getMaxFieldSize()
            throws SQLException
Returns the maximum number of bytes allowed for any column value. This limit is the maximum number of bytes that can be returned for any column value. The limit applies only 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

getMaxRows

public int getMaxRows()
            throws SQLException
Retrieves the maximum number of rows that a ResultSet object can contain. If the limit is exceeded, the excess rows are silently dropped.
Returns:
the current max row limit; zero means unlimited

getMoreResults

public boolean getMoreResults()
            throws SQLException
Moves to a Statement object's next result. It returns true if this result is a ResultSet object. This method also implicitly closes any current ResultSet object obtained with the method getResultSet.

There are no more results when the following is true:

      (!getMoreResults() && (getUpdateCount() == -1)
 
Returns:
true if the next result is a ResultSet object; false if it is an update count or there are no more results

getMoreResults

public boolean getMoreResults(int mode)
            throws SQLException

getQueryTimeout

public int getQueryTimeout()
            throws SQLException
Retrieves the number of seconds the driver will wait for a Statement object to execute. If the limit is exceeded, a SQLException is thrown.
Returns:
the current query timeout limit in seconds; zero means unlimited

getResultSet

public ResultSet getResultSet()
            throws SQLException
Returns the current result as a ResultSet object. This method should be called only once per result. Calling this method twice with autocommit on and used will probably throw an inappropriate or uninformative exception.
Returns:
the current result as a ResultSet object; null if the result is an update count or there are no more results

getResultSet

public ResultSet getResultSet(boolean trimStrings)
            throws SQLException

getResultSetConcurrency

public int getResultSetConcurrency()
            throws SQLException
Retrieves the result set concurrency for ResultSet objects generated by this Statement object.
Returns:
either ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
Since:
1.2

getResultSetHoldability

public int getResultSetHoldability()
            throws SQLException
Retrieves the result set holdability for ResultSet objects generated by this Statement object.

getResultSetType

public int getResultSetType()
            throws SQLException
Retrieves the result set type for ResultSet objects generated by this Statement object.
Returns:
one of ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
Since:
1.2

getSynchronizationObject

public Object getSynchronizationObject()
            throws SQLException
Get synchronization object for this statement object.
Specified by:
getSynchronizationObject in interface Synchronizable
Returns:
object that will be used for synchronization.

getUpdateCount

public int getUpdateCount()
            throws SQLException
Returns the current result as an update count; if the result is a ResultSet object or there are no more results, -1 is returned. This method should be called only once per result.
Returns:
the current result as an update count; -1 if the current result is a ResultSet object or there are no more results

getUpdatedRowsCount

public int getUpdatedRowsCount()
            throws SQLException
Specified by:
getUpdatedRowsCount in interface FirebirdStatement

getWarnings

public SQLWarning getWarnings()
            throws SQLException
Retrieves the first warning reported by calls on this Statement object. Subsequent Statement object warnings will be chained to this SQLWarning object.

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

Note: If you are processing a ResultSet object, any warnings associated with reads on that ResultSet object will be chained on it.

Returns:
the first SQLWarning object or null

hasOpenResultSet

public boolean hasOpenResultSet()
Specified by:
hasOpenResultSet in interface FirebirdStatement

internalExecute

protected boolean internalExecute(String sql)
            throws GDSException,
                   SQLException

isExecuteProcedureStatement

protected boolean isExecuteProcedureStatement(String sql)
            throws SQLException
This method checks if supplied statement is executing procedure or it is generic statement. This check is needed to handle correctly parameters that are returned from non-selectable procedures.
Parameters:
sql - SQL statement to check
Returns:
true if supplied statement is EXECUTE PROCEDURE type of statement.

isValid

public boolean isValid()
Specified by:
isValid in interface FirebirdStatement

nativeSQL

protected String nativeSQL(String sql)
            throws SQLException

notifyStatementCompleted

protected void notifyStatementCompleted()
            throws SQLException

notifyStatementCompleted

protected void notifyStatementCompleted(boolean success)
            throws SQLException

notifyStatementStarted

protected void notifyStatementStarted()
            throws SQLException

notifyStatementStarted

protected void notifyStatementStarted(boolean closeResultSet)
            throws SQLException

prepareFixedStatement

protected void prepareFixedStatement(String sql,
                                     boolean describeBind)
            throws GDSException,
                   SQLException

setCursorName

public void setCursorName(String name)
            throws SQLException
Defines the SQL cursor name that will be used by subsequent Statement object execute methods. This name can then be used in SQL positioned update/delete statements to identify the current row in the ResultSet object generated by this statement. If the database doesn't support positioned update/delete, this method is a noop. To insure that a cursor has the proper isolation level to support updates, the cursor's SELECT statement should be of the form 'select for update ...'. If the 'for update' phrase is omitted, positioned updates may fail.

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

Parameters:
name - the new cursor name, which must be unique within a connection

setEscapeProcessing

public void setEscapeProcessing(boolean enable)
            throws SQLException
Sets escape processing on or off. 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 have no effect.
Parameters:
enable - true to enable; false to disable

setFetchDirection

public void setFetchDirection(int direction)
            throws SQLException
Gives the driver a hint as to the direction in which the rows in a result set will be processed. The hint applies only to result sets created using this Statement object. The default value is ResultSet.FETCH_FORWARD.

Note that this method sets the default fetch direction for result sets generated by this Statement object. Each result set has its own methods for getting and setting its own fetch direction.

Parameters:
direction - the initial direction for processing rows
Since:
1.2

setFetchSize

public void setFetchSize(int rows)
            throws SQLException
Gives the JDBC driver a hint as to the number of rows that should be fetched from the database when more rows are needed. The number of rows specified affects only result sets created using this statement. If the value specified is zero, then the hint is ignored. The default value is zero.
Parameters:
rows - the number of rows to fetch
Since:
1.2

setMaxFieldSize

public void setMaxFieldSize(int max)
            throws SQLException
Sets the limit for the maximum number of bytes in a column to the given number of bytes. This is the maximum number of bytes that can be returned for any column value. This limit applies only 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

setMaxRows

public void setMaxRows(int max)
            throws SQLException
Sets the limit for the maximum number of rows that any ResultSet object can contain to the given number. If the limit is exceeded, the excess rows are silently dropped.
Parameters:
max - the new max rows limit; zero means unlimited

setQueryTimeout

public void setQueryTimeout(int seconds)
            throws SQLException
Sets the number of seconds the driver will wait for a Statement object to execute to the given number of seconds. If the limit is exceeded, an SQLException is thrown.
Parameters:
seconds - the new query timeout limit in seconds; zero means unlimited

toArray

protected int[] toArray(Collection list)
Convert collection of Integer elements into array of int.
Parameters:
list - collection of integer elements.
Returns:
array of int.

Copyright B) 2001 David Jencks and other authors. All rights reserved.