public interface Connection extends Wrapper, AutoCloseable
WHERE
clauseModifier and Type | Field and Description |
---|---|
static int |
TRANSACTION_NONE
A constant indicating that transactions are not supported.
|
static 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.
|
static 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:
dirty reads
non-repeatable reads
phantom reads
|
static int |
TRANSACTION_REPEATABLE_READ
A constant indicating that dirty reads and non-repeatable
reads are prevented but phantom reads can occur.
|
static int |
TRANSACTION_SERIALIZABLE
The constant that indicates that the following incidents are all
prevented (the opposite of
TRANSACTION_READ_UNCOMMITTED ):
dirty reads
non-repeatable reads
phantom reads
|
Modifier and Type | Method and Description |
---|---|
void |
clearWarnings()
Discards all warnings that may have arisen for this connection.
|
void |
close()
Causes the instant release of all database and driver connection
resources associated with this object.
|
void |
commit()
Commits all of the changes made since the last
commit or
rollback of the associated transaction. |
Array |
createArrayOf(String typeName,
Object[] elements)
Returns a new
Array containing the given elements . |
Blob |
createBlob()
Returns a new empty Blob.
|
Clob |
createClob()
Returns a new empty Clob.
|
NClob |
createNClob()
Returns a new empty NClob.
|
SQLXML |
createSQLXML()
Returns a new empty SQLXML.
|
Statement |
createStatement()
Returns a new instance of
Statement for issuing SQL commands to
the remote database. |
Statement |
createStatement(int resultSetType,
int resultSetConcurrency)
Returns a new instance of
Statement whose associated ResultSet s have the characteristics specified in the type and
concurrency arguments. |
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. |
Struct |
createStruct(String typeName,
Object[] attributes)
Returns a new
Struct containing the given attributes . |
boolean |
getAutoCommit()
Returns a
boolean indicating whether or not this connection is in
the auto-commit operating mode. |
String |
getCatalog()
Gets this
Connection object's current catalog name. |
Properties |
getClientInfo()
Returns a
Properties object containing all client info properties. |
String |
getClientInfo(String name)
Returns the value corresponding to the given client info property, or null if unset.
|
int |
getHoldability()
Returns the holdability property that any
ResultSet produced by
this instance will have. |
DatabaseMetaData |
getMetaData()
Gets the metadata about the database referenced by this connection.
|
int |
getTransactionIsolation()
Returns the transaction isolation level for this connection.
|
Map<String,Class<?>> |
getTypeMap()
Returns the type mapping associated with this
Connection object. |
SQLWarning |
getWarnings()
Gets the first instance of any
SQLWarning objects that may have
been created in the use of this connection. |
boolean |
isClosed()
Returns a
boolean indicating whether or not this connection is in
the closed state. |
boolean |
isReadOnly()
Returns a
boolean indicating whether or not this connection is
currently in the read-only state. |
boolean |
isValid(int timeout)
Returns true if this connection is still open and valid, false otherwise.
|
String |
nativeSQL(String sql)
Returns a string representation of the input SQL statement
sql expressed in the underlying system's native SQL
syntax. |
CallableStatement |
prepareCall(String sql)
Returns a new instance of
CallableStatement that may be used for
making stored procedure calls to the database. |
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. |
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. |
PreparedStatement |
prepareStatement(String sql)
Returns a new instance of
PreparedStatement that may be used any
number of times to execute parameterized requests on the database server. |
PreparedStatement |
prepareStatement(String sql,
int autoGeneratedKeys)
Creates a default
PreparedStatement that can retrieve
automatically generated keys. |
PreparedStatement |
prepareStatement(String sql,
int[] columnIndexes)
Creates a default
PreparedStatement that can retrieve the
auto-generated keys designated by a supplied array. |
PreparedStatement |
prepareStatement(String sql,
int resultSetType,
int resultSetConcurrency)
Creates a
PreparedStatement that generates ResultSet s
with the specified values of resultSetType and resultSetConcurrency . |
PreparedStatement |
prepareStatement(String sql,
int resultSetType,
int resultSetConcurrency,
int resultSetHoldability)
Creates a
PreparedStatement that generates ResultSet s
with the specified type, concurrency and holdability |
PreparedStatement |
prepareStatement(String sql,
String[] columnNames)
Creates a default
PreparedStatement that can retrieve the
auto-generated keys designated by a supplied array. |
void |
releaseSavepoint(Savepoint savepoint)
Releases the specified
savepoint from the present transaction. |
void |
rollback()
Rolls back all updates made so far in this transaction and
relinquishes all acquired database locks.
|
void |
rollback(Savepoint savepoint)
Undoes all changes made after the supplied
Savepoint object was
set. |
void |
setAutoCommit(boolean autoCommit)
Sets this connection's auto-commit mode
on or off . |
void |
setCatalog(String catalog)
Sets the catalog name for this connection.
|
void |
setClientInfo(Properties properties)
Replaces all client info properties with the name/value pairs from
properties . |
void |
setClientInfo(String name,
String value)
Sets the client info property
name to value . |
void |
setHoldability(int holdability)
Sets the holdability of the
ResultSet s created by this Connection. |
void |
setReadOnly(boolean readOnly)
Sets this connection to read-only mode.
|
Savepoint |
setSavepoint()
Creates an unnamed
Savepoint in the current transaction. |
Savepoint |
setSavepoint(String name)
Creates a named
Savepoint in the current transaction. |
void |
setTransactionIsolation(int level)
Sets the transaction isolation level for this Connection.
|
void |
setTypeMap(Map<String,Class<?>> map)
Sets the
TypeMap for this connection. |
isWrapperFor, unwrap
static final int TRANSACTION_NONE
static final int TRANSACTION_READ_COMMITTED
static final int TRANSACTION_READ_UNCOMMITTED
static final int TRANSACTION_REPEATABLE_READ
static final int TRANSACTION_SERIALIZABLE
TRANSACTION_READ_UNCOMMITTED
):
void clearWarnings() throws SQLException
getWarnings()
will return null
up until a new warning condition occurs.SQLException
- if there is a problem accessing the database.void close() throws SQLException
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.
close
in interface AutoCloseable
SQLException
- if there is a problem accessing the database.void commit() throws SQLException
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.Statement createStatement() throws SQLException
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.ResultSet
Statement createStatement(int resultSetType, int resultSetConcurrency) throws SQLException
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 databaseStatement createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
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.boolean getAutoCommit() throws SQLException
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.String getCatalog() throws SQLException
Connection
object's current catalog name.null
if there is no catalog
name.SQLException
- if there is a problem accessing the database.int getHoldability() throws SQLException
ResultSet
produced by
this instance will have.SQLException
- if there is a problem accessing the a database.DatabaseMetaData getMetaData() throws SQLException
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.int getTransactionIsolation() throws SQLException
SQLException
- if there is a problem accessing the database.TRANSACTION_NONE
,
TRANSACTION_READ_COMMITTED
,
TRANSACTION_READ_UNCOMMITTED
,
TRANSACTION_REPEATABLE_READ
,
TRANSACTION_SERIALIZABLE
Map<String,Class<?>> getTypeMap() throws SQLException
Connection
object.
The type mapping must be set on the application level.java.util.Map
.SQLException
- if there is a problem accessing the database.SQLWarning getWarnings() throws SQLException
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 SQLWarning.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.boolean isClosed() throws SQLException
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.boolean isReadOnly() throws SQLException
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.String nativeSQL(String sql) throws SQLException
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 databaseCallableStatement prepareCall(String sql) throws SQLException
CallableStatement
that may be used for
making stored procedure calls to the database.sql
- the SQL statement that calls the stored functionCallableStatement
representing the SQL
statement. ResultSet
s emitted from this CallableStatement
will default to type
ResultSet.TYPE_FORWARD_ONLY
and concurrency
ResultSet.CONCUR_READ_ONLY
.SQLException
- if a problem occurs accessing the database.CallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
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 statementresultSetType
- 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 databaseCallableStatement prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
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 statementresultSetType
- 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.PreparedStatement prepareStatement(String sql) throws SQLException
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
ResultSet.TYPE_FORWARD_ONLY
type with a
ResultSet.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.PreparedStatement prepareStatement(String sql, int autoGeneratedKeys) throws SQLException
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
ResultSet.TYPE_FORWARD_ONLY
type with a
ResultSet.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.PreparedStatement prepareStatement(String sql, int[] columnIndexes) throws SQLException
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
ResultSet.TYPE_FORWARD_ONLY
type with a
ResultSet.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.PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency) throws SQLException
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.PreparedStatement prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQLException
PreparedStatement
that generates ResultSet
s
with the specified type, concurrency and holdabilitysql
- 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.PreparedStatement prepareStatement(String sql, String[] columnNames) throws SQLException
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
ResultSet.TYPE_FORWARD_ONLY
type with a
ResultSet.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.void releaseSavepoint(Savepoint savepoint) throws SQLException
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.void rollback() throws SQLException
SQLException
- if there is a problem with the database or if the method is
called while in auto-commit mode of operation.void rollback(Savepoint savepoint) throws SQLException
Savepoint
object was
set. This method should only be used when auto-commit mode is disabled.savepoint
- the Savepoint to roll back toSQLException
- if there is a problem accessing the database.void setAutoCommit(boolean autoCommit) throws SQLException
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.void setCatalog(String catalog) throws SQLException
catalog
- the catalog name to use.SQLException
- if there is a problem accessing the database.void setHoldability(int holdability) throws SQLException
ResultSet
s created by this Connection.holdability
- one of the following holdability mode specifiers:
SQLException
- if there is a problem accessing the databasevoid setReadOnly(boolean readOnly) throws SQLException
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.Savepoint setSavepoint() throws SQLException
Savepoint
in the current transaction.Savepoint
object for this savepoint.SQLException
- if there is a problem accessing the database.Savepoint setSavepoint(String name) throws SQLException
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.void setTransactionIsolation(int level) throws SQLException
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.void setTypeMap(Map<String,Class<?>> map) throws SQLException
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
.Clob createClob() throws SQLException
SQLException
- if this connection is closed, or there's a problem creating a new clob.Blob createBlob() throws SQLException
SQLException
- if this connection is closed, or there's a problem creating a new blob.NClob createNClob() throws SQLException
SQLException
- if this connection is closed, or there's a problem creating a new nclob.SQLXML createSQLXML() throws SQLException
SQLException
- if this connection is closed, or there's a problem creating a new XML.boolean isValid(int timeout) throws SQLException
timeout
- number of seconds to wait for a response before giving up and returning false,
0 to wait foreverSQLException
- if timeout < 0
void setClientInfo(String name, String value) throws SQLClientInfoException
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.void setClientInfo(Properties properties) throws SQLClientInfoException
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.String getClientInfo(String name) throws SQLException
SQLClientInfoException
- if this connection is closed, or there's a problem getting
the property.SQLException
Properties getClientInfo() throws SQLException
Properties
object containing all client info properties.SQLClientInfoException
- if this connection is closed, or there's a problem getting
a property.SQLException
Array createArrayOf(String typeName, Object[] elements) throws SQLException
Array
containing the given elements
.typeName
- the SQL name of the type of the array elementsSQLClientInfoException
- if this connection is closed, or there's a problem creating
the array.SQLException
Struct createStruct(String typeName, Object[] attributes) throws SQLException
Struct
containing the given attributes
.typeName
- the SQL name of the type of the struct attributesSQLClientInfoException
- if this connection is closed, or there's a problem creating
the array.SQLException