APIdia Launch Partner
Top Description Fields Methods
java.sql

public Interface Connection

extends Wrapper, AutoCloseable
Imports
java.util.Properties, .Map, java.util.concurrent.Executor

A connection (session) with a specific database. SQL statements are executed and results are returned within the context of a connection.

A Connection object's database is able to provide information describing its tables, its supported SQL grammar, its stored procedures, the capabilities of this connection, and so on. This information is obtained with the getMetaData method.

Note

When configuring a Connection, JDBC applications should use the appropriate Connection method such as setAutoCommit or setTransactionIsolation. Applications should not invoke SQL commands directly to change the connection's configuration when there is a JDBC method available. By default, a Connection object is in auto-commit mode, which means that it automatically commits changes after executing each statement. If auto-commit mode has been disabled, the method commit must be called explicitly in order to commit changes; otherwise, database changes will not be saved.

A new Connection object created using the JDBC 2.1 core API has an initially empty type map associated with it. A user may enter a custom mapping for a UDT in this type map. When a UDT is retrieved from a data source with the method ResultSet.getObject, the getObject method will check the connection's type map to see if there is an entry for that UDT. If so, the getObject method will map the UDT to the class indicated. If there is no entry, the UDT will be mapped using the standard mapping.

A user may create a new type map, which is a java.util.Map object, make an entry in it, and pass it to the java.sql methods that can perform custom mapping. In this case, the method will use the given type map instead of the one associated with the connection.

For example, the following code fragment specifies that the SQL type ATHLETES will be mapped to the class Athletes in the Java programming language. The code fragment retrieves the type map for the Connection object con, inserts the entry into it, and then sets the type map with the new entry as the connection's type map. 

     java.util.Map map = con.getTypeMap();
     map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
     con.setTypeMap(map);
Since
1.1
See Also
DriverManager#getConnection(String), Statement, ResultSet, DatabaseMetaData

Field Summary

Modifier and TypeField and Description
public static final int
TRANSACTION_NONE

A constant indicating that transactions are not supported.

public static final int
TRANSACTION_READ_COMMITTED

A constant indicating that dirty reads are prevented; non-repeatable reads and phantom reads can occur.

public static final int
TRANSACTION_READ_UNCOMMITTED

A constant indicating that dirty reads, non-repeatable reads and phantom reads can occur.

public static final int
TRANSACTION_REPEATABLE_READ

A constant indicating that dirty reads and non-repeatable reads are prevented; phantom reads can occur.

public static final int
TRANSACTION_SERIALIZABLE

A constant indicating that dirty reads, non-repeatable reads and phantom reads are prevented.

Method Summary

Modifier and TypeMethod and Description
public void
abort(Executor
The Executor implementation which will be used by abort.
executor)

Terminates an open connection.

public default void
beginRequest()

Hints to the driver that a request, an independent unit of work, is beginning on this connection.

public void
clearWarnings()

Clears all warnings reported for this Connection object.

public void
close()

Redeclares java.lang.AutoCloseable.close.

Releases this Connection object's database and JDBC resources immediately instead of waiting for them to be automatically released.

public void
commit()

Makes all changes made since the previous commit/rollback permanent and releases any database locks currently held by this Connection object.

public Array

Returns:

an Array object whose elements map to the specified SQL type
createArrayOf(String
the SQL name of the type the elements of the array map to. The typeName is a database-specific name which may be the name of a built-in type, a user-defined type or a standard SQL type supported by this database. This is the value returned by Array.getBaseTypeName
typeName, Object[]
the elements that populate the returned object
elements)

Factory method for creating Array objects.

public Blob

Returns:

An object that implements the Blob interface
createBlob()

Constructs an object that implements the Blob interface.

public Clob

Returns:

An object that implements the Clob interface
createClob()

Constructs an object that implements the Clob interface.

public NClob

Returns:

An object that implements the NClob interface
createNClob()

Constructs an object that implements the NClob interface.

public SQLXML

Returns:

An object that implements the SQLXML interface
createSQLXML()

Constructs an object that implements the SQLXML interface.

public Statement

Returns:

a new default Statement object
createStatement()

Creates a Statement object for sending SQL statements to the database.

public Statement

Returns:

a new Statement object that will generate ResultSet objects with the given type and concurrency
createStatement(int
a result set type; one of ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
resultSetType, int
a concurrency type; one of ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
resultSetConcurrency)

