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