Skip to content

Most visited

Recently visited

navigation
Added in API level 1

Statement

public interface Statement
implements Wrapper, AutoCloseable

java.sql.Statement
Known Indirect Subclasses


Interface used for executing static SQL statements to retrieve query results. The resulting table rows are returned as ResultSets. For any given Statement object, only one ResultSet can be opened at one time. A call to any of the execution methods of Statement will cause any previously created ResultSet object for that Statement to be closed implicitly.

To have multiple ResultSet objects opened concurrently, multiple Statement objects must be created and then executed.

To obtain such an executable statement one needs to invoke Connection#createStatement.

See also:

Summary

Constants

int CLOSE_ALL_RESULTS

Passing this constant to getMoreResults() implies that all ResultSet objects previously kept open should be closed.

int CLOSE_CURRENT_RESULT

Passing this constant to getMoreResults() implies that the current ResultSet object should be closed.

int EXECUTE_FAILED

Indicates that an error was encountered during execution of a batch statement.

int KEEP_CURRENT_RESULT

Passing this constant to getMoreResults implies that the current ResultSet object should not be closed.

int NO_GENERATED_KEYS

Indicates that generated keys should not be accessible for retrieval.

int RETURN_GENERATED_KEYS

Indicates that generated keys should be accessible for retrieval.

int SUCCESS_NO_INFO

Indicates that a batch statement was executed with a successful result, but a count of the number of rows it affected is unavailable.

Public methods

abstract void addBatch(String sql)

Adds a specified SQL command to the list of commands for this Statement.

abstract void cancel()

Cancels this statement's execution if both the database and the JDBC driver support aborting an SQL statement in flight.

abstract void clearBatch()

Clears the current list of SQL commands for this statement.

abstract void clearWarnings()

Clears all SQLWarnings from this statement.

abstract void close()

Releases this statement's database and JDBC driver resources.

abstract boolean execute(String sql)

Executes a supplied SQL statement.

abstract boolean execute(String sql, int autoGeneratedKeys)

Executes a supplied SQL statement.

abstract boolean execute(String sql, String[] columnNames)

Executes the supplied SQL statement.

abstract boolean execute(String sql, int[] columnIndexes)

Executes the supplied SQL statement.

abstract int[] executeBatch()

Submits a batch of SQL commands to the database.

abstract ResultSet executeQuery(String sql)

Executes a supplied SQL statement.

abstract int executeUpdate(String sql, int autoGeneratedKeys)

Executes the supplied SQL statement.

abstract int executeUpdate(String sql, String[] columnNames)

Executes the supplied SQL statement.

abstract int executeUpdate(String sql)

Executes the supplied SQL statement.

abstract int executeUpdate(String sql, int[] columnIndexes)

Executes the supplied SQL statement.

abstract Connection getConnection()

Gets the Connection object which created this statement.

abstract int getFetchDirection()

Gets the default direction for fetching rows for ResultSets generated from this statement.

abstract int getFetchSize()

Gets the default number of rows for a fetch for the ResultSet objects returned from this statement.

abstract ResultSet getGeneratedKeys()

Returns auto generated keys created by executing this statement.

abstract int getMaxFieldSize()

Gets the maximum number of bytes which can be returned as values from character and binary type columns in a ResultSet derived from this statement.

abstract int getMaxRows()

Gets the maximum number of rows that a ResultSet can contain when produced from this statement.

abstract boolean getMoreResults(int current)

Moves to this statement's next result.

abstract boolean getMoreResults()

Moves to this statement's next result.

abstract int getQueryTimeout()

Gets the timeout value for the statement's execution time.

abstract ResultSet getResultSet()

Gets the current result.

abstract int getResultSetConcurrency()

Gets the concurrency setting for ResultSet objects generated by this statement.

abstract int getResultSetHoldability()

Gets the cursor hold setting for ResultSet objects generated by this statement.

abstract int getResultSetType()

Gets the ResultSet type setting for ResultSets derived from this statement.

abstract int getUpdateCount()

Gets an update count for the current result if it is not a ResultSet.

abstract SQLWarning getWarnings()

Retrieves the first SQLWarning reported by calls on this statement.

abstract boolean isClosed()

Returns true if this statement has been closed, false otherwise.

abstract boolean isPoolable()

Returns true if this statement is poolable, false otherwise.

abstract void setCursorName(String name)

Sets the SQL cursor name.

abstract void setEscapeProcessing(boolean enable)

Sets Escape Processing mode.

abstract void setFetchDirection(int direction)

Sets the fetch direction - a hint to the JDBC driver about the direction of processing of rows in ResultSets created by this statement.