Creates a Statement object that will generate ResultSet objects with the given type and concurrency.

public Statement

Returns:

a new Statement object that will generate ResultSet objects with the given type, concurrency, and holdability
createStatement(int
one of the following ResultSet constants: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
resultSetType, int
one of the following ResultSet constants: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
resultSetConcurrency, int
one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
resultSetHoldability)

Creates a Statement object that will generate ResultSet objects with the given type, concurrency, and holdability.

public Struct

Returns:

a Struct object that maps to the given SQL type and is populated with the given attributes
createStruct(String
the SQL type name of the SQL structured type that this Struct object maps to. The typeName is the name of a user-defined type that has been defined for this database. It is the value returned by Struct.getSQLTypeName.
typeName, Object[]
the attributes that populate the returned object
attributes)

Factory method for creating Struct objects.

public default void
endRequest()

Hints to the driver that a request, an independent unit of work, has completed.

public default String

Returns:

A simple SQL identifier or a delimited identifier
enquoteIdentifier(String
a SQL identifier
identifier, boolean
indicates if a simple SQL identifier should be returned as a delimited identifier
alwaysDelimit)

Returns a simple SQL identifier or a delimited identifier.

public default String

Returns:

A string enclosed by single quotes with every single quote converted to two single quotes
enquoteLiteral(String
a character string
val)

Returns a String enclosed in single quotes.

public default String

Returns:

the result of replacing every single quote character in the argument by two single quote characters where this entire result is then prefixed with 'N'.
enquoteNCharLiteral(String
a character string
val)

Returns a String representing a National Character Set Literal enclosed in single quotes and prefixed with a upper case letter N.

public boolean

Returns:

the current state of this Connection object's auto-commit mode
getAutoCommit()

Retrieves the current auto-commit mode for this Connection object.

public String

Returns:

the current catalog name or null if there is none
getCatalog()

Retrieves this Connection object's current catalog name.

public String

Returns:

The value of the client info property specified
getClientInfo(String
The name of the client info property to retrieve
name)

Returns the value of the client info property specified by name.

public Properties

Returns:

A Properties object that contains the name and current value of each of the client info properties supported by the driver.
getClientInfo()

Returns a list containing the name and current value of each client info property supported by the driver.

public int

Returns:

the holdability, one of ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
getHoldability()

Retrieves the current holdability of ResultSet objects created using this Connection object.

public DatabaseMetaData

Returns:

a DatabaseMetaData object for this Connection object
getMetaData()

Retrieves a DatabaseMetaData object that contains metadata about the database to which this Connection object represents a connection.

public int

Returns:

the current timeout limit in milliseconds; zero means there is no limit
getNetworkTimeout()

Retrieves the number of milliseconds the driver will wait for a database request to complete.

public String

Returns:

the current schema name or null if there is none
getSchema()

Retrieves this Connection object's current schema name.

public int

Returns:

the current transaction isolation level, which will be one of the following constants: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, Connection.TRANSACTION_SERIALIZABLE, or Connection.TRANSACTION_NONE.
getTransactionIsolation()

Retrieves this Connection object's current transaction isolation level.

public Map<String, Class<?>>

Returns:

the java.util.Map object associated with this Connection object
getTypeMap()

Retrieves the Map object associated with this Connection object.

public SQLWarning

Returns:

the first SQLWarning object or null if there are none
getWarnings()

Retrieves the first warning reported by calls on this Connection object.

public boolean

Returns:

true if this Connection object is closed; false if it is still open
isClosed()

Retrieves whether this Connection object has been closed.

public boolean

Returns:

true if this Connection object is read-only; false otherwise
isReadOnly()

Retrieves whether this Connection object is in read-only mode.

public default boolean

Returns:

true if a simple SQL identifier, false otherwise
isSimpleIdentifier(String
a SQL identifier
identifier)

Returns whether identifier is a simple SQL identifier.

public boolean

Returns:

true if the connection is valid, false otherwise
isValid(int
The time in seconds to wait for the database operation used to validate the connection to complete. If the timeout period expires before the operationcompletes, this method returns false. A value of 0 indicates a timeout is not applied to the database operation.
timeout)

Returns true if the connection has not been closed and is still valid.

public String

Returns:

the native form of this statement
nativeSQL(String
an SQL statement that may contain one or more '?' parameter placeholders
sql)

Converts the given SQL statement into the system's native SQL grammar.

