| 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 clause| Constants | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 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 ResultSets have the characteristics specified in the type and
concurrency arguments. | |||||||||||
Returns a new instance of
Statement whose associated
ResultSets 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
PreparedStatement that generates ResultSets
with the specified values of resultSetType and resultSetConcurrency. | |||||||||||
Creates a default
PreparedStatement that can retrieve the
auto-generated keys designated by a supplied array. | |||||||||||
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 ResultSets
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
ResultSets 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.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 ResultSets 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
ResultSets 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
ResultSets 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 ResultSets 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. ResultSets 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. ResultSets 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. ResultSets 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. ResultSets 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. ResultSets emitted from this
CallableStatement will satisfy the specified resultSetType, resultSetConcurrency and resultSetHoldability values.| SQLException | if a problem occurs accessing the database. |
|---|
Creates a PreparedStatement that generates ResultSets
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. ResultSets emitted from this
PreparedStatement will satisfy the specified resultSetType and resultSetConcurrency 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. |
|---|
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 SQLExceptions get raised.
By default, ResultSets 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 SQLExceptions get raised.
By default, ResultSets 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 ResultSets
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. ResultSets 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 SQLExceptions 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. |
|---|---|
| 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
ResultSets 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 ResultSets 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.
|
|---|