abstract void setFetchSize(int rows)

Sets the fetch size.

abstract void setMaxFieldSize(int max)

Sets the maximum number of bytes for ResultSet columns that contain character or binary values.

abstract void setMaxRows(int max)

Sets the maximum number of rows that any ResultSet can contain.

abstract void setPoolable(boolean poolable)

Hints whether this statement should be pooled.

abstract void setQueryTimeout(int seconds)

Sets the timeout, in seconds, for queries - how long the driver will allow for completion of a statement execution.

Inherited methods

From interface java.sql.Wrapper
From interface java.lang.AutoCloseable

Constants

CLOSE_ALL_RESULTS

Added in API level 1
int CLOSE_ALL_RESULTS

Passing this constant to getMoreResults() implies that all ResultSet objects previously kept open should be closed.

Constant Value: 3 (0x00000003)

CLOSE_CURRENT_RESULT

Added in API level 1
int CLOSE_CURRENT_RESULT

Passing this constant to getMoreResults() implies that the current ResultSet object should be closed.

Constant Value: 1 (0x00000001)

EXECUTE_FAILED

Added in API level 1
int EXECUTE_FAILED

Indicates that an error was encountered during execution of a batch statement.

Constant Value: -3 (0xfffffffd)

KEEP_CURRENT_RESULT

Added in API level 1
int KEEP_CURRENT_RESULT

Passing this constant to getMoreResults implies that the current ResultSet object should not be closed.

Constant Value: 2 (0x00000002)

NO_GENERATED_KEYS

Added in API level 1
int NO_GENERATED_KEYS

Indicates that generated keys should not be accessible for retrieval.

Constant Value: 2 (0x00000002)

RETURN_GENERATED_KEYS

Added in API level 1
int RETURN_GENERATED_KEYS

Indicates that generated keys should be accessible for retrieval.

Constant Value: 1 (0x00000001)

SUCCESS_NO_INFO

Added in API level 1
int SUCCESS_NO_INFO

Indicates that a batch statement was executed with a successful result, but a count of the number of rows it affected is unavailable.

Constant Value: -2 (0xfffffffe)

Public methods

addBatch

Added in API level 1
void addBatch (String sql)

Adds a specified SQL command to the list of commands for this Statement.

The list of commands is executed by invoking the executeBatch method.

Parameters
sql String: the SQL command as a String. Typically an INSERT or UPDATE statement.
Throws
SQLException if an error occurs accessing the database or the database does not support batch updates.

cancel

Added in API level 1
void cancel ()

Cancels this statement's execution if both the database and the JDBC driver support aborting an SQL statement in flight. This method can be used by one thread to stop a statement that is executed on another thread.

Throws
SQLException if an error occurs accessing the database.

clearBatch

Added in API level 1
void clearBatch ()

Clears the current list of SQL commands for this statement.

Throws
SQLException if an error occurs accessing the database or the database does not support batch updates.

clearWarnings

Added in API level 1
void clearWarnings ()

Clears all SQLWarnings from this statement.

Throws
SQLException if an error occurs accessing the database.

close

Added in API level 1
void close ()

Releases this statement's database and JDBC driver resources.

Using this method to release these resources as soon as possible is strongly recommended.

One should not rely on the resources being automatically released when finalized during garbage collection. Doing so can result in unpredictable behavior for the application.

Throws
SQLException if an error occurs accessing the database.

execute

Added in API level 1
boolean execute (String sql)

Executes a supplied SQL statement. This may return multiple ResultSets.

Use the getResultSet or getUpdateCount methods to get the first result and getMoreResults to get any subsequent results.

Parameters
sql String: the SQL statement to execute
Returns
boolean true if the first result is a ResultSet, false if the first result is an update count or if there is no result.
Throws
SQLException if an error occurs accessing the database.

execute

Added in API level 1
boolean execute (String sql, 
                int autoGeneratedKeys)

Executes a supplied SQL statement. This may return multiple ResultSets. This method allows control of whether auto-generated Keys should be made available for retrieval, if the SQL statement is an INSERT statement.

Use the getResultSet or getUpdateCount methods to get the first result and getMoreResults to get any subsequent results.

Parameters
sql String: the SQL statement to execute.
autoGeneratedKeys int: a flag indicating whether to make auto generated keys available for retrieval. This parameter must be one of Statement.NO_GENERATED_KEYS or Statement.RETURN_GENERATED_KEYS.
Returns
boolean true if results exists and the first result is a ResultSet, false if the first result is an update count or if there is no result.
Throws
SQLException if an error occurs accessing the database.

