Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Interface java.sql.Connection


public interface Connection

A Connection represents a session with a specific database. Within the context of a Connection, SQL statements are executed and results are returned.

A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is obtained with the getMetaData method.

Note: By default the Connection automatically commits changes after executing each statement. If auto commit has been disabled, an explicit commit must be done or database changes will not be saved.

See Also:
getConnection, Statement, ResultSet, DatabaseMetaData

Field Summary
static int  TRANSACTION_NONE
Transactions are not supported.
static int  TRANSACTION_READ_COMMITTED
Dirty reads are prevented; non-repeatable reads and phantom reads can occur.
static int  TRANSACTION_READ_UNCOMMITTED
Dirty reads, non-repeatable reads and phantom reads can occur.
static int  TRANSACTION_REPEATABLE_READ
Dirty reads and non-repeatable reads are prevented; phantom reads can occur.
static int  TRANSACTION_SERIALIZABLE
Dirty reads, non-repeatable reads and phantom reads are prevented.
 

Method Summary
void  clearWarnings()
After this call, getWarnings returns null until a new warning is reported for this Connection.
void  close()
In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released; the close method provides this immediate release.
void  commit()
Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection.
Statement  createStatement()
SQL statements without parameters are normally executed using Statement objects.
boolean  getAutoCommit()
Get the current auto-commit state.
String  getCatalog()
Return the Connection's current catalog name.
DatabaseMetaData  getMetaData()
A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc.
int  getResultSetConcurrency()
JDBC 2.0 Determine the result set concurrency.
int  getResultSetType()
JDBC 2.0 Determine the result set type.
int  getTransactionIsolation()
Get this Connection's current transaction isolation mode.
Map  getTypeMap()
JDBC 2.0   * Get the type-map object associated with this connection.
SQLWarning  getWarnings()
The first warning reported by calls on this Connection is returned.
boolean  isClosed()
Tests to see if a Connection is closed.
boolean  isReadOnly()
Tests to see if the connection is in read-only mode.
String  nativeSQL(String sql)
A driver may convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; nativeSQL returns the native form of the statement that the driver would have sent.
CallableStatement  prepareCall(String sql)
A SQL stored procedure call statement is handled by creating a CallableStatement for it.
PreparedStatement  prepareStatement(String sql)
A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object.
void  rollback()
Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection.
void  setAutoCommit(boolean autoCommit)
If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions.
void  setCatalog(String catalog)
A sub-space of this Connection's database may be selected by setting a catalog name.
void  setReadOnly(boolean readOnly)
You can put a connection in read-only mode as a hint to enable database optimizations.
void  setResultSetConcurrency(int value)
JDBC 2.0 Set the concurrency value to be used for result sets produced on this connection.
void  setResultSetType(int type)
JDBC 2.0 Set the type for result sets produced on this connection.
void  setTransactionIsolation(int level)
You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values.
void  setTypeMap(Map map)
JDBC 2.0  * Install a type-map object as the default type-map for  * this connection.
 

Field Detail

TRANSACTION_NONE

public static final int TRANSACTION_NONE
Transactions are not supported.

TRANSACTION_READ_UNCOMMITTED

public static final int TRANSACTION_READ_UNCOMMITTED
Dirty reads, non-repeatable reads and phantom reads can occur.

TRANSACTION_READ_COMMITTED

public static final int TRANSACTION_READ_COMMITTED
Dirty reads are prevented; non-repeatable reads and phantom reads can occur.

TRANSACTION_REPEATABLE_READ

public static final int TRANSACTION_REPEATABLE_READ
Dirty reads and non-repeatable reads are prevented; phantom reads can occur.

TRANSACTION_SERIALIZABLE

public static final int TRANSACTION_SERIALIZABLE
Dirty reads, non-repeatable reads and phantom reads are prevented.
Method Detail

createStatement

public Statement createStatement() throws SQLException
SQL statements without parameters are normally executed using Statement objects. If the same SQL statement is executed many times, it is more efficient to use a PreparedStatement
Returns:
a new Statement object
Throws:
SQLException - if a database-access error occurs.

