: Class Statement

Overview

Package

Class

Tree

Deprecated

Index

Help

1.50.39

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

interbase.interclient
Class Statement

java.lang.Object
  |
  +--interbase.interclient.Statement

Direct Known Subclasses:: PreparedStatement

public class Statement
extends Object
implements Statement

A SQL container used for executing SQL, and a factory for result sets.

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

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

Since:: JDBC 1, with extended behavior in JDBC 2
See Also:: Connection.createStatement(), ResultSet

Method Summary
`void`	`addBatch(String sql)` Adds a SQL command to the current batch of commmands for the statement.
`void`	`cancel()` Cancel can be used by one thread to cancel a statement that is being executed by another thread.
`void`	`clearBatch()` Make the set of commands in the current batch empty.
`void`	`clearWarnings()` After this call, getWarnings returns null until a new warning is reported for this Statement.
`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.
`boolean`	`execute(String sql)` Execute a SQL statement that may return multiple results.
`int[]`	`executeBatch()` Submit a batch of commands to the database for execution.
`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 void`	`finalize()` A statement will be closed when its finalizer is called by the garbage collector.
`Connection`	`getConnection()` Return the Connection that produced this Statement.
`int`	`getFetchDirection()` Determine the fetch direction.
`int`	`getFetchSize()` Determine the default fetch size.
`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()` getMoreResults moves to a Statement's next result.
`int`	`getQueryTimeout()` The queryTimeout limit is the number of seconds the driver will wait for a Statement to execute.
`ResultSet`	`getResultSet()` getResultSet returns the current result as a ResultSet.
`int`	`getResultSetConcurrency()` Determine the result set concurrency.
`int`	`getResultSetType()` Determine the result set type.
`int`	`getUpdateCount()` 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 Statement is returned.
`void`	`setCursorName(String cursorName)` setCursorname 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`	`setFetchDirection(int direction)` Give a hint as to the direction in which the rows in a result set will be processed.
`void`	`setFetchSize(int rows)` Give 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 maxFieldSize)` 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 maxRows)` 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 a Statement to execute.

Methods inherited from class java.lang.Object

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

Method Detail

finalize

protected void finalize()
                 throws Throwable

A statement will be closed when its finalizer is called by the garbage collector. However, there is no guarantee that the garbage collector will ever run, and in general will not run when an application terminates abruptly without closing its resources.

Therefore, it is recommended that prepared statements be explicitly closed even if your application throws an exception. This can be achieved by placing a call to close() in a finally clause of your application as follows

 try {
   ...
 }
 finally {
   if (statement != null)
     try { statement.close (); } catch (SQLException e) {}
   if (connection != null)
     try { connection.close (); } catch (SQLException e) {}
 }

Or alternatively, use the System.runFinalizersOnExit () method.

Overrides:: finalize in class Object
Since:: Extension

executeQuery

public ResultSet executeQuery(String sql)
                       throws SQLException

Execute a SQL statement that returns a single ResultSet.

Specified by:: executeQuery in interface Statement
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.
Since:: JDBC 1

executeUpdate

public int executeUpdate(String sql)
                  throws SQLException

Execute a SQL INSERT, UPDATE or DELETE statement. In addition, SQL statements that return nothing such as SQL DDL statements can be executed.

Specified by:: executeUpdate in interface Statement
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.
Since:: JDBC 1

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.

Specified by:: close in interface Statement
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

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.

Specified by:: getMaxFieldSize in interface Statement
Returns:: the current max column size limit; zero means unlimited
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

setMaxFieldSize

public void setMaxFieldSize(int maxFieldSize)
                     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.

Specified by:: setMaxFieldSize in interface Statement
Parameters:: max - the new max column size limit; zero means unlimited
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

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.

Specified by:: getMaxRows in interface Statement
Returns:: the current max row limit; zero means unlimited
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

setMaxRows

public void setMaxRows(int maxRows)
                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.

Specified by:: setMaxRows in interface Statement
Parameters:: max - the new max rows limit; zero means unlimited
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

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.

Specified by:: setEscapeProcessing in interface Statement
Parameters:: enable - true to enable; false to disable
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

getQueryTimeout

public int getQueryTimeout()
                    throws SQLException

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

Specified by:: getQueryTimeout in interface Statement
Returns:: the current query timeout limit in seconds; zero means unlimited
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

setQueryTimeout

public void setQueryTimeout(int seconds)
                     throws SQLException

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

InterClient note: Throws DriverNotCapableException. InterBase does not support asynchronous query timeout or cancel.

Specified by:: setQueryTimeout in interface Statement
Parameters:: seconds - the new query timeout limit in seconds; zero means unlimited
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1, not yet supported

cancel

public void cancel()
            throws SQLException

Cancel can be used by one thread to cancel a statement that is being executed by another thread.

InterClient note: Throws DriverNotCapableException. InterBase does not support asynchronous query timeout or cancel.

Specified by:: cancel in interface Statement
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1, not yet supported

getWarnings

public SQLWarning getWarnings()
                       throws SQLException