execute

Added in API level 1
boolean execute (String sql, 
                String[] columnNames)

Executes the supplied SQL statement. This may return multiple ResultSets. This method allows retrieval of auto generated keys specified by the supplied array of column indexes, if the SQL statement is an INSERT statement.

Use the getResultSet or getUpdateCount methods to get the first result and getMoreResults to get any subsequent results.

Parameters
sql String: the SQL statement to execute.
columnNames String: an array of column names in the inserted row which should be made available for retrieval via the getGeneratedKeys method.
Returns
boolean true if the first result is a ResultSet, false if the first result is an update count or if there is no result
Throws
SQLException if an error occurs accessing the database.

execute

Added in API level 1
boolean execute (String sql, 
                int[] columnIndexes)

Executes the supplied SQL statement. This may return multiple ResultSets. This method allows retrieval of auto generated keys specified by the supplied array of column indexes, if the SQL statement is an INSERT statement.

Use the getResultSet or getUpdateCount methods to get the first result and getMoreResults to get any subsequent results.

Parameters
sql String: the SQL statement to execute.
columnIndexes int: an array of indexes of the columns in the inserted row which should be made available for retrieval via the getGeneratedKeys method.
Returns
boolean true if the first result is a ResultSet, false if the first result is an update count or if there is no result.
Throws
SQLException if an error occurs accessing the database.

executeBatch

Added in API level 1
int[] executeBatch ()

Submits a batch of SQL commands to the database. Returns an array of update counts, if all the commands execute successfully.

If one of the commands in the batch fails, this method can throw a BatchUpdateException and the JDBC driver may or may not process the remaining commands. The JDBC driver must behave consistently with the underlying database, following the "all or nothing" principle. If the driver continues processing, the array of results returned contains the same number of elements as there are commands in the batch, with a minimum of one of the elements having the EXECUTE_FAILED value.

Returns
int[] an array of update counts, with one entry for each command in the batch. The elements are ordered according to the order in which the commands were added to the batch.

  1. If the value of an element is ≥ 0, the corresponding command completed successfully and the value is the update count (the number of rows in the database affected by the command) for that command.
  2. If the value is SUCCESS_NO_INFO, the command completed successfully but the number of rows affected is unknown.
  3. If the value is EXECUTE_FAILED, the command failed.
Throws
SQLException if an error occurs accessing the database.

executeQuery

Added in API level 1
ResultSet executeQuery (String sql)

Executes a supplied SQL statement. Returns a single ResultSet.

Parameters
sql String: an SQL statement to execute. Typically a SELECT statement
Returns
ResultSet a ResultSet containing the data produced by the SQL statement. Never null.
Throws
SQLException if an error occurs accessing the database or if the statement produces anything other than a single ResultSet.

executeUpdate

Added in API level 1
int executeUpdate (String sql, 
                int autoGeneratedKeys)

Executes the supplied SQL statement. This method allows control of whether auto-generated Keys should be made available for retrieval.

Parameters
sql String: an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or a statement which does not return anything.
autoGeneratedKeys int: a flag that indicates whether to allow retrieval of auto generated keys. Parameter must be one of Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS
Returns
int the number of updated rows, or 0 if the statement returns nothing.
Throws
SQLException if an error occurs accessing the database or if the statement produces a ResultSet.

executeUpdate

Added in API level 1
int executeUpdate (String sql, 
                String[] columnNames)

Executes the supplied SQL statement. This method allows retrieval of auto generated keys specified by the supplied array of column names.

Parameters
sql String: an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or a statement which returns nothing
columnNames String: an array of column names in the inserted row which should be made available for retrieval via the getGeneratedKeys method.
Returns
int the count of updated rows, or 0 for a statement that returns nothing.
Throws
SQLException if an error occurs accessing the database or if the statement produces a ResultSet.

executeUpdate

Added in API level 1
int executeUpdate (String sql)

Executes the supplied SQL statement. The statement may be an INSERT, UPDATE or DELETE statement or a statement which returns nothing.

Parameters
sql String: an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or a statement which returns nothing
Returns
int the count of updated rows, or 0 for a statement that returns nothing.
Throws
SQLException if an error occurs accessing the database or if the statement produces a ResultSet.

executeUpdate

Added in API level 1
int executeUpdate (String sql, 
                int[] columnIndexes)

Executes the supplied SQL statement. This method allows retrieval of auto generated keys specified by the supplied array of column indexes.