public CallableStatement

Returns:

a new default CallableStatement object containing the pre-compiled SQL statement
prepareCall(String
an SQL statement that may contain one or more '?' parameter placeholders. Typically this statement is specified using JDBC call escape syntax.
sql)

Creates a CallableStatement object for calling database stored procedures.

public CallableStatement

Returns:

a new CallableStatement object containing the pre-compiled SQL statement that will produce ResultSet objects with the given type and concurrency
prepareCall(String
a String object that is the SQL statement to be sent to the database; may contain on or more '?' parameters
sql, int
a result set type; one of ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
resultSetType, int
a concurrency type; one of ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
resultSetConcurrency)

Creates a CallableStatement object that will generate ResultSet objects with the given type and concurrency.

public CallableStatement

Returns:

a new CallableStatement object, containing the pre-compiled SQL statement, that will generate ResultSet objects with the given type, concurrency, and holdability
prepareCall(String
a String object that is the SQL statement to be sent to the database; may contain on or more '?' parameters
sql, int
one of the following ResultSet constants: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
resultSetType, int
one of the following ResultSet constants: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
resultSetConcurrency, int
one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
resultSetHoldability)

Creates a CallableStatement object that will generate ResultSet objects with the given type and concurrency.

public PreparedStatement

Returns:

a new default PreparedStatement object containing the pre-compiled SQL statement
prepareStatement(String
an SQL statement that may contain one or more '?' IN parameter placeholders
sql)

Creates a PreparedStatement object for sending parameterized SQL statements to the database.

public PreparedStatement

Returns:

a new PreparedStatement object containing the pre-compiled SQL statement that will produce ResultSet objects with the given type and concurrency
prepareStatement(String
a String object that is the SQL statement to be sent to the database; may contain one or more '?' IN parameters
sql, int
a result set type; one of ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
resultSetType, int
a concurrency type; one of ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
resultSetConcurrency)

Creates a PreparedStatement object that will generate ResultSet objects with the given type and concurrency.

public PreparedStatement

Returns:

a new PreparedStatement object, containing the pre-compiled SQL statement, that will generate ResultSet objects with the given type, concurrency, and holdability
prepareStatement(String
a String object that is the SQL statement to be sent to the database; may contain one or more '?' IN parameters
sql, int
one of the following ResultSet constants: ResultSet.TYPE_FORWARD_ONLY, ResultSet.TYPE_SCROLL_INSENSITIVE, or ResultSet.TYPE_SCROLL_SENSITIVE
resultSetType, int
one of the following ResultSet constants: ResultSet.CONCUR_READ_ONLY or ResultSet.CONCUR_UPDATABLE
resultSetConcurrency, int
one of the following ResultSet constants: ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
resultSetHoldability)

Creates a PreparedStatement object that will generate ResultSet objects with the given type, concurrency, and holdability.

public PreparedStatement

Returns:

a new PreparedStatement object, containing the pre-compiled SQL statement, that will have the capability of returning auto-generated keys
prepareStatement(String
an SQL statement that may contain one or more '?' IN parameter placeholders
sql, int
a flag indicating whether auto-generated keys should be returned; one of Statement.RETURN_GENERATED_KEYS or Statement.NO_GENERATED_KEYS
autoGeneratedKeys)

Creates a default PreparedStatement object that has the capability to retrieve auto-generated keys.

public PreparedStatement

Returns:

a new PreparedStatement object, containing the pre-compiled statement, that is capable of returning the auto-generated keys designated by the given array of column indexes
prepareStatement(String
an SQL statement that may contain one or more '?' IN parameter placeholders
sql, int[]
an array of column indexes indicating the columns that should be returned from the inserted row or rows
columnIndexes)

Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array.

public PreparedStatement

Returns:

a new PreparedStatement object, containing the pre-compiled statement, that is capable of returning the auto-generated keys designated by the given array of column names
prepareStatement(String
an SQL statement that may contain one or more '?' IN parameter placeholders
sql, String[]
an array of column names indicating the columns that should be returned from the inserted row or rows
columnNames)

Creates a default PreparedStatement object capable of returning the auto-generated keys designated by the given array.

public void
releaseSavepoint(Savepoint
the Savepoint object to be removed
savepoint)

Removes the specified Savepoint and subsequent Savepoint objects from the current transaction.

public void
rollback()

Undoes all changes made in the current transaction and releases any database locks currently held by this Connection object.

