Interface Connection

public interface Connection extends Object

A Connection is a session in a specific database engine. SQL statements and their results are executed within the context of such a Connection.

You can obtain information such as database tables, stored procedures, and other database objects from a Connection with the getMetaData methods.

All changes are committed after the execution of a statement. This is the default behavior. If autocommit has been disabled, an explicit commit must be done, or database changes won’t be effective.

See also: getConnection, Statement, ResultSet, DatabaseMetaData

Fields

TRANSACTION_NONE

public static final int TRANSACTION_NONE

This constant value specifies that transactions aren’t supported.

TRANSACTION_READ_COMMITTED

public static final int TRANSACTION_READ_COMMITTED

This constant value specifies that only reads on the current row are repeatable. Dirty reads aren’t allowed, but nonrepeatable and phantom reads can occur.

TRANSACTION_READ_UNCOMMITTED

public static final int TRANSACTION_READ_UNCOMMITTED

This constant value specifies that dirty reads, nonrepeatable reads, and phantom reads can occur.

TRANSACTION_REPEATABLE_READ

public static final int TRANSACTION_REPEATABLE_READ

This constant value specifies that only phantom reads can occur.

TRANSACTION_SERIALIZABLE

public static final int TRANSACTION_SERIALIZABLE

This constant value specifies that dirty reads, nonrepeatable reads, and phantom reads cannot occur.

Methods

clearWarnings

public void clearWarnings() throws SQLException

This clears the chained warnings of a Connection. getWarnings() returns null until a new warning is reported.

close

public void close() throws SQLException

The close method provides an immediate release for a Connection. All its resources are released upon invocation, including resources maintained by the DBMS and the JDBC driver. Note that a Connection is automatically closed when it is garbage-collected.

commit

public void commit() throws SQLException

This method is used to commit transactions. All changes made since the previous commit() or rollback() are made permanent, and any database locks currently held by the Connection are released. Note that all PreparedStatements, CallableStatements, and ResultSets are implicitly closed when a Connection is committed.

See also: setAutoClose, setAutoCommit

createStatement

public Statement createStatement() throws SQLException

This method creates a Statement object used to execute SQL statements without parameters. Unlike PreparedStatement, this method is used for Statements that are executed only once.

Returns: A new Statement object

createStatement

public Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException 

This method creates a Statement object that generates ResultSet objects with the given type and concurrency.

Parameters:

resultSetType:	One of the following result set types: ResultSet.TYPE_FORWARD_ONLY ResultSet.TYPE_SCROLL_INSENSITIVE ResultSet.TYPE_SCROLL_SENSITIVE
resultSetConcurrency:	One of the following concurrency types: ResultSet.CONCUR_READ_ONLY ResultSet.CONCUR_UPDATABLE

Returns: The newly created Statement object

createStatement

public Statement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException

This method creates a Statement object that generates ResultSet objects with the given type and concurrency.

Parameters:

resultSetType:	One of the following result set types: ResultSet.TYPE_FORWARD_ONLY ResultSet.TYPE_SCROLL_INSENSITIVE ResultSet.TYPE_SCROLL_SENSITIVE
resultSetConcurrency:	One of the following concurrency types: ResultSet.CONCUR_READ_ONLY ResultSet.CONCUR_UPDATABLE
resultSetHoldability:	One of the following cursor holdabilities: ResultSet.HOLD_CURSORS_OVER_COMMIT ResultSet.CLOSE_CURSORS_AT_COMMIT

Returns: The newly created Statement object

getAutoClose

public boolean getAutoClose() throws SQLException

This checks whether the Connection’s state is autoclose.

Returns: The current state of autoclose mode

See also: setAutoClose

getAutoCommit

public boolean getAutoCommit() throws SQLException 

This checks whether the Connection’s state is autocommit.

Returns: The current state of autocommit mode

See also: setAutoCommit

getCatalog

public String getCatalog() throws SQLException

If catalogs are supported, this method returns the Connection’s current catalog name.

Returns: The current catalog name or null

getHoldability

public int getHoldability() throws SQLException

This gets the current holdability of ResultSet objects for this connection.

Returns: The holdability, which is one of the following:

• ResultSet.HOLD_CURSORS_OVER_COMMIT

• ResultSet.CLOSE_CURSORS_AT_COMMIT

getMetaData

public DatabaseMetaData getMetaData() throws SQLException

You can use the DatabaseMetaData object returned by this method to get information from the database engine. Such information includes a description of tables, stored procedures, keys and indexes, the supported SQL grammar, and so on. Refer to the DatabaseMetaData interface for more detail.

Returns: A DatabaseMetaData object

getTransactionIsolation

public int getTransactionIsolation() throws SQLException

This returns the current transaction isolation mode. The different values are those listed as TRANSACTION_XXX static variables.

Returns: The current transaction mode value

getTypeMap

public java.util.Map getTypeMap() throws SQLException

This gets the type map object for this connection.

Returns: The java.util.Map object associated with this connection

getWarnings