Parameters
sql String: an SQL statement to execute - an SQL INSERT, UPDATE, DELETE or a statement which returns nothing
columnIndexes int: an array of indexes of the columns in the inserted row which should be made available for retrieval via the getGeneratedKeys method.
Returns
int the count of updated rows, or 0 for a statement that returns nothing.
Throws
SQLException if an error occurs accessing the database or if the statement produces a ResultSet.

getConnection

Added in API level 1
Connection getConnection ()

Gets the Connection object which created this statement.

Returns
Connection the Connection through which this statement is transmitted to the database.
Throws
SQLException if an error occurs accessing the database.

getFetchDirection

Added in API level 1
int getFetchDirection ()

Gets the default direction for fetching rows for ResultSets generated from this statement.

Returns
int the default fetch direction, one of:
  • ResultSet.FETCH_FORWARD
  • ResultSet.FETCH_REVERSE
  • ResultSet.FETCH_UNKNOWN
Throws
SQLException if an error occurs accessing the database.

getFetchSize

Added in API level 1
int getFetchSize ()

Gets the default number of rows for a fetch for the ResultSet objects returned from this statement.

Returns
int the default fetch size for ResultSets produced by this statement.
Throws
SQLException if an error occurs accessing the database.

getGeneratedKeys

Added in API level 1
ResultSet getGeneratedKeys ()

Returns auto generated keys created by executing this statement.

Returns
ResultSet a ResultSet containing the auto generated keys - empty if no keys are generated by this statement.
Throws
SQLException if an error occurs accessing the database.

getMaxFieldSize

Added in API level 1
int getMaxFieldSize ()

Gets the maximum number of bytes which can be returned as values from character and binary type columns in a ResultSet derived from this statement. This limit applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR types. Any data exceeding the maximum size is abandoned without announcement.

Returns
int the current size limit, where 0 means that there is no limit.
Throws
SQLException if an error occurs accessing the database.

getMaxRows

Added in API level 1
int getMaxRows ()

Gets the maximum number of rows that a ResultSet can contain when produced from this statement. If the limit is exceeded, the excess rows are discarded silently.

Returns
int the current row limit, where 0 means that there is no limit.
Throws
SQLException if an error occurs accessing the database.

getMoreResults

Added in API level 1
boolean getMoreResults (int current)

Moves to this statement's next result. Returns true if the next result is a ResultSet. Any current ResultSet objects previously obtained with getResultSet() are handled as indicated by a supplied Flag parameter.

Parameters
current int: a flag indicating what to do with existing ResultSets. This parameter must be one of Statement.CLOSE_ALL_RESULTS, Statement.CLOSE_CURRENT_RESULT or Statement.KEEP_CURRENT_RESULT.
Returns
boolean true if the next result exists and is a ResultSet , false if the next result is not a ResultSet or if there are no more results. Note that if there is no more data, this method will return false and getUpdateCount will return -1.
Throws
SQLException if an error occurs accessing the database.

getMoreResults

Added in API level 1
boolean getMoreResults ()

Moves to this statement's next result. Returns true if it is a ResultSet. Any current ResultSet objects previously obtained with getResultSet() are closed implicitly.

Returns
boolean true if the next result is a ResultSet, false if the next result is not a ResultSet or if there are no more results. Note that if there is no more data, this method will return false and getUpdateCount will return -1.
Throws
SQLException if an error occurs accessing the database.

getQueryTimeout

Added in API level 1
int getQueryTimeout ()

Gets the timeout value for the statement's execution time. The JDBC driver will wait up to this value for the execution to complete - after the limit is exceeded an SQL Exception is thrown.

Returns
int the current query timeout value, where 0 indicates that there is no current timeout.
Throws
SQLException if an error occurs accessing the database.

getResultSet

Added in API level 1
ResultSet getResultSet ()

Gets the current result. Should only be called once per result.

Returns
ResultSet the ResultSet for the current result. null if the result is an update count or if there are no more results.
Throws
SQLException if an error occurs accessing the database.

getResultSetConcurrency

Added in API level 1
int getResultSetConcurrency ()

Gets the concurrency setting for ResultSet objects generated by this statement.

Returns
int ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE.
Throws
SQLException if an error occurs accessing the database.

getResultSetHoldability

Added in API level 1
int getResultSetHoldability ()

Gets the cursor hold setting for ResultSet objects generated by this statement.

Returns
int ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
Throws
SQLException if there is an error while accessing the database.

getResultSetType

Added in API level 1
int getResultSetType ()

Gets the ResultSet type setting for ResultSets derived from this statement.