public void
rollback(Savepoint
the Savepoint object to roll back to
savepoint)

Undoes all changes made after the given Savepoint object was set.

public void
setAutoCommit(boolean
true to enable auto-commit mode; false to disable it
autoCommit)

Sets this connection's auto-commit mode to the given state.

public void
setCatalog(String
the name of a catalog (subspace in this Connection object's database) in which to work
catalog)

Sets the given catalog name in order to select a subspace of this Connection object's database in which to work.

public void
setClientInfo(String
The name of the client info property to set
name, String
The value to set the client info property to. If the value is null, the current value of the specified property is cleared.
value)

Sets the value of the client info property specified by name to the value specified by value.

public void
setClientInfo(Properties
the list of client info properties to set
properties)

Sets the value of the connection's client info properties.

public void
setHoldability(int
a ResultSet holdability constant; one of ResultSet.HOLD_CURSORS_OVER_COMMIT or ResultSet.CLOSE_CURSORS_AT_COMMIT
holdability)

Changes the default holdability of ResultSet objects created using this Connection object to the given holdability.

public void
setNetworkTimeout(Executor
The Executor implementation which will be used by setNetworkTimeout.
executor, int
The time in milliseconds to wait for the database operation to complete. If the JDBC driver does not support milliseconds, the JDBC driver will round the value up to the nearest second. If the timeout period expires before the operation completes, a SQLException will be thrown. A value of 0 indicates that there is not timeout for database operations.
milliseconds)

Sets the maximum period a Connection or objects created from the Connection will wait for the database to reply to any one request.

public void
setReadOnly(boolean
true enables read-only mode; false disables it
readOnly)

Puts this connection in read-only mode as a hint to the driver to enable database optimizations.

public Savepoint

Returns:

the new Savepoint object
setSavepoint()

Creates an unnamed savepoint in the current transaction and returns the new Savepoint object that represents it.

public Savepoint

Returns:

the new Savepoint object
setSavepoint(String
a String containing the name of the savepoint
name)

Creates a savepoint with the given name in the current transaction and returns the new Savepoint object that represents it.

public void
setSchema(String
the name of a schema in which to work
schema)

Sets the given schema name to access.

public default void
setShardingKey(ShardingKey
the sharding key to set on this connection. The sharding key may be null
shardingKey, ShardingKey
the super sharding key to set on this connection. The super sharding key may be null
superShardingKey)

Specifies a shardingKey and superShardingKey to use with this Connection

public default void
setShardingKey(ShardingKey
the sharding key to set on this connection. The sharding key may be null
shardingKey)

Specifies a shardingKey to use with this Connection

public default boolean

Returns:

true if the connection is valid and the sharding keys are valid and set on this connection; false if the sharding keys are not valid or the timeout period expires before the operation completes.
setShardingKeyIfValid(ShardingKey
the sharding key to be validated against this connection. The sharding key may be null
shardingKey, ShardingKey
the super sharding key to be validated against this connection. The super sharding key may be null.
superShardingKey, int
time in seconds before which the validation process is expected to be completed, otherwise the validation process is aborted. A value of 0 indicates the validation process will not time out.
timeout)

Sets and validates the sharding keys for this connection.

public default boolean

Returns:

true if the connection is valid and the sharding key is valid to be set on this connection; false if the sharding key is not valid or the timeout period expires before the operation completes.
setShardingKeyIfValid(ShardingKey
the sharding key to be validated against this connection. The sharding key may be null
shardingKey, int
time in seconds before which the validation process is expected to be completed,else the validation process is aborted. A value of 0 indicates the validation process will not time out.
timeout)

Sets and validates the sharding key for this connection.

public void
setTransactionIsolation(int
one of the following Connection constants: Connection.TRANSACTION_READ_UNCOMMITTED, Connection.TRANSACTION_READ_COMMITTED, Connection.TRANSACTION_REPEATABLE_READ, or Connection.TRANSACTION_SERIALIZABLE. (Note that Connection.TRANSACTION_NONE cannot be used because it specifies that transactions are not supported.)
level)

Attempts to change the transaction isolation level for this Connection object to the one given.

public void
setTypeMap(Map<String, Class<?>>
the java.util.Map object to install as the replacement for this Connection object's default type map
map)

Installs the given TypeMap object as the type map for this Connection object.

Inherited from java.sql.Wrapper:
isWrapperForunwrap