public SQLWarning getWarnings() throws SQLException

Warnings issued by calls on a Connection are chained together. This method returns the first warning that is reported as a SQLWarning.

Returns: The first SQLWarning or null

isClosed

public boolean isClosed() throws SQLException

This checks whether a connection has been closed.

Returns: true if the connection is closed or false if it’s still open

isReadOnly

public boolean isReadOnly() throws SQLException

This checks whether the Connection is in read-only mode.

Returns: true if Connection is read-only

nativeSQL

public String nativeSQL(String sql) throws SQLException

Under some circumstances, specific JDBC drivers may translate the SQL statements into a database’s native SQL grammar prior to sending them. This method is useful to obtain the native form of the statement that the driver would have sent.

Parameters:

sql:

A SQL statement. Note that it may contain ? parameter placeholders.

Returns: The native form of the statement

prepareCall

public CallableStatement prepareCall(String sql) throws SQLException

CallableStatements are used for stored procedure call statements. This method creates such an object that can be used later with appropriate methods to provide IN and OUT parameters to the stored procedure.

Parameters:

sql:

A SQL statement. Note that it may contain ? parameter placeholders.

Returns: A new CallableStatement object containing the precompiled SQL statement

prepareCall

public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException

CallableStatements are used for stored procedure call statements. This method creates such an object that can be used later with appropriate methods to provide IN and OUT parameters to the stored procedure.

Parameters:

sql:	The SQL string containing parameter marks
resultSetType:	One of the following result set types: ResultSet.TYPE_FORWARD_ONLY ResultSet.TYPE_SCROLL_INSENSITIVE ResultSet.TYPE_SCROLL_SENSITIVE
resultSetConcurrency:	One of the following concurrency types: ResultSet.CONCUR_READ_ONLY ResultSet.CONCUR_UPDATABLE

Returns: The newly created CallableStatement

prepareCall

public CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException

CallableStatements are used for stored procedure call statements. This method creates such an object that can be used later with appropriate methods to provide IN and OUT parameters to the stored procedure.

Parameters:

sql:	The SQL string containing parameter marks
resultSetType:	One of the following result set types: ResultSet.TYPE_FORWARD_ONLY ResultSet.TYPE_SCROLL_INSENSITIVE ResultSet.TYPE_SCROLL_SENSITIVE
resultSetConcurrency:	One of the following concurrency types: ResultSet.CONCUR_READ_ONLY ResultSet.CONCUR_UPDATABLE
resultSetHoldability:	One of the following cursor holdabilities: ResultSet.HOLD_CURSORS_OVER_COMMIT ResultSet.CLOSE_CURSORS_AT_COMMIT

Returns: The newly created CallableStatement

prepareStatement

public PreparedStatement prepareStatement(String sql) throws SQLException

This method returns a PreparedStatement object. Such objects are useful when a SQL statement must be executed multiple times. The SQL statement is precompiled before it actually receives parameters and is executed. If supported by the driver and by the DBMS, parsing and optimizations are performed only once during precompilation.

Parameters:

sql:

A SQL statement. Note that it is normally used with ? IN parameter placeholders.

Returns: The newly created PreparedStatement object

prepareStatement

public PreparedStatement prepareStatement(String sql, int[] columnIndexes) throws SQLException

This method returns a PreparedStatement object. Such objects are useful when a SQL statement must be executed multiple times. The SQL statement is precompiled before it actually receives parameters and is executed. If supported by the driver and by the DBMS, parsing and optimizations are performed only once during precompilation.

Parameters:

sql:	A SQL statement. Note that it is normally used with ? IN parameter placeholders.
columnIndexes:	An array containing the column numbers returned by the statement in case of an update.

Returns: The newly created PreparedStatement object

prepareStatement

public PreparedStatement prepareStatement(String sql, String[] columnNames) throws SQLException

This method returns a PreparedStatement object. Such objects are useful when a SQL statement must be executed multiple times. The SQL statement is precompiled before it actually receives parameters and is executed. If supported by the driver and by the DBMS, parsing and optimizations are performed only once during precompilation.

Parameters:

sql:	A SQL statement. Note that it is normally used with ? IN parameter placeholders.
columnNames:	An array containing the column names returned by the

statement in case of an update.

Returns: The newly created PreparedStatement object

prepareStatement

public PreparedStatement prepareStatement(String sql, int flag) throws SQLException

This method returns a PreparedStatement object. Such objects are useful when a SQL statement must be executed multiple times. The SQL statement is precompiled before it actually receives parameters and is executed. If supported by the driver and by the DBMS, parsing and optimizations are performed only once during precompilation.

Parameters:

sql:	A SQL statement. Note that it is normally used with ‘?’ IN parameter placeholders.
flag:	One of the following flags, which indicate whether auto-generated keys should be returned: Statement.RETURN_GENERATED_KEYS Statement.NO_GENERATED_KEYS

Returns: The newly created PreparedStatement object

prepareStatement

public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException

This method returns a PreparedStatement object. Such objects are useful when a SQL statement must be executed multiple times. The SQL statement is precompiled before it actually receives parameters and is executed. If supported by the driver and by the DBMS, parsing and optimizations are performed only once during precompilation.

Parameters:

sql:	The SQL string containing IN parameters represented by ?
resultSetType:	One of the following result set types: ResultSet.TYPE_FORWARD_ONLY ResultSet.TYPE_SCROLL_INSENSITIVE ResultSet.TYPE_SCROLL_SENSITIVE
resultSetConcurrency:	One of the following concurrency types: ResultSet.CONCUR_READ_ONLY ResultSet.CONCUR_UPDATABLE

Returns: The newly created PreparedStatement

prepareStatement

public PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException

This method returns a PreparedStatement object. Such objects are useful when a SQL statement must be executed multiple times. The SQL statement is precompiled before it actually receives parameters and is executed. If supported by the driver and by the DBMS, parsing and optimizations are performed only once during precompilation.

Parameters:

sql:	The SQL string containing IN parameters represented by ?
resultSetType:	One of the following result set types: ResultSet.TYPE_FORWARD_ONLY ResultSet.TYPE_SCROLL_INSENSITIVE ResultSet.TYPE_SCROLL_SENSITIVE
resultSetConcurrency:	One of the following concurrency types: ResultSet.CONCUR_READ_ONLY ResultSet.CONCUR_UPDATABLE
resultSetHoldability:	One of the following cursor holdabilities: ResultSet.HOLD_CURSORS_OVER_COMMIT ResultSet.CLOSE_CURSORS_AT_COMMIT

Returns: The newly created PreparedStatement

releaseSavepoint

public void releaseSavepoint(Savepoint savepoint) throws SQLException

This deletes a savepoint from the current transaction.Parameters:

Parameters:

savepoint:

The savepoint to be removed

rollback

public void rollback() throws SQLException

Unlike commit(), rollback() cancels all changes made since the previous commit() or rollback() invocation and releases any database locks currently held by the Connection. This method is used to abort transactions. Note that a Connection’s PreparedStatements, CallableStatements, and ResultSets are implicitly closed when it is rolled back.

See also: setAutoClose, setAutoCommit

rollback

public void rollback(Savepoint savepoint) throws SQLException

This cancels all the changes that were made after the savepoint was set.

Parameters:

savepoint:

The savepoint to roll back to

setAutoClose

public void setAutoClose(boolean autoClose) throws SQLException

When autoclose is disabled, JDBC attempts to keep all Statements and ResultSets open across commits and rollbacks.

Parameters:

autoClose:

true enables autoclose; false disables autoclose.

See also: supportsOpenCursorsAcrossCommit, supportsOpenCursorsAcrossRollback, supportsOpenStatementsAcrossCommit, supportsOpenStatementsAcrossRollback

setAutoCommit

public void setAutoCommit(boolean autoCommit) throws SQLException

SQL statements are executed and committed as individual transactions if a Connection is in autocommit mode. If not in autocommit mode, the SQL statements are grouped into transactions that are terminated by either commit() or rollback(). By default, new connections are in autocommit mode. In autocommit mode, a commit always occurs after all results and output parameter values for a specific statement have been retrieved.

Parameters:

autoCommit:

true enables autocommit; false disables it.

setCatalog

public void setCatalog(String catalog) throws SQLException

If the database supports catalogs, this method selects a specific catalog. The method has no effect if catalogs aren’t supported.

setHoldability

public void setHoldability(int holdability) throws SQLException

This changes the holdability of ResultSet objects for the connection.

Parameters:

holdability:

One of the following values:

• ResultSet.HOLD_CURSORS_OVER_COMMIT

• ResultSet.CLOSE_CURSORS_AT_COMMIT

setReadOnly

public void setReadOnly(boolean readOnly) throws SQLException

This sets connections in read-only mode. In this case, no database updates are allowed, and performance is often improved. Note that this method cannot be called while in the middle of a transaction.

Parameters:

readOnly:

true enables read-only mode; false disables read-only mode.

setSavepoint

public Savepoint setSavepoint() throws SQLException

This sets an unnamed savepoint. The savepoint will be automatically numbered.

Returns: The savepoint

setSavepoint

public Savepoint setSavepoint(String name) throws SQLException

This sets a named savepoint.

Parameters:

name:

The name of the savepoint

Returns: The savepoint

setTransactionIsolation

public void setTransactionIsolation(int level) throws SQLException

This method is used to change the transaction isolation level using the TRANSACTION_ XXX static variables defined in the beginning of this section. Note that it cannot be called while in the middle of a transaction.

Parameters:

level:

A TRANSACTION_XXX isolation value with the exception of TRANSACTION_NONE

See also: supportsTransactionIsolationLevel

setTypeMap

public void setTypeMap(java.util.Map map) throws SQLException 

This sets the type map as the type map for the connection for the custom mapping of SQL structured types and distinct types.

Parameters:

map:

The java.util.Map object to install for the connection