Returns
int ResultSet.TYPE_FORWARD_ONLY for a ResultSet where the cursor can only move forwards, ResultSet.TYPE_SCROLL_INSENSITIVE for a ResultSet which is scrollable but is not sensitive to changes made by others, ResultSet.TYPE_SCROLL_SENSITIVE for a ResultSet which is scrollable but is sensitive to changes made by others.
Throws
SQLException if there is an error accessing the database.

getUpdateCount

Added in API level 1
int getUpdateCount ()

Gets an update count for the current result if it is not a ResultSet.

Returns
int the current result as an update count. -1 if the current result is a ResultSet or if there are no more results.
Throws
SQLException if an error occurs accessing the database.

getWarnings

Added in API level 1
SQLWarning getWarnings ()

Retrieves the first SQLWarning reported by calls on this statement. If there are multiple warnings, subsequent warnings are chained to the first one. The chain of warnings is cleared each time the statement is executed.

Warnings associated with reads from the ResultSet returned from executing the statement will be attached to the ResultSet, not the statement object.

Returns
SQLWarning an SQLWarning, null if there are no warnings
Throws
SQLException if an error occurs accessing the database.

isClosed

Added in API level 9
boolean isClosed ()

Returns true if this statement has been closed, false otherwise.

Returns
boolean
Throws
SQLException

isPoolable

Added in API level 9
boolean isPoolable ()

Returns true if this statement is poolable, false otherwise.

Returns
boolean
Throws
SQLException

setCursorName

Added in API level 1
void setCursorName (String name)

Sets the SQL cursor name. This name is used by subsequent statement execute methods.

Cursor names must be unique within one Connection.

With the cursor name set, it can then be used in SQL positioned update or delete statements to determine the current row in a ResultSet generated from this statement. The positioned update or delete must be done with a different statement than this one.

Parameters
name String: the Cursor name as a string,
Throws
SQLException if an error occurs accessing the database.

setEscapeProcessing

Added in API level 1
void setEscapeProcessing (boolean enable)

Sets Escape Processing mode.

If Escape Processing is on, the JDBC driver will do escape substitution on an SQL statement before sending it for execution. This does not apply to PreparedStatements since they are processed when created, before this method can be called.

Parameters
enable boolean: true to set escape processing mode on, false to turn it off.
Throws
SQLException if an error occurs accessing the database.

setFetchDirection

Added in API level 1
void setFetchDirection (int direction)

Sets the fetch direction - a hint to the JDBC driver about the direction of processing of rows in ResultSets created by this statement. The default fetch direction is FETCH_FORWARD.

Parameters
direction int: which fetch direction to use. This parameter should be one of
  • ResultSet.FETCH_UNKNOWN
  • ResultSet.FETCH_FORWARD
  • ResultSet.FETCH_REVERSE
Throws
SQLException if there is an error while accessing the database or if the fetch direction is unrecognized.

setFetchSize

Added in API level 1
void setFetchSize (int rows)

Sets the fetch size. This is a hint to the JDBC driver about how many rows should be fetched from the database when more are required by application processing.

Parameters
rows int: the number of rows that should be fetched. 0 tells the driver to ignore the hint. Should be less than getMaxRows for this statement. Should not be negative.
Throws
SQLException if an error occurs accessing the database, or if the rows parameter is out of range.

setMaxFieldSize

Added in API level 1
void setMaxFieldSize (int max)

Sets the maximum number of bytes for ResultSet columns that contain character or binary values. This applies to BINARY, VARBINARY, LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. Any data exceeding the maximum size is abandoned without announcement.

Parameters
max int: the maximum field size in bytes. 0 means "no limit".
Throws
SQLException if an error occurs accessing the database or the max value is < 0.

setMaxRows

Added in API level 1
void setMaxRows (int max)

Sets the maximum number of rows that any ResultSet can contain. If the number of rows exceeds this value, the additional rows are silently discarded.

Parameters
max int: the maximum number of rows. 0 means "no limit".
Throws
SQLException if an error occurs accessing the database or if max < 0.

setPoolable

Added in API level 9
void setPoolable (boolean poolable)

Hints whether this statement should be pooled. Defaults to false for Statement, but true for CallableStatement and PreparedStatement. Pool manager implementations may or may not honor this hint.

Parameters
poolable boolean
Throws
SQLException

setQueryTimeout

Added in API level 1
void setQueryTimeout (int seconds)

Sets the timeout, in seconds, for queries - how long the driver will allow for completion of a statement execution. If the timeout is exceeded, the query will throw an SQLException.

Parameters
seconds int: timeout in seconds. 0 means no timeout ("wait forever")
Throws
SQLException if an error occurs accessing the database or if seconds < 0.
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.