prepareStatement

public PreparedStatement prepareStatement(String sql) throws SQLException
A SQL statement with or without IN parameters can be pre-compiled and stored in a PreparedStatement object. This object can then be used to efficiently execute this statement multiple times.

Note: This method is optimized for handling parametric SQL statements that benefit from precompilation. If the driver supports precompilation, prepareStatement will send the statement to the database for precompilation. Some drivers may not support precompilation. In this case, the statement may not be sent to the database until the PreparedStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions.

Parameters:
sql - a SQL statement that may contain one or more '?' IN parameter placeholders
Returns:
a new PreparedStatement object containing the pre-compiled statement
Throws:
SQLException - if a database-access error occurs.

prepareCall

public CallableStatement prepareCall(String sql) throws SQLException
A SQL stored procedure call statement is handled by creating a CallableStatement for it. The CallableStatement provides methods for setting up its IN and OUT parameters, and methods for executing it.

Note: This method is optimized for handling stored procedure call statements. Some drivers may send the call statement to the database when the prepareCall is done; others may wait until the CallableStatement is executed. This has no direct affect on users; however, it does affect which method throws certain SQLExceptions.

Parameters:
sql - a SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is a JDBC function call escape string.
Returns:
a new CallableStatement object containing the pre-compiled SQL statement
Throws:
SQLException - if a database-access error occurs.

nativeSQL

public String nativeSQL(String sql) throws SQLException
A driver may convert the JDBC sql grammar into its system's native SQL grammar prior to sending it; nativeSQL returns the native form of the statement that the driver would have sent.
Parameters:
sql - a SQL statement that may contain one or more '?' parameter placeholders
Returns:
the native form of this statement
Throws:
SQLException - if a database-access error occurs.

setAutoCommit

public void setAutoCommit(boolean autoCommit) throws SQLException
If a connection is in auto-commit mode, then all its SQL statements will be executed and committed as individual transactions. Otherwise, its SQL statements are grouped into transactions that are terminated by either commit() or rollback(). By default, new connections are in auto-commit mode. The commit occurs when the statement completes or the next execute occurs, whichever comes first. In the case of statements returning a ResultSet, the statement completes when the last row of the ResultSet has been retrieved or the ResultSet has been closed. In advanced cases, a single statement may return multiple results as well as output parameter values. Here the commit occurs when all results and output param values have been retrieved.
Parameters:
autoCommit - true enables auto-commit; false disables auto-commit.
Throws:
SQLException - if a database-access error occurs.

getAutoCommit

public boolean getAutoCommit() throws SQLException
Get the current auto-commit state.
Returns:
Current state of auto-commit mode.
Throws:
SQLException - if a database-access error occurs.
See Also:
setAutoCommit

commit

public void commit() throws SQLException
Commit makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.
Throws:
SQLException - if a database-access error occurs.
See Also:
setAutoCommit

rollback

public void rollback() throws SQLException
Rollback drops all changes made since the previous commit/rollback and releases any database locks currently held by the Connection. This method should only be used when auto commit has been disabled.
Throws:
SQLException - if a database-access error occurs.
See Also:
setAutoCommit

close

public void close() throws SQLException
In some cases, it is desirable to immediately release a Connection's database and JDBC resources instead of waiting for them to be automatically released; the close method provides this immediate release.

Note: A Connection is automatically closed when it is garbage collected. Certain fatal errors also result in a closed Connection.

Throws:
SQLException - if a database-access error occurs.

isClosed

public boolean isClosed() throws SQLException
Tests to see if a Connection is closed.
Returns:
true if the connection is closed; false if it's still open
Throws:
SQLException - if a database-access error occurs.

getMetaData

public DatabaseMetaData getMetaData() throws SQLException
A Connection's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, etc. This information is made available through a DatabaseMetaData object.
Returns:
a DatabaseMetaData object for this Connection
Throws:
SQLException - if a database-access error occurs.