The first warning reported by calls on this Statement is returned. A Statment's execute methods clear its SQLWarning chain. Subsequent Statement 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.

Specified by:: getWarnings in interface Statement
Returns:: the first SQLWarning or null
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

clearWarnings

public void clearWarnings()
                   throws SQLException

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

Specified by:: clearWarnings in interface Statement
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

setCursorName

public void setCursorName(String cursorName)
                   throws SQLException

setCursorname 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. To insure that a cursor has the proper isolation level to support update, the cursor's select statement should be of the form 'select for update ...'. If the 'for update' clause is omitted the positioned updates may fail.

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.

Specified by:: setCursorName in interface Statement
Parameters:: name - the new cursor name.
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 1

execute

public boolean execute(String sql)
                throws SQLException

Execute a 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're executing a stored procedure that you know may return multiple results, or unless you're dynamically executing an unknown SQL string. The "execute", "getMoreResults", "getResultSet" and "getUpdateCount" methods let you navigate through multiple results. The "execute" method executes a SQL statement and indicates the form of the first result. You can then use getResultSet or getUpdateCount to retrieve the result, and getMoreResults to move to any subsequent result(s).

Specified by:: execute in interface Statement
Parameters:: sql - any SQL statement
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.
Since:: JDBC 1
See Also:: getResultSet(), getUpdateCount(), getMoreResults()

getResultSet

public ResultSet getResultSet()
                       throws SQLException

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

Specified by:: getResultSet in interface Statement
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.
Since:: JDBC 1
See Also:: execute(java.lang.String)

getUpdateCount

public int getUpdateCount()
                   throws SQLException

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

Specified by:: getUpdateCount in interface Statement
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.
Since:: JDBC 1
See Also:: execute(java.lang.String)

getMoreResults

public boolean getMoreResults()
                       throws SQLException

getMoreResults moves to a Statement'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)

Specified by:: getMoreResults in interface Statement
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.
Since:: JDBC 1
See Also:: execute(java.lang.String)

setFetchDirection

public void setFetchDirection(int direction)
                       throws SQLException

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

Specified by:: setFetchDirection in interface Statement
Parameters:: direction - the initial direction for processing rows
Throws:: SQLException - if a database access error occurs or direction is not one of ResultSet.FETCH_FORWARD, ResultSet.FETCH_REVERSE, or ResultSet.FETCH_UNKNOWN
Since:: JDBC 2, not yet supported

getFetchDirection

public int getFetchDirection()
                      throws SQLException

Determine the fetch direction.

Specified by:: getFetchDirection in interface Statement
Returns:: the default fetch direction
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 2, not yet supported

setFetchSize

public void setFetchSize(int rows)
                  throws SQLException

Give 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 only affects result sets created using this statement. If the value specified is zero, then the hint is ignored. The default value is zero.

InterClient note: The default of zero lets the driver decide. By default, InterClient prefetches as many rows as can fill up a 128K buffer.

Specified by:: setFetchSize in interface Statement
Parameters:: rows - the number of rows to fetch
Throws:: SQLException - if a database access error occurs, or the condition 0 <= rows <= this.getMaxRows() is not satisfied.
Since:: JDBC 2, since InterClient 1.50

getFetchSize

public int getFetchSize()
                 throws SQLException

Determine the default fetch size.

Specified by:: getFetchSize in interface Statement
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 2, not yet supported

getResultSetConcurrency

public int getResultSetConcurrency()
                            throws SQLException

Determine the result set concurrency.

Specified by:: getResultSetConcurrency in interface Statement
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 2, not yet supported

getResultSetType

public int getResultSetType()
                     throws SQLException

Determine the result set type.

Specified by:: getResultSetType in interface Statement
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 2, not yet supported

addBatch

public void addBatch(String sql)
              throws SQLException

Adds a SQL command to the current batch of commmands for the statement. This method is optional.

Specified by:: addBatch in interface Statement
Parameters:: sql - typically this is a static SQL INSERT or UPDATE statement
Throws:: SQLException - if a database access error occurs, or the driver does not support batch statements
Since:: JDBC 2, not yet supported

clearBatch

public void clearBatch()
                throws SQLException

Make the set of commands in the current batch empty. This method is optional.

Specified by:: clearBatch in interface Statement
Throws:: SQLException - if a database access error occurs, or the driver does not support batch statements
Since:: JDBC 2, not yet supported

executeBatch

public int[] executeBatch()
                   throws SQLException

Submit a batch of commands to the database for execution. This method is optional.

Specified by:: executeBatch in interface Statement
Returns:: an array of update counts containing one element for each command in the batch. The array is ordered according to the order in which commands were inserted into the batch
Throws:: SQLException - if a database access error occurs, or the driver does not support batch statements
Since:: JDBC 2, not yet supported

getConnection

public Connection getConnection()
                         throws SQLException

Return the Connection that produced this Statement.

Specified by:: getConnection in interface Statement
Throws:: SQLException - if a database access error occurs.
Since:: JDBC 2, since 1.50