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. Database statements that are executed within this context form a database session which forms one or more closed transactions. Especially in distributed applications, multiple concurrent connections may exist accessing the same values of the database. which may lead to the following phenomena (referred to as transaction isolation levels):
WHERE
clauseConstants | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
int | TRANSACTION_NONE | A constant indicating that transactions are not supported. | |||||||||
int | TRANSACTION_READ_COMMITTED | No dirty reads are permitted, therefore transactions may not read a row containing uncommitted values - but does not prevent an application from non-repeatable reads and phantom reads. | |||||||||
int | TRANSACTION_READ_UNCOMMITTED | In the case that reading uncommitted values is allowed, the following
incidents may happen which may lead to an invalid results:
|
|||||||||
int | TRANSACTION_REPEATABLE_READ | A constant indicating that dirty reads and non-repeatable reads are prevented but phantom reads can occur. | |||||||||
int | TRANSACTION_SERIALIZABLE | The constant that indicates that the following incidents are all
prevented (the opposite of TRANSACTION_READ_UNCOMMITTED ):
|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Discards all warnings that may have arisen for this connection.
| |||||||||||
Causes the instant release of all database and driver connection
resources associated with this object.
| |||||||||||
Commits all of the changes made since the last
commit or
rollback of the associated transaction. | |||||||||||
Returns a new
Array containing the given elements . | |||||||||||
Returns a new empty Blob.
| |||||||||||
Returns a new empty Clob.
| |||||||||||
Returns a new empty NClob.
| |||||||||||
Returns a new empty SQLXML.
| |||||||||||
Returns a new instance of
Statement whose associated ResultSet s have the characteristics specified in the type and
concurrency arguments. | |||||||||||
Returns a new instance of
Statement whose associated
ResultSet s will have the characteristics specified in the
type, concurrency and holdability arguments. | |||||||||||
Returns a new instance of
Statement for issuing SQL commands to
the remote database. | |||||||||||
Returns a new
Struct containing the given attributes . | |||||||||||
Returns a
boolean indicating whether or not this connection is in
the auto-commit operating mode. | |||||||||||
Gets this
Connection object's current catalog name. | |||||||||||
Returns the value corresponding to the given client info property, or null if unset.
| |||||||||||
Returns a
Properties object containing all client info properties. | |||||||||||
Returns the holdability property that any
ResultSet produced by
this instance will have. | |||||||||||
Gets the metadata about the database referenced by this connection.
| |||||||||||
Returns the transaction isolation level for this connection.
| |||||||||||
Returns the type mapping associated with this
Connection object. | |||||||||||
Gets the first instance of any
SQLWarning objects that may have
been created in the use of this connection. | |||||||||||
Returns a
boolean indicating whether or not this connection is in
the closed state. | |||||||||||
Returns a
boolean indicating whether or not this connection is
currently in the read-only state. | |||||||||||
Returns true if this connection is still open and valid, false otherwise.
| |||||||||||
Returns a string representation of the input SQL statement
sql expressed in the underlying system's native SQL
syntax. | |||||||||||
Returns a new instance of
CallableStatement that may be used for
making stored procedure calls to the database. | |||||||||||
Returns a new instance of
CallableStatement that may be used for
making stored procedure calls to the database. | |||||||||||
Returns a new instance of
CallableStatement that may be used for
making stored procedure calls to the database. | |||||||||||
Creates a default
PreparedStatement that can retrieve the
auto-generated keys designated by a supplied array. | |||||||||||
Creates a
PreparedStatement that generates ResultSet s
with the specified values of resultSetType and resultSetConcurrency . | |||||||||||
Returns a new instance of
PreparedStatement that may be used any
number of times to execute parameterized requests on the database server. | |||||||||||
Creates a default
PreparedStatement that can retrieve
automatically generated keys. | |||||||||||
Creates a
PreparedStatement that generates ResultSet s
with the specified type, concurrency and holdability | |||||||||||
Creates a default
PreparedStatement that can retrieve the
auto-generated keys designated by a supplied array. | |||||||||||
Releases the specified
savepoint from the present transaction. | |||||||||||
Rolls back all updates made so far in this transaction and
relinquishes all acquired database locks.
| |||||||||||
Undoes all changes made after the supplied
Savepoint object was
set. | |||||||||||
Sets this connection's auto-commit mode
on or off . | |||||||||||
Sets the catalog name for this connection.
| |||||||||||
Sets the client info property
name to value . | |||||||||||
Replaces all client info properties with the name/value pairs from
properties . | |||||||||||
Sets the holdability of the
ResultSet s created by this Connection. | |||||||||||
Sets this connection to read-only mode.
| |||||||||||
Creates a named
Savepoint in the current transaction. | |||||||||||
Creates an unnamed
Savepoint in the current transaction. | |||||||||||
Sets the transaction isolation level for this Connection.
| |||||||||||
Sets the
TypeMap for this connection. |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From interface
java.lang.AutoCloseable
| |||||||||||
From interface
java.sql.Wrapper
|
A constant indicating that transactions are not supported.
No dirty reads are permitted, therefore transactions may not read a row containing uncommitted values - but does not prevent an application from non-repeatable reads and phantom reads.
In the case that reading uncommitted values is allowed, the following incidents may happen which may lead to an invalid results:
A constant indicating that dirty reads and non-repeatable reads are prevented but phantom reads can occur.
The constant that indicates that the following incidents are all
prevented (the opposite of TRANSACTION_READ_UNCOMMITTED
):
Discards all warnings that may have arisen for this connection.
Subsequent calls to getWarnings()
will return null
up until a new warning condition occurs.
SQLException | if there is a problem accessing the database. |
---|
Causes the instant release of all database and driver connection resources associated with this object. Any subsequent invocations of this method have no effect.
It is strongly recommended that all connections are closed before they
are dereferenced by the application ready for garbage collection.
Although the finalize
method of the connection closes the
connection before garbage collection takes place, it is not advisable to
leave the close
operation to take place in this way. Mainly
because undesired side-effects may appear.
SQLException | if there is a problem accessing the database. |
---|
Commits all of the changes made since 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 leads to an error.
SQLException | if there is a problem accessing the database or if the target connection instance is in auto-commit mode. |
---|
Returns a new Array
containing the given elements
.
typeName | the SQL name of the type of the array elements |
---|
SQLClientInfoException | if this connection is closed, or there's a problem creating the array. |
---|---|
SQLException |
Returns a new empty Blob.
SQLException | if this connection is closed, or there's a problem creating a new blob. |
---|
Returns a new empty Clob.
SQLException | if this connection is closed, or there's a problem creating a new clob. |
---|
Returns a new empty NClob.
SQLException | if this connection is closed, or there's a problem creating a new nclob. |
---|
Returns a new empty SQLXML.
SQLException | if this connection is closed, or there's a problem creating a new XML. |
---|
Returns a new instance of Statement
whose associated ResultSet
s have the characteristics specified in the type and
concurrency arguments.
resultSetType | one of the following type specifiers: |
---|---|
resultSetConcurrency | one of the following concurrency mode specifiers: |
Statement
capable of manufacturing
ResultSet
s that satisfy the specified resultSetType
and resultSetConcurrency
values.SQLException | if there is a problem accessing the database |
---|
Returns a new instance of Statement
whose associated
ResultSet
s will have the characteristics specified in the
type, concurrency and holdability arguments.
resultSetType | one of the following type specifiers: |
---|---|
resultSetConcurrency | one of the following concurrency mode specifiers: |
resultSetHoldability | one of the following holdability mode specifiers: |
Statement
capable of
manufacturing ResultSet
s that satisfy the
specified resultSetType
,
resultSetConcurrency
and
resultSetHoldability
values.SQLException | if there is a problem accessing the database. |
---|
Returns a new instance of Statement
for issuing SQL commands to
the remote database.
ResultSets
generated by the returned statement will default to
type ResultSet.TYPE_FORWARD_ONLY
and concurrency level ResultSet.CONCUR_READ_ONLY
.
Statement
object with default settings.SQLException | if there is a problem accessing the database. |
---|
Returns a new Struct
containing the given attributes
.
typeName | the SQL name of the type of the struct attributes |
---|
SQLClientInfoException | if this connection is closed, or there's a problem creating the array. |
---|---|
SQLException |
Returns a boolean
indicating whether or not this connection is in
the auto-commit
operating mode.
true
if auto-commit
is on, otherwise false
.SQLException | if there is a problem accessing the database. |
---|
Gets this Connection
object's current catalog name.
null
if there is no catalog
name.SQLException | if there is a problem accessing the database. |
---|
Returns the value corresponding to the given client info property, or null if unset.
SQLClientInfoException | if this connection is closed, or there's a problem getting the property. |
---|---|
SQLException |
Returns a Properties
object containing all client info properties.
SQLClientInfoException | if this connection is closed, or there's a problem getting a property. |
---|---|
SQLException |
Returns the holdability property that any ResultSet
produced by
this instance will have.
SQLException | if there is a problem accessing the a database. |
---|
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.
DatabaseMetaData
object containing the database
description.SQLException | if there is a problem accessing the a database. |
---|
Returns the transaction isolation level for this connection.
SQLException | if there is a problem accessing the database. |
---|
Returns the type mapping associated with this Connection
object.
The type mapping must be set on the application level.
java.util.Map
.SQLException | if there is a problem accessing the database. |
---|
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 of
this connection's warning objects.
null
).SQLException | if there is a problem accessing the database or if the call has been made on a connection which has been previously closed. |
---|
Returns a boolean
indicating 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.
true
if closed, otherwise false
.SQLException | if there is a problem accessing the database. |
---|
Returns a boolean
indicating whether or not this connection is
currently in the read-only
state.
true
if in read-only state, otherwise false
.SQLException | if there is a problem accessing the database. |
---|
Returns true if this connection is still open and valid, false otherwise.
timeout | number of seconds to wait for a response before giving up and returning false, 0 to wait forever |
---|
SQLException | if timeout < 0
|
---|
Returns a string representation of the input SQL statement
sql
expressed in the underlying system's native SQL
syntax.
sql | the JDBC form of an SQL statement. |
---|
SQLException | if there is a problem accessing the database |
---|
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.
sql | the SQL statement |
---|---|
resultSetType | one of the following type specifiers: |
resultSetConcurrency | one of the following concurrency mode specifiers: |
CallableStatement
representing the
precompiled SQL statement. ResultSet
s emitted from this
CallableStatement
will satisfy the specified resultSetType
and resultSetConcurrency
values.SQLException | if a problem occurs accessing the database |
---|
Returns a new instance of CallableStatement
that may be used for
making stored procedure calls to the database.
sql | the SQL statement that calls the stored function |
---|
CallableStatement
representing the SQL
statement. ResultSet
s emitted from this CallableStatement
will default to type
TYPE_FORWARD_ONLY
and concurrency
CONCUR_READ_ONLY
.SQLException | if a problem occurs accessing the database. |
---|
Returns a new instance of CallableStatement
that may be used for
making stored procedure calls to the database. ResultSet
s created
from this CallableStatement
will have characteristics determined
by the specified type, concurrency and holdability arguments.
sql | the SQL statement |
---|---|
resultSetType | one of the following type specifiers: |
resultSetConcurrency | one of the following concurrency mode specifiers: |
resultSetHoldability | one of the following holdability mode specifiers: |
CallableStatement
representing the
precompiled SQL statement. ResultSet
s emitted from this
CallableStatement
will satisfy the specified resultSetType
, resultSetConcurrency
and resultSetHoldability
values.SQLException | if a problem occurs accessing the database. |
---|
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 handling 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
concurrency mode.
sql | the SQL statement. |
---|---|
columnNames | the names of the columns for which auto-generated keys should be made available. |
SQLException | if a problem occurs accessing the database. |
---|
Creates a PreparedStatement
that generates ResultSet
s
with the specified values of resultSetType
and resultSetConcurrency
.
sql | the SQL statement. It can contain one or more '?'
IN parameter placeholders. |
---|---|
resultSetType | one of the following type specifiers: |
resultSetConcurrency | one of the following concurrency mode specifiers: |
PreparedStatement
containing the SQL
statement sql
. ResultSet
s emitted from this
PreparedStatement
will satisfy the specified resultSetType
and resultSetConcurrency
values.SQLException | if a problem occurs accessing the database. |
---|
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. If
the driver does not support precompiled statements, the statement will
not reach the database server until it is executed. This distinction
determines the moment when SQLException
s get raised.
By default, ResultSet
s from the returned object will be
TYPE_FORWARD_ONLY
type with a
CONCUR_READ_ONLY
mode of concurrency.
sql | the SQL statement. |
---|
PreparedStatement
containing the supplied SQL
statement.SQLException | if there is a problem accessing the database. |
---|
Creates a default PreparedStatement
that can retrieve
automatically generated keys. Parameter autoGeneratedKeys
may be
used to tell the driver whether such keys should be made accessible.
This is only relevant when the sql
statement 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 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. If
the driver does not support precompiled statements, the statement will
not reach the database server until it is executed. This distinction
determines the moment when SQLException
s get raised.
By default, ResultSet
s from the returned object will be
TYPE_FORWARD_ONLY
type with a
CONCUR_READ_ONLY
mode of concurrency.
sql | the SQL statement. |
---|---|
autoGeneratedKeys | one of the following generated key options: |
PreparedStatement
instance representing the input
SQL statement.SQLException | if there is a problem accessing the database. |
---|
Creates a PreparedStatement
that generates ResultSet
s
with the specified type, concurrency and holdability
sql | the SQL statement. It can contain one or more '?' IN
parameter placeholders. |
---|---|
resultSetType | one of the following type specifiers: |
resultSetConcurrency | one of the following concurrency mode specifiers: |
resultSetHoldability | one of the following holdability mode specifiers: |
PreparedStatement
containing the SQL
statement sql
. ResultSet
s emitted from this
PreparedStatement
will satisfy the specified resultSetType
, resultSetConcurrency
and resultSetHoldability
values.SQLException | if a problem occurs accessing the database. |
---|
Creates a default PreparedStatement
that can retrieve the
auto-generated keys designated by a supplied array. If sql
is an
SQL INSERT
statement, the 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. If
the driver does not support precompiled statements, the statement will
not reach the database server until it is executed. This distinction
determines the moment when SQLException
s get raised.
By default, ResultSet
s from the returned object will be
TYPE_FORWARD_ONLY
type with a
CONCUR_READ_ONLY
concurrency mode.
sql | the SQL statement. |
---|---|
columnIndexes | the indexes of the columns for which auto-generated keys should be made available. |
SQLException | if a problem occurs accessing the database. |
---|
Releases the specified savepoint
from the present transaction. Once removed,
the Savepoint
is considered invalid and should not be referenced
further.
savepoint | the object targeted for removal. |
---|
SQLException | if there is a problem with accessing the database or if
savepoint is considered not valid in this
transaction.
|
---|
Rolls back all updates made so far in this transaction and relinquishes all acquired database locks. It is an error to invoke this operation when in auto-commit mode.
SQLException | if there is a problem with the database or if the method is called while in auto-commit mode of operation. |
---|
Undoes all changes made after the supplied Savepoint
object was
set. This method should only be used when auto-commit mode is disabled.
savepoint | the Savepoint to roll back to |
---|
SQLException | if there is a problem accessing the database. |
---|
Sets this connection's auto-commit mode on
or off
.
Putting a Connection into auto-commit mode means that all associated SQL
statements are run and committed as separate transactions.
By contrast, setting auto-commit 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 completed 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.
autoCommit | boolean indication of whether to put the target
connection into auto-commit mode (true ) or not (
false ). |
---|
SQLException | if there is a problem accessing the database. |
---|
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.
catalog | the catalog name to use. |
---|
SQLException | if there is a problem accessing the database. |
---|
Sets the client info property name
to value
. A value of null clears the
client info property.
SQLClientInfoException | if this connection is closed, or there's a problem setting the property. |
---|
Replaces all client info properties with the name/value pairs from properties
.
All existing properties are removed. If an exception is thrown, the resulting state of
this connection's client info properties is undefined.
SQLClientInfoException | if this connection is closed, or there's a problem setting a property. |
---|
Sets the holdability of the ResultSet
s created by this Connection.
holdability | one of the following holdability mode specifiers: |
---|
SQLException | if there is a problem accessing the database |
---|
Sets this connection to read-only mode.
This serves as a hint to the driver, which can enable database optimizations.
readOnly | true to set the Connection to read only mode. false disables read-only mode. |
---|
SQLException | if there is a problem accessing the database. |
---|
Creates a named Savepoint
in the current transaction.
name | the name to use for the new Savepoint . |
---|
Savepoint
object for this savepoint.SQLException | if there is a problem accessing the database. |
---|
Creates an unnamed Savepoint
in the current transaction.
Savepoint
object for this savepoint.SQLException | if there is a problem accessing the database. |
---|
Sets the transaction isolation level for this Connection.
If this method is called during a transaction, the results are implementation defined.
level | the new transaction isolation level to use from the following list of possible values: |
---|
SQLException | if there is a problem with the database or if the value of
level is not one of the expected constant values.
|
---|
Sets the TypeMap
for this connection. The input map
should contain mappings between complex Java and SQL types.
map | the new type map. |
---|
SQLException | if there is a problem accessing the database or if map is not an instance of Map .
|
---|