setReadOnly

public void setReadOnly(boolean readOnly) throws SQLException
You can put a connection in read-only mode as a hint to enable database optimizations.

Note: setReadOnly cannot be called while in the middle of a transaction.

Parameters:
readOnly - true enables read-only mode; false disables read-only mode.
Throws:
SQLException - if a database-access error occurs.

isReadOnly

public boolean isReadOnly() throws SQLException
Tests to see if the connection is in read-only mode.
Returns:
true if connection is read-only
Throws:
SQLException - if a database-access error occurs.

setCatalog

public void setCatalog(String catalog) throws SQLException
A sub-space of this Connection's database may be selected by setting a catalog name. If the driver does not support catalogs it will silently ignore this request.
Throws:
SQLException - if a database-access error occurs.

getCatalog

public String getCatalog() throws SQLException
Return the Connection's current catalog name.
Returns:
the current catalog name or null
Throws:
SQLException - if a database-access error occurs.

setTransactionIsolation

public void setTransactionIsolation(int level) throws SQLException
You can call this method to try to change the transaction isolation level using one of the TRANSACTION_* values.

Note: setTransactionIsolation cannot be called while in the middle of a transaction.

Parameters:
level - one of the TRANSACTION_* isolation values with the exception of TRANSACTION_NONE; some databases may not support other values
Throws:
SQLException - if a database-access error occurs.
See Also:
supportsTransactionIsolationLevel

getTransactionIsolation

public int getTransactionIsolation() throws SQLException
Get this Connection's current transaction isolation mode.
Returns:
the current TRANSACTION_* mode value
Throws:
SQLException - if a database-access error occurs.

getWarnings

public SQLWarning getWarnings() throws SQLException
The first warning reported by calls on this Connection is returned.

Note: Subsequent warnings will be chained to this SQLWarning.

Returns:
the first SQLWarning or null
Throws:
SQLException - if a database-access error occurs.

clearWarnings

public void clearWarnings() throws SQLException
After this call, getWarnings returns null until a new warning is reported for this Connection.
Throws:
SQLException - if a database-access error occurs.

setResultSetConcurrency

public void setResultSetConcurrency(int value) throws SQLException
JDBC 2.0 Set the concurrency value to be used for result sets produced on this connection. The initial value is ResultSet.CONCUR_READONLY. This value may be overridden for an individual Statement object once it is created by calling Statement.setResultSetConcurrency().
Parameters:
value - the concurrency value
Throws:
SQLException - if a database-access error occurs or value is not one of ResultSet.CONCUR_READONLY, CONCUR_LOCK, CONCUR_VERSION, or CONCUR_VALUE.

getResultSetConcurrency

public int getResultSetConcurrency() throws SQLException
JDBC 2.0 Determine the result set concurrency.

setResultSetType

public void setResultSetType(int type) throws SQLException
JDBC 2.0 Set the type for result sets produced on this connection. The initial value is ResultSet.TYPE_FORWARD_ONLY. This value may be overridden for an individual Statement object once it is created by calling Statement.setResultSetType(), but not for a PreparedStatement object.
Throws:
SQLException - if a database-access error occurs, or type is not one of ResultSet.TYPE_FORWARD_ONLY, TYPE_STATIC, TYPE_KEYSET, or TYPE_DYNAMIC.

getResultSetType

public int getResultSetType() throws SQLException
JDBC 2.0 Determine the result set type.
Returns:
the result type
Throws:
SQLException - if a database-access error occurs

getTypeMap

public Map getTypeMap() throws SQLException
JDBC 2.0   * Get the type-map object associated with this connection.   * By default, the map returned is empty.  

setTypeMap

public void setTypeMap(Map map) throws SQLException
JDBC 2.0  * Install a type-map object as the default type-map for  * this connection.  

Contents | Package | Class | Tree | Deprecated | Index | Help Java 1.2 Beta 3
PREV | NEXT SHOW LISTS | HIDE LISTS

Submit a bug or feature
Submit comments/suggestions about new javadoc look.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.