java.sql
public
interface
java.sql.Connection
A Connection represents a link from a Java application to a database. All SQL
statements and results are returned within the context of a connection.
Summary
Constants
|
|
|
Value |
|
int |
TRANSACTION_NONE |
A constant indicating that transactions are not supported. |
0 |
0x00000000 |
int |
TRANSACTION_READ_COMMITTED |
No dirty reads are permitted. |
2 |
0x00000002 |
int |
TRANSACTION_READ_UNCOMMITTED |
Dirty reads (reading from table rows containing changes that have not yet
been committed), non-repeatable reads (reading table rows more than once
in a transaction but getting back different data because other
transactions may have altered rows between reads), and phantom reads
(retrieving additional "phantom" rows in the course of repeated table
reads because other transactions may have inserted additional rows that
satisfy an SQL WHERE clause) are all permitted. |
1 |
0x00000001 |
int |
TRANSACTION_REPEATABLE_READ |
A constant indicating that dirty reads and non-repeatable reads are
prevented; phantom reads can occur. |
4 |
0x00000004 |
int |
TRANSACTION_SERIALIZABLE |
Dirty reads (reading from table rows containing changes that have not yet
been committed), non-repeatable reads (reading table rows more than once
in a transaction but getting back different data because other
transactions may have altered rows between reads), and phantom reads
(retrieving additional "phantom" rows in the course of repeated table
reads because other transactions may have inserted additional rows that
satisfy an SQL WHERE clause) are all prevented. |
8 |
0x00000008 |
Public Methods
|
|
|
|
|
void |
clearWarnings() |
|
|
|
|
|
void |
close() |
|
|
|
|
|
void |
commit() |
|
|
|
|
|
Statement |
createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) |
|
|
|
|
|
Statement |
createStatement(int resultSetType, int resultSetConcurrency) |
|
|
|
|
|
Statement |
createStatement() |
|
|
|
|
|
boolean |
getAutoCommit() |
|
|
|
|
|
String |
getCatalog() |
|
|
|
|
|
int |
getHoldability() |
|
|
|
|
|
DatabaseMetaData |
getMetaData() |
|
|
|
|
|
int |
getTransactionIsolation() |
|
|
|
|
|
Map<String, Class<?>> |
getTypeMap() |
|
|
|
|
|
SQLWarning |
getWarnings() |
|
|
|
|
|
boolean |
isClosed() |
|
|
|
|
|
boolean |
isReadOnly() |
|
|
|
|
|
String |
nativeSQL(String sql) |
|
|
|
|
|
CallableStatement |
prepareCall(String sql) |
|
|
|
|
|
CallableStatement |
prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) |
|
|
|
|
|
CallableStatement |
prepareCall(String sql, int resultSetType, int resultSetConcurrency) |
|
|
|
|
|
PreparedStatement |
prepareStatement(String sql, int autoGeneratedKeys) |
|
|
|
|
|
PreparedStatement |
prepareStatement(String sql, String[] columnNames) |
|
|
|
|
|
PreparedStatement |
prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) |
|
|
|
|
|
PreparedStatement |
prepareStatement(String sql, int resultSetType, int resultSetConcurrency) |
|
|
|
|
|
PreparedStatement |
prepareStatement(String sql) |
|
|
|
|
|
PreparedStatement |
prepareStatement(String sql, int[] columnIndexes) |
|
|
|
|
|
void |
releaseSavepoint(Savepoint savepoint) |
|
|
|
|
|
void |
rollback(Savepoint savepoint) |
|
|
|
|
|
void |
rollback() |
|
|
|
|
|
void |
setAutoCommit(boolean autoCommit) |
|
|
|
|
|
void |
setCatalog(String catalog) |
|
|
|
|
|
void |
setHoldability(int holdability) |
|
|
|
|
|
void |
setReadOnly(boolean readOnly) |
|
|
|
|
|
Savepoint |
setSavepoint() |
|
|
|
|
|
Savepoint |
setSavepoint(String name) |
|
|
|
|
|
void |
setTransactionIsolation(int level) |
|
|
|
|
|
void |
setTypeMap(Map<String, Class<?>> map) |
Details
Constants
public
static
final
int
TRANSACTION_NONE
A constant indicating that transactions are not supported.
Constant Value:
0
(0x00000000)
public
static
final
int
TRANSACTION_READ_COMMITTED
No dirty reads are permitted. Transactions may not read a row containing
changes that have not yet been committed.
Constant Value:
2
(0x00000002)
public
static
final
int
TRANSACTION_READ_UNCOMMITTED
Dirty reads (reading from table rows containing changes that have not yet
been committed), non-repeatable reads (reading table rows more than once
in a transaction but getting back different data because other
transactions may have altered rows between reads), and phantom reads
(retrieving additional "phantom" rows in the course of repeated table
reads because other transactions may have inserted additional rows that
satisfy an SQL
WHERE
clause) are
all permitted.
Constant Value:
1
(0x00000001)
public
static
final
int
TRANSACTION_REPEATABLE_READ
A constant indicating that dirty reads and non-repeatable reads are
prevented; phantom reads can occur.
Constant Value:
4
(0x00000004)
public
static
final
int
TRANSACTION_SERIALIZABLE
Dirty reads (reading from table rows containing changes that have not yet
been committed), non-repeatable reads (reading table rows more than once
in a transaction but getting back different data because other
transactions may have altered rows between reads), and phantom reads
(retrieving additional "phantom" rows in the course of repeated table
reads because other transactions may have inserted additional rows that
satisfy an SQL
WHERE
clause) are
all prevented.
Constant Value:
8
(0x00000008)
Public Methods
public
void
clearWarnings()
Throws away any warnings that may have arisen for this connection.
Subsequent calls to
getWarnings() will return
null
up until a brand new warning condition occurs.
public
void
close()
Causes the instant release of all database and driver connection
resources associated with this object. Any subsequent invocations of this
method will have no effect.
It is strongly recommended that all Connections are closed before they
are dereferenced by the application ready for garbage collection. While
the finalize method of the Connection will close the Connection before
garbage collection takes place, it is not advisable to leave the close
operation to take place in this way. Unpredictable performance may result
from closing Connections in the finalizer.
public
void
commit()
Commits all of the changes made subsequent to the last commit or rollback
of the associated transaction. All locks in the database held by this
connection are also relinquished. Calling this operation on connection
objects in auto-commit mode is an error.
Throws
SQLException
| if there is a problem accessing the database or if the target
connection instance is in auto-commit mode.
|
public
Statement
createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)
Returns a new instance of
Statement
whose associated
ResultSet
s will have the characteristics specified in the
type, concurrency and holdability arguments.
Parameters
resultSetType
| one of :
|
resultSetConcurrency
| one of :
|
resultSetHoldability
| one of :
|
Returns
- a new instance of
Statement
capable of
manufacturing ResultSet
s that satisfy the
specified resultSetType
,
resultSetConcurrency
and
resultSetHoldability
values.
public
Statement
createStatement(int resultSetType, int resultSetConcurrency)
Returns a new instance of
Statement
whose associated
ResultSet
s will have the characteristics specified in the
type, concurrency and holdability arguments.
Parameters
resultSetType
| one of :
|
resultSetConcurrency
| one of :
|
Returns
- a new instance of
Statement
capable of
manufacturing ResultSet
s that satisfy the
specified resultSetType
and
resultSetConcurrency
values.
public
Statement
createStatement()
Returns a new instance of
Statement
for issuing SQL
commands to the remote database.
ResultSets generated by the returned Statement will default to type
TYPE_FORWARD_ONLY
and concurrency level
CONCUR_READ_ONLY
.
Returns
- a
Statement
object with default settings.
public
boolean
getAutoCommit()
Returns a boolean indication of whether or not this connection is in the
auto-commit operating mode.
Returns
true
if auto-commit is on, otherwise
false
public
String
getCatalog()
Gets this Connection object's current catalog name.
Returns
- the catalog name.
null
if there is no catalog
name.
public
int
getHoldability()
Returns the kind of holdability that any
ResultSet
s made
from this instance will have.
Gets the metadata about the database referenced by this connection. The
returned
DatabaseMetaData
describes the database
topography, available stored procedures, SQL syntax and so on.
Returns
- a
DatabaseMetaData
object containing the database
description
public
int
getTransactionIsolation()
Returns the present value of transaction isolation for this Connection
instance.
Returns
- the transaction isolation value
Returns the Type Map associated with this Connection object. The type map
will be empty unless the application has added at least one entry.
Returns
- the Type Map as a
java.util.Map
public
SQLWarning
getWarnings()
Gets the first instance of any
SQLWarning
objects that may
have been created in the use of this connection. If at least one warning
has occurred then this operation returns the first one reported. A
null
indicates that no warnings have occurred.
By invoking the getNextWarning() method of the
returned SQLWarning
object it is possible to obtain all
warning objects.
Returns
- the first warning as an SQLWarning object (may be
null
)
Throws
SQLException
| if there is a problem accessing the database or if the call
has been made on a connection which has been previously
closed.
|
public
boolean
isClosed()
Returns a boolean indication of whether or not this connection is in the
closed state. The closed state may be entered into as a consequence of a
successful invocation of the
close() method or else if an error
has occurred that prevents the connection from functioning normally.
Returns
true
if closed, otherwise false
public
boolean
isReadOnly()
Returns a boolean indication of whether or not this connection is
currently in read-only state.
Returns
true
if in read-only state, otherwise
false
.
Returns a string representation of the input SQL statement
sql
expressed in the underlying system's native SQL
syntax.
Parameters
sql
| the JDBC form of an SQL statement. |
Returns
- the SQL statement in native database format.
Returns a new instance of
CallableStatement
that may be
used for making stored procedure calls to the database.
Parameters
sql
| the SQL statement that calls the stored function |
Returns
- a new instance of
CallableStatement
representing
the SQL statement. ResultSet
s emitted from this
CallableStatement
will default to type
TYPE_FORWARD_ONLY and concurrency
CONCUR_READ_ONLY.
public
CallableStatement
prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
Returns a new instance of
CallableStatement
that may be
used for making stored procedure calls to the database. ResultSets
created from this
CallableStatement
will have
characteristics determined by the specified type, concurrency and
holdability arguments.
Parameters
sql
| the SQL statement |
resultSetType
| one of :
|
resultSetConcurrency
| one of :
|
resultSetHoldability
| one of :
|
Returns
- a new instance of
CallableStatement
representing
the precompiled SQL statement. ResultSet
s emitted
from this CallableStatement
will satisfy the
specified resultSetType
,
resultSetConcurrency
and
resultSetHoldability
values.
public
CallableStatement
prepareCall(String sql, int resultSetType, int resultSetConcurrency)
Returns a new instance of
CallableStatement
that may be
used for making stored procedure calls to the database.
ResultSet
s emitted from this
CallableStatement
will satisfy the specified
resultSetType
and
resultSetConcurrency
values.
Parameters
sql
| the SQL statement |
resultSetType
| one of :
|
resultSetConcurrency
| one of :
|
Returns
- a new instance of
CallableStatement
representing
the precompiled SQL statement. ResultSet
s emitted
from this CallableStatement
will satisfy the
specified resultSetType
and
resultSetConcurrency
values.
public
PreparedStatement
prepareStatement(String sql, int autoGeneratedKeys)
Creates a default PreparedStatement that can retrieve automatically
generated keys. Parameter
autoGeneratedKeys
may be used to
specify to the driver if such keys should be made accessible. This is
only the case when
sql
is an insert statement.
An SQL statement which may have IN parameters can be stored and
precompiled in a PreparedStatement. The PreparedStatement can then be
used to execute the statement multiple times in an efficient way.
Subject to JDBC driver support, this operation will attempt to send the
precompiled version of the statement to the database. Alternatively, if
the driver is not capable of flowing precompiled statements, the
statement will not reach the database server until it is executed. This
will have a bearing on precisely when SQLException
instances get raised.
By default, ResultSets from the returned object will be
TYPE_FORWARD_ONLY type with a
CONCUR_READ_ONLY mode of concurrency.
Parameters
sql
| the SQL statement. |
autoGeneratedKeys
| one of :
|
Returns
- a new
PreparedStatement
instance representing the
input SQL statement.
Creates a default PreparedStatement that can retrieve the auto-generated
keys designated by a supplied array. If
sql
is an SQL
INSERT
statement,
columnNames
is expected
to hold the names of each column in the statement's associated database
table containing the autogenerated-keys of interest. Otherwise
columnNames
is ignored.
Subject to JDBC driver support, this operation will attempt to send the
precompiled version of the statement to the database. Alternatively, if
the driver is not capable of flowing precompiled statements, the
statement will not reach the database server until it is executed. This
will have a bearing on precisely when SQLException
instances get raised.
By default, ResultSets from the returned object will be
TYPE_FORWARD_ONLY type with a
CONCUR_READ_ONLY mode of concurrency.
Parameters
sql
| the SQL statement. |
columnNames
| the names of the columns for which auto-generated keys should
be made available. |
Returns
- the PreparedStatement containing the supplied SQL statement
public
PreparedStatement
prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)
Creates a PreparedStatement that generates ResultSets with the specified
type, concurrency and holdability
Parameters
sql
| the SQL statement. It can contain one or more '?' IN parameter
placeholders |
resultSetType
| one of :
|
resultSetConcurrency
| one of :
|
resultSetHoldability
| one of :
|
Returns
- a new instance of
PreparedStatement
containing the
SQL statement sql
. ResultSet
s
emitted from this PreparedStatement
will satisfy
the specified resultSetType
,
resultSetConcurrency
and
resultSetHoldability
values.
public
PreparedStatement
prepareStatement(String sql, int resultSetType, int resultSetConcurrency)
Creates a PreparedStatement that generates ResultSets with the specified
values of
resultSetType
and
resultSetConcurrency
.
Parameters
sql
| the SQL statement. It can contain one or more '?' IN parameter
placeholders |
resultSetType
| one of :
|
resultSetConcurrency
| one of :
|
Returns
- a new instance of
PreparedStatement
containing the
SQL statement sql
. ResultSet
s
emitted from this PreparedStatement
will satisfy
the specified resultSetType
and
resultSetConcurrency
values.
Returns a new instance of
PreparedStatement
that may be
used any number of times to execute parameterized requests on the
database server.
Subject to JDBC driver support, this operation will attempt to send the
precompiled version of the statement to the database. Alternatively, if
the driver is not capable of flowing precompiled statements, the
statement will not reach the database server until it is executed. This
will have a bearing on precisely when SQLException
instances get raised.
By default, ResultSets from the returned object will be
TYPE_FORWARD_ONLY type with a
CONCUR_READ_ONLY mode of concurrency.
Returns
- the PreparedStatement containing the supplied SQL statement
public
PreparedStatement
prepareStatement(String sql, int[] columnIndexes)
Creates a default PreparedStatement that can retrieve the auto-generated
keys designated by a supplied array. If
sql
is an SQL
INSERT
statement, parameter
columnIndexes
is expected to hold the index values for each column in the statement's
intended database table containing the autogenerated-keys of interest.
Otherwise
columnIndexes
is ignored.
Subject to JDBC driver support, this operation will attempt to send the
precompiled version of the statement to the database. Alternatively, if
the driver is not capable of flowing precompiled statements, the
statement will not reach the database server until it is executed. This
will have a bearing on precisely when SQLException
instances get raised.
By default, ResultSets from the returned object will be
TYPE_FORWARD_ONLY type with a
CONCUR_READ_ONLY mode of concurrency.
Parameters
sql
| the SQL statement. |
columnIndexes
| the indexes of the columns for which auto-generated keys
should be made available. |
Returns
- the PreparedStatement containing the supplied SQL statement
public
void
releaseSavepoint(Savepoint savepoint)
Releases
savepoint
from the present transaction. Once
removed, the
Savepoint
is considered invalid and should
not be referenced further.
Parameters
savepoint
| the object targeted for removal |
Throws
SQLException
| if there is a problem with accessing the database or if
savepoint is considered not valid in this
transaction.
|
public
void
rollback(Savepoint savepoint)
Undoes all changes made after the supplied Savepoint object was set. This
method should only be used when auto-commit mode is disabled.
Parameters
savepoint
| the Savepoint to roll back to |
public
void
rollback()
Rolls back all updates made so far in this transaction as well as
relinquishing all acquired database locks. It is an error to invoke this
operation when in auto-commit mode.
Throws
SQLException
| if there is a problem with the database or if the method is
called while in auto-commit mode of operation.
|
public
void
setAutoCommit(boolean autoCommit)
Sets this connection's auto-commit mode on or off.
Putting a Connection into auto-commit mode means that all associated SQL
statements will be run and committed in their own separate transactions.
Alternatively, auto-commit set to off means that associated SQL
statements get grouped into transactions that need to be completed by
explicit calls to either the commit() or rollback()
methods.
Auto-commit is the default mode for new connection instances.
When in this mode, commits will automatically occur upon successful SQL
statement completion or upon successful completion of an execute.
Statements are not considered successfully complete until all associated
ResultSet
s and output parameters have been obtained or
closed.
Calling this operation during an uncommitted transaction will result in
it being committed.
Parameters
autoCommit
| boolean indication of whether to put the target connection
into auto-commit mode (true ) or not (false ) |
public
void
setCatalog(String catalog)
Sets the catalog name for this connection. This is used to select a
subspace of the database for future work. If the driver does not support
catalog names, this method is ignored.
Parameters
catalog
| the catalog name to use. |
public
void
setHoldability(int holdability)
Sets the holdability of ResultSets created by this Connection.
public
void
setReadOnly(boolean readOnly)
Sets this connection to read-only mode.
This serves as a hint to the driver, which can enable database
optimizations.
Parameters
readOnly
| true to set the Connection to read only mode. false disables
read-only mode |
public
Savepoint
setSavepoint()
Creates an unnamed Savepoint in the current transaction.
Returns
- a Savepoint object for this savepoint.
Creates a named Savepoint in the current transaction.
Parameters
name
| the name to use for the new Savepoint. |
Returns
- a Savepoint object for this savepoint.
public
void
setTransactionIsolation(int level)
Sets the transaction isolation level for this Connection.
If this method is called during a transaction, the results are
implementation defined.
Parameters
level
| the new transaction isolation level to use from the following
list of possible values :
|
Throws
SQLException
| if there is a problem with the database or if the value of
level is not one of the expected constant
values.
|
public
void
setTypeMap(Map<String, Class<?>> map)
Sets the
TypeMap
for this connection. The input
map
should contain mappings between complex Java and SQL
types.
Throws
SQLException
| if there is a problem accessing the database or if
map is not an instance of Map.
|