模块 java.sql

包 java.sql

接口 Connection

所有父级接口：

AutoCloseable , Wrapper

public interface Connection extends Wrapper , AutoCloseable 
      

与特定数据库的连接（会话）。在连接上下文中执行 SQL 语句并返回结果。

Connection 对象的数据库能够提供描述其表、支持的 SQL 语法、存储过程、此连接的功能等的信息。此信息是使用 getMetaData 方法获得的。

笔记：配置 Connection 时，JDBC 应用程序应使用适当的 Connection 方法，例如 setAutoCommit 或 setTransactionIsolation。当有可用的 JDBC 方法时，应用程序不应直接调用 SQL 命令来更改连接的配置。默认情况下，Connection 对象处于自动提交模式，这意味着它会在执行每个语句后自动提交更改。如果禁用了自动提交模式，则必须显式调用方法 commit 才能提交更改；否则，数据库更改将不会被保存。

使用 JDBC 2.1 核心 API 创建的新 Connection 对象具有与其关联的最初为空的类型映射。用户可以在此类型map中为 UDT 输入自定义映射。当使用方法 ResultSet.getObject 从数据源检索 UDT 时， getObject 方法将检查连接的类型映射以查看是否存在该 UDT 的条目。如果是这样，getObject 方法会将 UDT 映射到指示的类。如果没有条目，UDT 将使用标准映射进行映射。

用户可以创建一个新的类型映射，它是一个 java.util.Map 对象，在其中创建一个条目，并将其传递给可以执行自定义映射的 java.sql 方法。在这种情况下，该方法将使用给定的类型映射而不是与连接关联的类型映射。

例如，以下代码片段指定 SQL 类型ATHLETES 将映射到 Java 编程语言中的类 Athletes。代码片段检索 Connection 对象 con 的类型映射，将条目插入其中，然后将具有新条目的类型映射设置为连接的类型映射。

   java.util.Map map = con.getTypeMap();
   map.put("mySchemaName.ATHLETES", Class.forName("Athletes"));
   con.setTypeMap(map);
 

自从：

1.1

参见：

• DriverManager.getConnection(java.lang.String, java.util.Properties)
• Statement
• ResultSet
• DatabaseMetaData

字段摘要

字段

修饰符和类型	Field	描述
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	一个常量，表示防止脏读、不可重复读和幻读。

方法总结

修饰符和类型	方法	描述
void	abort(Executor executor)	终止打开的连接。
default void	beginRequest()	向驱动程序提示一个请求，一个独立的工作单元，正在这个连接上开始。
void	clearWarnings()	清除为此 Connection 对象报告的所有警告。
void	close()	立即释放此 Connection 对象的数据库和 JDBC 资源，而不是等待它们自动释放。
void	commit()	使自上次提交/回滚以来所做的所有更改永久化，并释放当前由该 Connection 对象持有的所有数据库锁。
Array	createArrayOf(String typeName, Object[] elements)	用于创建 Array 对象的工厂方法。
Blob	createBlob()	构造一个实现 Blob 接口的对象。
Clob	createClob()	构造一个实现 Clob 接口的对象。
NClob	createNClob()	构造一个实现 NClob 接口的对象。
SQLXML	createSQLXML()	构造一个实现 SQLXML 接口的对象。
Statement	createStatement()	创建一个 Statement 对象，用于将 SQL 语句发送到数据库。
Statement	createStatement(int resultSetType, int resultSetConcurrency)	创建一个 Statement 对象，它将生成具有给定类型和并发性的 ResultSet 对象。
Statement	createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability)	创建一个 Statement 对象，该对象将生成具有给定类型、并发性和可持有性的 ResultSet 对象。
Struct	createStruct(String typeName, Object[] attributes)	用于创建 Struct 对象的工厂方法。
default void	endRequest()	向驱动程序提示请求（一个独立的工作单元）已完成。
boolean	getAutoCommit()	检索此 Connection 对象的当前自动提交模式。
String	getCatalog()	检索此 Connection 对象的当前目录名称。
Properties	getClientInfo()	返回一个列表，其中包含驱动程序支持的每个客户端信息属性的名称和当前值。
String	getClientInfo(String name)	返回名称指定的客户端信息属性的值。
int	getHoldability()	检索使用此 Connection 对象创建的 ResultSet 对象的当前可持有性。
DatabaseMetaData	getMetaData()	检索一个 DatabaseMetaData 对象，该对象包含有关此 Connection 对象表示连接的数据库的元数据。
int	getNetworkTimeout()	检索驱动程序将等待数据库请求完成的毫秒数。
String	getSchema()	检索此 Connection 对象的当前架构名称。
int	getTransactionIsolation()	检索此 Connection 对象的当前事务隔离级别。
Map<String,Class<?>>	getTypeMap()	检索与此 Connection 对象关联的 Map 对象。
SQLWarning	getWarnings()	检索对此 Connection 对象的调用报告的第一个警告。
boolean	isClosed()	检索此 Connection 对象是否已关闭。
boolean	isReadOnly()	检索此 Connection 对象是否处于只读模式。
boolean	isValid(int timeout)	如果连接尚未关闭且仍然有效，则返回 true。
String	nativeSQL(String sql)	将给定的 SQL 语句转换为系统的本机 SQL 语法。
CallableStatement	prepareCall(String sql)	创建用于调用数据库存储过程的 CallableStatement 对象。
CallableStatement	prepareCall(String sql, int resultSetType, int resultSetConcurrency)	创建一个 CallableStatement 对象，它将生成具有给定类型和并发性的 ResultSet 对象。
CallableStatement	prepareCall(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)	创建一个 CallableStatement 对象，它将生成具有给定类型和并发性的 ResultSet 对象。
PreparedStatement	prepareStatement(String sql)	创建一个 PreparedStatement 对象，用于将参数化 SQL 语句发送到数据库。
PreparedStatement	prepareStatement(String sql, int autoGeneratedKeys)	创建一个默认的 PreparedStatement 对象，该对象能够检索自动生成的密钥。
PreparedStatement	prepareStatement(String sql, int[] columnIndexes)	创建一个默认的 PreparedStatement 对象，能够返回由给定数组指定的自动生成的键。
PreparedStatement	prepareStatement(String sql, int resultSetType, int resultSetConcurrency)	创建一个 PreparedStatement 对象，它将生成具有给定类型和并发性的 ResultSet 对象。
PreparedStatement	prepareStatement(String sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability)	创建一个 PreparedStatement 对象，该对象将生成具有给定类型、并发性和可持有性的 ResultSet 对象。
PreparedStatement	prepareStatement(String sql, String[] columnNames)	创建一个默认的 PreparedStatement 对象，能够返回由给定数组指定的自动生成的键。
void	releaseSavepoint(Savepoint savepoint)	从当前事务中删除指定的 Savepoint 和后续的 Savepoint 对象。
void	rollback()	撤消当前事务中所做的所有更改并释放此 Connection 对象当前持有的所有数据库锁。
void	rollback(Savepoint savepoint)	撤消设置给定 Savepoint 对象后所做的所有更改。
void	setAutoCommit(boolean autoCommit)	将此连接的自动提交模式设置为给定状态。
void	setCatalog(String catalog)	设置给定的目录名称，以便选择此 Connection 对象的数据库的子空间在其中工作。
void	setClientInfo(String name, String value)	将名称指定的客户端信息属性的值设置为值指定的值。
void	setClientInfo(Properties properties)	设置连接的客户端信息属性的值。
void	setHoldability(int holdability)	将使用此 Connection 对象创建的 ResultSet 对象的默认可持有性更改为给定的可持有性。
void	setNetworkTimeout(Executor executor, int milliseconds)	设置 Connection 或从 Connection 创建的对象将等待数据库回复任何一个请求的最长期限。
void	setReadOnly(boolean readOnly)	将此连接置于只读模式，以提示驱动程序启用数据库优化。
Savepoint	setSavepoint()	在当前事务中创建一个未命名的保存点并返回代表它的新 Savepoint 对象。
Savepoint	setSavepoint(String name)	在当前事务中创建一个具有给定名称的保存点并返回表示它的新 Savepoint 对象。
void	setSchema(String schema)	设置要访问的给定模式名称。
default void	setShardingKey(ShardingKey shardingKey)	指定与此连接一起使用的 shardingKey
default void	setShardingKey(ShardingKey shardingKey, ShardingKey superShardingKey)	指定与此连接一起使用的 shardingKey 和 superShardingKey
default boolean	setShardingKeyIfValid(ShardingKey shardingKey, int timeout)	设置并验证此连接的分片键。
default boolean	setShardingKeyIfValid(ShardingKey shardingKey, ShardingKey superShardingKey, int timeout)	设置并验证此连接的分片键。
void	setTransactionIsolation(int level)	尝试将此 Connection 对象的事务隔离级别更改为给定级别。
void	setTypeMap(Map<String,Class<?>> map)	安装给定的 TypeMap 对象作为此 Connection 对象的类型映射。

在接口 java.sql.Wrapper 中声明的方法

isWrapperFor, unwrap

字段详细信息

TRANSACTION_NONE

static final int TRANSACTION_NONE
            

一个常量，表示不支持事务。

参见：

• 常量字段值

TRANSACTION_READ_UNCOMMITTED

static final int TRANSACTION_READ_UNCOMMITTED
            

一个常量，指示可能发生脏读、不可重复读和幻读。此级别允许由一个事务更改的行在提交该行的任何更改之前由另一个事务读取（“脏读”）。如果任何更改被回滚，则第二个事务将检索到无效行。

参见：

• 常量字段值

TRANSACTION_READ_COMMITTED

static final int TRANSACTION_READ_COMMITTED
            

表示防止脏读的常量；可能会出现不可重复读取和幻读。此级别仅禁止事务读取其中包含未提交更改的行。

参见：

• 常量字段值

TRANSACTION_REPEATABLE_READ

static final int TRANSACTION_REPEATABLE_READ
            

一个常量，表示防止脏读和不可重复读；可能会出现幻读。这个级别禁止一个事务读取其中有未提交更改的行，它还禁止一个事务读取一行，第二个事务更改该行，第一个事务重新读取该行，第二次得到不同值的情况（ “不可重复读取”）。

参见：

• 常量字段值

TRANSACTION_SERIALIZABLE

static final int TRANSACTION_SERIALIZABLE
            

一个常量，表示防止脏读、不可重复读和幻读。此级别包括 TRANSACTION_REPEATABLE_READ 中的禁令，并进一步禁止以下情况：一个事务读取满足 WHERE 条件的所有行，第二个事务插入满足该 WHERE 条件的行，并且第一个事务重新读取相同条件，检索额外的“幻影”行在第二次阅读中。

参见：

• 常量字段值

方法详情

createStatement

Statement  createStatement() throws SQL异常 
            

创建一个 Statement 对象，用于将 SQL 语句发送到数据库。不带参数的 SQL 语句通常使用 Statement 对象执行。如果多次执行相同的 SQL 语句，使用 PreparedStatement 对象可能更有效。

使用返回的 Statement 对象创建的结果集默认为 TYPE_FORWARD_ONLY 类型，并发级别为 CONCUR_READ_ONLY 。可以通过调用 getHoldability() 来确定创建的结果集的可持有性。

返回：

一个新的默认 Statement 对象

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

prepareStatement

PreparedStatement  prepareStatement(String  sql) throws SQL异常 
            

创建一个 PreparedStatement 对象，用于将参数化 SQL 语句发送到数据库。

带或不带 IN 参数的 SQL 语句都可以预编译并存储在 PreparedStatement 对象中。然后可以使用该对象多次有效地执行该语句。

笔记：此方法针对处理受益于预编译的参数化 SQL 语句进行了优化。如果驱动程序支持预编译，方法prepareStatement会将语句发送到数据库进行预编译。某些驱动程序可能不支持预编译。在这种情况下，在执行PreparedStatement 对象之前，可能不会将语句发送到数据库。这对用户没有直接影响；但是，它确实会影响哪些方法抛出某些 SQLException 对象。

使用返回的 PreparedStatement 对象创建的结果集默认为 TYPE_FORWARD_ONLY 类型，并发级别为 CONCUR_READ_ONLY 。可以通过调用 getHoldability() 来确定创建的结果集的可持有性。

参数：

sql - 可能包含一个或多个“?”的 SQL 语句IN 参数占位符

返回：

包含预编译 SQL 语句的新默认 PreparedStatement 对象

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

prepareCall

CallableStatement  prepareCall(String  sql) throws SQL异常 
            

创建用于调用数据库存储过程的 CallableStatement 对象。 CallableStatement 对象提供了用于设置其 IN 和 OUT 参数的方法，以及用于执行对存储过程的调用的方法。

笔记：此方法针对处理存储过程调用语句进行了优化。某些驱动程序可能会在方法prepareCall完成时将调用语句发送到数据库；其他人可能会等到 CallableStatement 对象被执行。这对用户没有直接影响；但是，它确实会影响哪个方法抛出某些 SQLException。

使用返回的 CallableStatement 对象创建的结果集默认为 TYPE_FORWARD_ONLY 类型，并发级别为 CONCUR_READ_ONLY。可以通过调用 getHoldability() 来确定创建的结果集的可持有性。

参数：

sql - 可能包含一个或多个“?”的 SQL 语句参数占位符。通常，此语句是使用 JDBC 调用转义语法指定的。

返回：

包含预编译 SQL 语句的新默认 CallableStatement 对象

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

nativeSQL

String  nativeSQL(String  sql) throws SQL异常 
            

将给定的 SQL 语句转换为系统的本机 SQL 语法。驱动程序可以在发送 JDBC SQL 语法之前将其转换为系统的本机 SQL 语法。此方法返回驱动程序将发送的语句的本机形式。

参数：

sql - 可能包含一个或多个“?”的 SQL 语句参数占位符

返回：

该语句的原始形式

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

setAutoCommit

void setAutoCommit(boolean autoCommit) throws SQL异常 
            

将此连接的自动提交模式设置为给定状态。如果连接处于自动提交模式，则其所有 SQL 语句将作为单独的事务执行和提交。否则，它的 SQL 语句被分组为通过调用方法 commit 或方法 rollback 终止的事务。默认情况下，新连接处于自动提交模式。

提交发生在语句完成时。语句完成的时间取决于 SQL 语句的类型：

• 对于 DML 语句，如 Insert、Update 或 Delete，以及 DDL 语句，一旦执行完毕，语句就完成了。
• 对于 Select 语句，当关联的结果集关闭时语句完成。
• 对于 CallableStatement 对象或返回多个结果的语句，当所有关联的结果集都已关闭并且所有更新计数和输出参数已被检索时，语句完成。

NOTE:如果在事务期间调用此方法并且更改了自动提交模式，则提交事务。如果调用 setAutoCommit 并且自动提交模式未更改，则该调用是空操作。

参数：

autoCommit - true 启用自动提交模式； false 禁用它

抛出：

SQLException - 如果发生数据库访问错误，则在参与分布式事务时调用 setAutoCommit(true)，或者在关闭的连接上调用此方法

参见：

• getAutoCommit()

getAutoCommit

boolean getAutoCommit() throws SQL异常 
            

检索此 Connection 对象的当前自动提交模式。

返回：

此 Connection 对象的自动提交模式的当前状态

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

参见：

• setAutoCommit(boolean)

commit

void commit() throws SQL异常 
            

使自上次提交/回滚以来所做的所有更改永久化，并释放当前由该 Connection 对象持有的所有数据库锁。只有在禁用自动提交模式时才应使用此方法。

抛出：

SQLException - 如果发生数据库访问错误，则在参与分布式事务时调用此方法，如果在关闭的连接上调用此方法或此 Connection 对象处于自动提交模式

参见：

• setAutoCommit(boolean)

rollback

void rollback() throws SQL异常 
            

撤消当前事务中所做的所有更改并释放此 Connection 对象当前持有的所有数据库锁。只有在禁用自动提交模式时才应使用此方法。

抛出：

SQLException - 如果发生数据库访问错误，则在参与分布式事务时调用此方法，在关闭的连接上调用此方法或此 Connection 对象处于自动提交模式

参见：

• setAutoCommit(boolean)

close

void close() throws SQL异常 
            

立即释放此 Connection 对象的数据库和 JDBC 资源，而不是等待它们自动释放。

在已关闭的 Connection 对象上调用方法 close 是空操作。

这是强力推荐应用程序在调用 close 方法之前显式提交或回滚活动事务。如果调用 close 方法并且存在活动事务，则结果由实现定义。

指定者：

close 在接口 AutoCloseable 中

抛出：

SQLException - 如果发生数据库访问错误

isClosed

boolean isClosed() throws SQL异常 
            

检索此 Connection 对象是否已关闭。如果已调用方法 close 或发生某些致命错误，连接将关闭。只有在调用方法 Connection.close 之后调用此方法，才能保证返回 true。

通常不能调用此方法来确定与数据库的连接是有效还是无效。典型的客户端可以通过捕获尝试操作时可能抛出的任何异常来确定连接无效。

返回：

true 如果此 Connection 对象已关闭； false如果它仍然开放

抛出：

SQLException - 如果发生数据库访问错误

getMetaData

DatabaseMetaData  getMetaData() throws SQL异常 
            

检索一个 DatabaseMetaData 对象，该对象包含有关此 Connection 对象表示连接的数据库的元数据。元数据包括有关数据库表的信息、其支持的 SQL 语法、存储过程、此连接的功能等。

返回：

这个 Connection 对象的 DatabaseMetaData 对象

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

setReadOnly

void setReadOnly(boolean readOnly) throws SQL异常 
            

将此连接置于只读模式，以提示驱动程序启用数据库优化。

笔记：在事务期间不能调用此方法。

参数：

readOnly - true 启用只读模式； false 禁用它

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或在事务期间调用此方法

isReadOnly

boolean isReadOnly() throws SQL异常 
            

检索此 Connection 对象是否处于只读模式。

返回：

true 如果这个 Connection 对象是只读的； false否则

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

setCatalog

void setCatalog(String  catalog) throws SQL异常 
            

设置给定的目录名称，以便选择此 Connection 对象的数据库的子空间在其中工作。

如果驱动程序不支持目录，它会默默地忽略这个请求。

调用 setCatalog 对之前创建或准备的 Statement 对象没有影响。调用 Connection 方法 prepareStatement 或 prepareCall 时，DBMS 准备操作是否立即发生由实现定义。为了获得最大的可移植性，应在创建或准备 Statement 之前调用 setCatalog。

参数：

catalog - 在其中工作的目录名称（此 Connection 对象数据库中的子空间）

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

参见：

• getCatalog()

getCatalog

String  getCatalog() throws SQL异常 
            

检索此 Connection 对象的当前目录名称。

返回：

当前目录名称或 null（如果没有）

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

参见：

• setCatalog(java.lang.String)

setTransactionIsolation

void setTransactionIsolation(int level) throws SQL异常 
            

尝试将此 Connection 对象的事务隔离级别更改为给定级别。接口Connection 中定义的常量是可能的事务隔离级别。

笔记：如果在事务期间调用此方法，则结果是实现定义的。

参数：

level - 以下 Connection 常量之一：Connection.TRANSACTION_READ_UNCOMMITTED、Connection.TRANSACTION_READ_COMMITTED、Connection.TRANSACTION_REPEATABLE_READ 或 Connection.TRANSACTION_SERIALIZABLE。 （请注意，Connection.TRANSACTION_NONE 不能使用，因为它指定不支持事务。）

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或给定参数不是 Connection 常量之一

参见：

• DatabaseMetaData.supportsTransactionIsolationLevel(int)
• getTransactionIsolation()

getTransactionIsolation

int getTransactionIsolation() throws SQL异常 
            

检索此 Connection 对象的当前事务隔离级别。

返回：

当前事务隔离级别，它将是以下常量之一：Connection.TRANSACTION_READ_UNCOMMITTED、Connection.TRANSACTION_READ_COMMITTED、Connection.TRANSACTION_REPEATABLE_READ、Connection.TRANSACTION_SERIALIZABLE 或 Connection.TRANSACTION_NONE。

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

参见：

• setTransactionIsolation(int)

getWarnings

SQLWarning  getWarnings() throws SQL异常 
            

检索对此 Connection 对象的调用报告的第一个警告。如果有多个警告，则后续警告将链接到第一个警告，并且可以通过对先前检索到的警告调用方法 SQLWarning.getNextWarning 来检索。

不能在关闭的连接上调用此方法；这样做会导致抛出 SQLException。

笔记：后续警告将链接到此 SQLWarning。

返回：

第一个 SQLWarning 对象或 null 如果没有

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

参见：

• SQLWarning

clearWarnings

void clearWarnings() throws SQL异常 
            

清除为此 Connection 对象报告的所有警告。调用此方法后，方法 getWarnings 返回 null 直到针对此 Connection 对象报告新警告。

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

createStatement

Statement  createStatement(int resultSetType, int resultSetConcurrency) throws SQL异常 
            

创建一个 Statement 对象，它将生成具有给定类型和并发性的 ResultSet 对象。此方法与上面的createStatement方法相同，但它允许覆盖默认结果集类型和并发。可以通过调用 getHoldability() 来确定创建的结果集的可持有性。

参数：

resultSetType - 结果集类型； ResultSet.TYPE_FORWARD_ONLY、ResultSet.TYPE_SCROLL_INSENSITIVE 或 ResultSet.TYPE_SCROLL_SENSITIVE 之一

resultSetConcurrency - 并发类型； ResultSet.CONCUR_READ_ONLY 或 ResultSet.CONCUR_UPDATABLE 之一

返回：

一个新的 Statement 对象，它将生成具有给定类型和并发性的 ResultSet 对象

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或给定的参数不是 ResultSet 指示类型和并发性的常量

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法或指定的结果集类型和结果集并发不支持此方法。

自从：

1.2

prepareStatement

PreparedStatement  prepareStatement(String  sql, int resultSetType, int resultSetConcurrency) throws SQL异常 
            

创建一个 PreparedStatement 对象，它将生成具有给定类型和并发性的 ResultSet 对象。此方法与上面的prepareStatement方法相同，但它允许覆盖默认结果集类型和并发。可以通过调用 getHoldability() 来确定创建的结果集的可持有性。

参数：

sql - 一个 String 对象，它是要发送到数据库的 SQL 语句；可能包含一个或多个'?'输入参数

resultSetType - 结果集类型； ResultSet.TYPE_FORWARD_ONLY、ResultSet.TYPE_SCROLL_INSENSITIVE 或 ResultSet.TYPE_SCROLL_SENSITIVE 之一

resultSetConcurrency - 并发类型； ResultSet.CONCUR_READ_ONLY 或 ResultSet.CONCUR_UPDATABLE 之一

返回：

一个新的 PreparedStatement 对象，包含预编译的 SQL 语句，该语句将生成具有给定类型和并发性的 ResultSet 对象

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或给定的参数不是 ResultSet 指示类型和并发性的常量

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法或指定的结果集类型和结果集并发不支持此方法。

自从：

1.2

prepareCall

CallableStatement  prepareCall(String  sql, int resultSetType, int resultSetConcurrency) throws SQL异常 
            

创建一个 CallableStatement 对象，它将生成具有给定类型和并发性的 ResultSet 对象。此方法与上面的prepareCall方法相同，但它允许覆盖默认结果集类型和并发性。可以通过调用 getHoldability() 来确定创建的结果集的可持有性。

参数：

sql - 一个 String 对象，它是要发送到数据库的 SQL 语句；可能包含一个或多个“？”参数

resultSetType - 结果集类型； ResultSet.TYPE_FORWARD_ONLY、ResultSet.TYPE_SCROLL_INSENSITIVE 或 ResultSet.TYPE_SCROLL_SENSITIVE 之一

resultSetConcurrency - 并发类型； ResultSet.CONCUR_READ_ONLY 或 ResultSet.CONCUR_UPDATABLE 之一

返回：

一个新的 CallableStatement 对象，包含预编译的 SQL 语句，该语句将生成具有给定类型和并发性的 ResultSet 对象

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或给定的参数不是 ResultSet 指示类型和并发性的常量

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法或指定的结果集类型和结果集并发不支持此方法。

自从：

1.2

getTypeMap

Map <String ,Class <?>> getTypeMap() throws SQL异常 
            

检索与此 Connection 对象关联的 Map 对象。除非应用程序添加了条目，否则返回的类型映射将为空。

您必须在更改从 getTypeMap 返回的 Map 对象后调用 setTypeMap，因为 JDBC 驱动程序可能会创建传递给 setTypeMap 的 Map 对象的内部副本：

   Map<String,Class<?>> myMap = con.getTypeMap();
   myMap.put("mySchemaName.ATHLETES", Athletes.class);
   con.setTypeMap(myMap);
 

返回：

与此 Connection 对象关联的 java.util.Map 对象

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.2

参见：

• setTypeMap(java.util.Map<java.lang.String, java.lang.Class<?>>)

setTypeMap

void setTypeMap(Map <String ,Class <?>> map) throws SQL异常 
            

安装给定的 TypeMap 对象作为此 Connection 对象的类型映射。类型映射将用于 SQL 结构化类型和不同类型的自定义映射。

您必须在调用 setMap 之前设置 TypeMap 的值，因为 JDBC 驱动程序可能会创建 TypeMap 的内部副本：

   Map myMap<String,Class<?>> = new HashMap<String,Class<?>>();
   myMap.put("mySchemaName.ATHLETES", Athletes.class);
   con.setTypeMap(myMap);
 

参数：

map - 要安装的 java.util.Map 对象作为此 Connection 对象的默认类型映射的替换

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或给定参数不是 java.util.Map 对象

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.2

参见：

• getTypeMap()

setHoldability

void setHoldability(int holdability) throws SQL异常 
            

将使用此 Connection 对象创建的 ResultSet 对象的默认可持有性更改为给定的可持有性。 ResultSet 对象的默认可持有性可以通过调用 DatabaseMetaData.getResultSetHoldability() 来确定。

参数：

holdability - 一个 ResultSet 可保持性常数； ResultSet.HOLD_CURSORS_OVER_COMMIT 或 ResultSet.CLOSE_CURSORS_AT_COMMIT 之一

抛出：

SQLException - 如果发生数据库访问，则在关闭的连接上调用此方法，或者给定的参数不是 ResultSet 表示可保持性的常量

SQLFeatureNotSupportedException - 如果不支持给定的可持性

自从：

1.4

参见：

• getHoldability()
• DatabaseMetaData.getResultSetHoldability()
• ResultSet

getHoldability

int getHoldability() throws SQL异常 
            

检索使用此 Connection 对象创建的 ResultSet 对象的当前可持有性。

返回：

可保持性，ResultSet.HOLD_CURSORS_OVER_COMMIT 或 ResultSet.CLOSE_CURSORS_AT_COMMIT 之一

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

自从：

1.4

参见：

• setHoldability(int)
• DatabaseMetaData.getResultSetHoldability()
• ResultSet

setSavepoint

Savepoint  setSavepoint() throws SQL异常 
            

在当前事务中创建一个未命名的保存点并返回代表它的新 Savepoint 对象。

如果在活动事务之外调用 setSavepoint，事务将在这个新创建的保存点启动。

返回：

新的 Savepoint 对象

抛出：

SQLException - 如果发生数据库访问错误，则在参与分布式事务时调用此方法，在关闭的连接上调用此方法或此 Connection 对象当前处于自动提交模式

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.4

参见：

• Savepoint

setSavepoint

Savepoint  setSavepoint(String  name) throws SQL异常 
            

在当前事务中创建一个具有给定名称的保存点并返回表示它的新 Savepoint 对象。

如果在活动事务之外调用 setSavepoint，事务将在这个新创建的保存点启动。

参数：

name - 包含保存点名称的 String

返回：

新的 Savepoint 对象

抛出：

SQLException - 如果发生数据库访问错误，则在参与分布式事务时调用此方法，在关闭的连接上调用此方法或此 Connection 对象当前处于自动提交模式

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.4

参见：

• Savepoint

rollback

void rollback(Savepoint  savepoint) throws SQL异常 
            

撤消设置给定 Savepoint 对象后所做的所有更改。

只有在禁用自动提交时才应使用此方法。

参数：

savepoint - 要回滚到的 Savepoint 对象

抛出：

SQLException - 如果发生数据库访问错误，在参与分布式事务时调用此方法，在关闭的连接上调用此方法，Savepoint 对象不再有效，或者此 Connection 对象当前处于自动提交模式

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.4

参见：

• Savepoint
• rollback()

releaseSavepoint

void releaseSavepoint(Savepoint  savepoint) throws SQL异常 
            

从当前事务中删除指定的 Savepoint 和后续的 Savepoint 对象。删除保存点后对保存点的任何引用都将导致抛出 SQLException。

参数：

savepoint - 要删除的 Savepoint 对象

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法，或者给定的 Savepoint 对象不是当前事务中的有效保存点

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.4

createStatement

Statement  createStatement(int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQL异常 
            

创建一个 Statement 对象，该对象将生成具有给定类型、并发性和可持有性的 ResultSet 对象。此方法与上面的createStatement 方法相同，但它允许覆盖默认结果集类型、并发性和可保存性。

参数：

resultSetType - 以下 ResultSet 常量之一：ResultSet.TYPE_FORWARD_ONLY、ResultSet.TYPE_SCROLL_INSENSITIVE 或 ResultSet.TYPE_SCROLL_SENSITIVE

resultSetConcurrency - 以下 ResultSet 常量之一：ResultSet.CONCUR_READ_ONLY 或 ResultSet.CONCUR_UPDATABLE

resultSetHoldability - 以下 ResultSet 常量之一：ResultSet.HOLD_CURSORS_OVER_COMMIT 或 ResultSet.CLOSE_CURSORS_AT_COMMIT

返回：

一个新的 Statement 对象，它将生成具有给定类型、并发性和可持有性的 ResultSet 对象

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或给定参数不是 ResultSet 表示类型、并发性和可保存性的常量

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法或指定的结果集类型、结果集可持有性和结果集并发性不支持此方法。

自从：

1.4

参见：

• ResultSet

prepareStatement

PreparedStatement  prepareStatement(String  sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQL异常 
            

创建一个 PreparedStatement 对象，该对象将生成具有给定类型、并发性和可持有性的 ResultSet 对象。

此方法与上面的prepareStatement 方法相同，但它允许覆盖默认结果集类型、并发性和可保存性。

参数：

sql - 一个 String 对象，它是要发送到数据库的 SQL 语句；可能包含一个或多个'?'输入参数

resultSetType - 以下 ResultSet 常量之一：ResultSet.TYPE_FORWARD_ONLY、ResultSet.TYPE_SCROLL_INSENSITIVE 或 ResultSet.TYPE_SCROLL_SENSITIVE

resultSetConcurrency - 以下 ResultSet 常量之一：ResultSet.CONCUR_READ_ONLY 或 ResultSet.CONCUR_UPDATABLE

resultSetHoldability - 以下 ResultSet 常量之一：ResultSet.HOLD_CURSORS_OVER_COMMIT 或 ResultSet.CLOSE_CURSORS_AT_COMMIT

返回：

一个新的 PreparedStatement 对象，包含预编译的 SQL 语句，它将生成具有给定类型、并发性和可持有性的 ResultSet 对象

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或给定参数不是 ResultSet 表示类型、并发性和可保存性的常量

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法或指定的结果集类型、结果集可持有性和结果集并发性不支持此方法。

自从：

1.4

参见：

• ResultSet

prepareCall

CallableStatement  prepareCall(String  sql, int resultSetType, int resultSetConcurrency, int resultSetHoldability) throws SQL异常 
            

创建一个 CallableStatement 对象，它将生成具有给定类型和并发性的 ResultSet 对象。此方法与上面的prepareCall方法相同，但它允许覆盖默认的结果集类型、结果集并发类型和可保持性。

参数：

sql - 一个 String 对象，它是要发送到数据库的 SQL 语句；可能包含一个或多个“？”参数

resultSetType - 以下 ResultSet 常量之一：ResultSet.TYPE_FORWARD_ONLY、ResultSet.TYPE_SCROLL_INSENSITIVE 或 ResultSet.TYPE_SCROLL_SENSITIVE

resultSetConcurrency - 以下 ResultSet 常量之一：ResultSet.CONCUR_READ_ONLY 或 ResultSet.CONCUR_UPDATABLE

resultSetHoldability - 以下 ResultSet 常量之一：ResultSet.HOLD_CURSORS_OVER_COMMIT 或 ResultSet.CLOSE_CURSORS_AT_COMMIT

返回：

一个新的 CallableStatement 对象，包含预编译的 SQL 语句，它将生成具有给定类型、并发性和可持有性的 ResultSet 对象

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或给定参数不是 ResultSet 表示类型、并发性和可保存性的常量

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法或指定的结果集类型、结果集可持有性和结果集并发性不支持此方法。

自从：

1.4

参见：

• ResultSet

prepareStatement

PreparedStatement  prepareStatement(String  sql, int autoGeneratedKeys) throws SQL异常 
            

创建一个默认的 PreparedStatement 对象，该对象能够检索自动生成的密钥。给定的常量告诉驱动程序是否应该使自动生成的密钥可用于检索。如果 SQL 语句不是 INSERT 语句，或者不是能够返回自动生成键的 SQL 语句（此类语句的列表是特定于供应商的），则忽略此参数。

笔记：此方法针对处理受益于预编译的参数化 SQL 语句进行了优化。如果驱动程序支持预编译，方法prepareStatement会将语句发送到数据库进行预编译。某些驱动程序可能不支持预编译。在这种情况下，在执行PreparedStatement 对象之前，可能不会将语句发送到数据库。这对用户没有直接影响；但是，它确实会影响哪些方法会抛出某些 SQLException。

使用返回的 PreparedStatement 对象创建的结果集默认为 TYPE_FORWARD_ONLY 类型，并发级别为 CONCUR_READ_ONLY 。可以通过调用 getHoldability() 来确定创建的结果集的可持有性。

参数：

sql - 可能包含一个或多个“?”的 SQL 语句IN 参数占位符

autoGeneratedKeys - 指示是否应返回自动生成的密钥的标志； Statement.RETURN_GENERATED_KEYS 或 Statement.NO_GENERATED_KEYS 之一

返回：

一个新的 PreparedStatement 对象，包含预编译的 SQL 语句，将具有返回自动生成的键的能力

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法或给定参数不是 Statement 常量，指示是否应返回自动生成的键

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持带有 Statement.RETURN_GENERATED_KEYS 常量的此方法

自从：

1.4

prepareStatement

PreparedStatement  prepareStatement(String  sql, int[] columnIndexes) throws SQL异常 
            

创建一个默认的 PreparedStatement 对象，能够返回由给定数组指定的自动生成的键。该数组包含目标表中列的索引，这些列包含应该可用的自动生成的键。如果 SQL 语句不是 INSERT 语句，或者不是能够返回自动生成键的 SQL 语句（此类语句的列表是特定于供应商的），驱动程序将忽略该数组。

带或不带 IN 参数的 SQL 语句都可以预编译并存储在 PreparedStatement 对象中。然后可以使用该对象多次有效地执行该语句。

笔记：此方法针对处理受益于预编译的参数化 SQL 语句进行了优化。如果驱动程序支持预编译，方法prepareStatement会将语句发送到数据库进行预编译。某些驱动程序可能不支持预编译。在这种情况下，在执行PreparedStatement 对象之前，可能不会将语句发送到数据库。这对用户没有直接影响；但是，它确实会影响哪些方法会抛出某些 SQLException。

使用返回的 PreparedStatement 对象创建的结果集默认为 TYPE_FORWARD_ONLY 类型，并发级别为 CONCUR_READ_ONLY 。可以通过调用 getHoldability() 来确定创建的结果集的可持有性。

参数：

sql - 可能包含一个或多个“?”的 SQL 语句IN 参数占位符

columnIndexes - 列索引数组，指示应从插入的行返回的列

返回：

一个新的 PreparedStatement 对象，包含预编译语句，能够返回由给定的列索引数组指定的自动生成的键

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.4

prepareStatement

PreparedStatement  prepareStatement(String  sql, String [] columnNames) throws SQL异常 
            

创建一个默认的 PreparedStatement 对象，能够返回由给定数组指定的自动生成的键。该数组包含目标表中列的名称，这些列包含应返回的自动生成的键。如果 SQL 语句不是 INSERT 语句，或者不是能够返回自动生成键的 SQL 语句（此类语句的列表是特定于供应商的），驱动程序将忽略该数组。

带或不带 IN 参数的 SQL 语句都可以预编译并存储在 PreparedStatement 对象中。然后可以使用该对象多次有效地执行该语句。

笔记：此方法针对处理受益于预编译的参数化 SQL 语句进行了优化。如果驱动程序支持预编译，方法prepareStatement会将语句发送到数据库进行预编译。某些驱动程序可能不支持预编译。在这种情况下，在执行PreparedStatement 对象之前，可能不会将语句发送到数据库。这对用户没有直接影响；但是，它确实会影响哪些方法会抛出某些 SQLException。

使用返回的 PreparedStatement 对象创建的结果集默认为 TYPE_FORWARD_ONLY 类型，并发级别为 CONCUR_READ_ONLY 。可以通过调用 getHoldability() 来确定创建的结果集的可持有性。

参数：

sql - 可能包含一个或多个“?”的 SQL 语句IN 参数占位符

columnNames - 列名数组，指示应从插入的一行或多行中返回的列

返回：

一个新的 PreparedStatement 对象，包含预编译语句，能够返回由给定的列名数组指定的自动生成的键

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.4

createClob

Clob  createClob() throws SQL异常 
            

构造一个实现 Clob 接口的对象。最初返回的对象不包含任何数据。 Clob接口的setAsciiStream、setCharacterStream和setString方法可用于向Clob添加数据。

返回：

实现 Clob 接口的对象

抛出：

SQLException - 如果无法构造实现 Clob 接口的对象，则在关闭连接或发生数据库访问错误时调用此方法。

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此数据类型

自从：

1.6

createBlob

Blob  createBlob() throws SQL异常 
            

构造一个实现 Blob 接口的对象。最初返回的对象不包含任何数据。 Blob 接口的 setBinaryStream 和 setBytes 方法可用于向 Blob 添加数据。

返回：

实现 Blob 接口的对象

抛出：

SQLException - 如果无法构造实现 Blob 接口的对象，则在关闭的连接或发生数据库访问错误时调用此方法。

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此数据类型

自从：

1.6

createNClob

NClob  createNClob() throws SQL异常 
            

构造一个实现 NClob 接口的对象。最初返回的对象不包含任何数据。 NClob接口的setAsciiStream、setCharacterStream和setString方法可用于向NClob添加数据。

返回：

实现 NClob 接口的对象

抛出：

SQLException - 如果无法构造实现 NClob 接口的对象，则在关闭连接或发生数据库访问错误时调用此方法。

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此数据类型

自从：

1.6

createSQLXML

SQLXML  createSQLXML() throws SQL异常 
            

构造一个实现 SQLXML 接口的对象。最初返回的对象不包含任何数据。 SQLXML接口的createXmlStreamWriter对象和setString方法可用于向SQLXML对象添加数据。

返回：

实现 SQLXML 接口的对象

抛出：

SQLException - 如果无法构造实现 SQLXML 接口的对象，则在关闭连接或发生数据库访问错误时调用此方法。

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此数据类型

自从：

1.6

isValid

boolean isValid(int timeout) throws SQL异常 
            

如果连接尚未关闭且仍然有效，则返回 true。调用此方法时，驱动程序应提交对连接的查询或使用其他一些机制来积极验证连接是否仍然有效。

驱动程序提交的用于验证连接的查询应在当前事务的上下文中执行。

参数：

timeout - - 等待用于验证连接完成的数据库操作的时间（以秒为单位）。如果超时期限在操作完成之前到期，则此方法返回 false。值 0 表示超时未应用于数据库操作。

返回：

如果连接有效则为 true，否则为 false

抛出：

SQLException - 如果为 timeout 提供的值小于 0

自从：

1.6

参见：

• DatabaseMetaData.getClientInfoProperties()

setClientInfo

void setClientInfo(String  name, String  value) throws SQLClientInfoException 
            

将名称指定的客户端信息属性的值设置为值指定的值。

应用程序可以使用 DatabaseMetaData.getClientInfoProperties 方法来确定驱动程序支持的客户端信息属性以及可以为每个属性指定的最大长度。

驱动程序将指定的值存储在数据库中的合适位置。例如在特殊寄存器、会话参数或系统表列中。为了提高效率，驱动程序可能会推迟在数据库中设置值，直到下一次执行或准备语句。除了将客户端信息存储在数据库中的适当位置之外，这些方法无论如何都不应改变连接的行为。提供给这些方法的值仅用于统计、诊断和调试目的。

如果驱动程序无法识别指定的客户端信息名称，驱动程序将生成警告。

如果为此方法指定的值大于属性的最大长度，驱动程序可能会截断该值并生成警告或生成 SQLClientInfoException。如果驱动程序生成 SQLClientInfoException ，则指定的值未在连接上设置。

以下是标准的客户端信息属性。驱动程序不需要支持这些属性，但是如果驱动程序支持可以由标准属性之一描述的客户端信息属性，则应使用标准属性名称。

• ApplicationName - 当前使用连接的应用程序的名称
• ClientUser - 使用连接的应用程序正在为其执行工作的用户的名称。这可能与建立连接时使用的用户名不同。
• ClientHostname - 运行使用连接的应用程序的计算机的主机名。

参数：

name - 要设置的客户端信息属性的名称

value - 将客户端信息属性设置为的值。如果该值为 null，则清除指定属性的当前值。

抛出：

SQLClientInfoException - 如果在数据库服务上设置客户端信息值时数据库服务返回错误，或者在关闭的连接上调用此方法

自从：

1.6

setClientInfo

void setClientInfo(Properties  properties) throws SQLClientInfoException 
            

设置连接的客户端信息属性的值。 Properties 对象包含要设置的客户端信息属性的名称和值。属性列表中包含的客户端信息属性集替换连接上的当前客户端信息属性集。如果当前在连接上设置的属性不在属性列表中，则该属性将被清除。指定一个空的属性列表将清除连接上的所有属性。有关详细信息，请参阅 setClientInfo (String, String)。

如果在设置任何客户端信息属性时发生错误，则会抛出 SQLClientInfoException。 SQLClientInfoException 包含指示未设置哪些客户端信息属性的信息。客户端信息的状态是未知的，因为某些数据库不允许以原子方式设置多个客户端信息属性。对于那些数据库，在错误发生之前可能已经设置了一个或多个属性。

参数：

properties - 要设置的客户端信息属性列表

抛出：

SQLClientInfoException - 如果在数据库服务上设置 clientInfo 值时数据库服务返回错误，或者在关闭的连接上调用此方法

自从：

1.6

参见：

• setClientInfo(String, String)

getClientInfo

String  getClientInfo(String  name) throws SQL异常 
            

返回名称指定的客户端信息属性的值。如果尚未设置指定的客户端信息属性并且没有默认值，则此方法可能返回 null。如果驱动程序不支持指定的客户端信息属性名称，此方法也将返回 null。

应用程序可以使用 DatabaseMetaData.getClientInfoProperties 方法来确定驱动程序支持的客户端信息属性。

参数：

name - 要检索的客户端信息属性的名称

返回：

指定的客户端信息属性的值

抛出：

SQLException - 如果数据库服务在从数据库中获取客户端信息值时返回错误，或者在关闭的连接上调用此方法

自从：

1.6

参见：

• DatabaseMetaData.getClientInfoProperties()

getClientInfo

Properties  getClientInfo() throws SQL异常 
            

返回一个列表，其中包含驱动程序支持的每个客户端信息属性的名称和当前值。如果属性尚未设置且没有默认值，则客户端信息属性的值可能为空。

返回：

一个 Properties 对象，其中包含驱动程序支持的每个客户端信息属性的名称和当前值。

抛出：

SQLException - 如果数据库服务在从数据库中获取客户端信息值时返回错误，或者在关闭的连接上调用此方法

自从：

1.6

createArrayOf

Array  createArrayOf(String  typeName, Object [] elements) throws SQL异常 
            

用于创建 Array 对象的工厂方法。

笔记：当 createArrayOf 用于创建map到原始数据类型的数组对象时，Array 对象是该原始数据类型的数组还是 Object 的数组由实现定义。

笔记：JDBC 驱动程序负责将元素 Object 数组映射到 java.sql.Types 中为给定的 Object 类定义的默认 JDBC SQL 类型。默认映射在 JDBC 规范的附录 B 中指定。如果生成的 JDBC 类型不是给定 typeName 的适当类型，则由实现定义是否抛出 SQLException 或驱动程序支持生成的转换。

参数：

typeName - 数组元素映射到的类型的 SQL 名称。 typeName 是一个特定于数据库的名称，可以是该数据库支持的内置类型、用户定义类型或标准 SQL 类型的名称。这是 Array.getBaseTypeName 返回的值

elements - 填充返回对象的元素

返回：

一个 Array 对象，其元素映射到指定的 SQL 类型

抛出：

SQLException - 如果发生数据库错误，JDBC 类型不适合 typeName 并且不支持转换，typeName 为 null 或在关闭的连接上调用此方法

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此数据类型

自从：

1.6

createStruct

Struct  createStruct(String  typeName, Object [] attributes) throws SQL异常 
            

用于创建 Struct 对象的工厂方法。

参数：

typeName - 此 Struct 对象映射到的 SQL 结构类型的 SQL 类型名称。 typeName 是已为此数据库定义的用户定义类型的名称。它是 Struct.getSQLTypeName 返回的值。

attributes - 填充返回对象的属性

返回：

映射到给定 SQL 类型并使用给定属性填充的 Struct 对象

抛出：

SQLException - 如果发生数据库错误，则 typeName 为 null 或在关闭的连接上调用此方法

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此数据类型

自从：

1.6

setSchema

void setSchema(String  schema) throws SQL异常 
            

设置要访问的给定模式名称。

如果驱动程序不支持模式，它会默默地忽略这个请求。

调用 setSchema 对先前创建或准备的 Statement 对象没有影响。调用 Connection 方法 prepareStatement 或 prepareCall 时，DBMS 准备操作是否立即发生由实现定义。为了获得最大的可移植性，应在创建或准备 Statement 之前调用 setSchema。

参数：

schema - 工作模式的名称

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

自从：

1.7

参见：

• getSchema()

getSchema

String  getSchema() throws SQL异常 
            

检索此 Connection 对象的当前架构名称。

返回：

当前模式名称或 null（如果没有）

抛出：

SQLException - 如果发生数据库访问错误或在关闭的连接上调用此方法

自从：

1.7

参见：

• setSchema(java.lang.String)

abort

void abort(Executor  executor) throws SQL异常 
            

终止打开的连接。调用 abort 结果：

• 标记为关闭的连接
• 关闭与数据库的任何物理连接
• 释放连接使用的资源
• 确保当前正在访问连接的任何线程将继续完成或抛出 SQLException 。

调用 abort 标记连接关闭并释放所有资源。在关闭的连接上调用 abort 是空操作。

连接占用的资源的中止和释放可能需要较长时间。当 abort 方法返回时，连接将被标记为已关闭，作为参数传递给 abort 的 Executor 可能仍在执行任务以释放资源。

在允许该方法继续之前，此方法会检查是否存在 SQLPermission 对象。如果 SecurityManager 存在并且其 checkPermission 方法拒绝调用 abort ，则此方法抛出 java.lang.SecurityException 。

参数：

executor - abort 将使用的 Executor 实现。

抛出：

SQLException - 如果发生数据库访问错误或 executor 为 null，

SecurityException - 如果安全管理器存在且其 checkPermission 方法拒绝调用 abort

自从：

1.7

参见：

• SecurityManager.checkPermission(java.security.Permission)
• Executor

setNetworkTimeout

void setNetworkTimeout(Executor  executor, int milliseconds) throws SQL异常 
            

设置 Connection 或从 Connection 创建的对象将等待数据库回复任何一个请求的最长期限。如果任何请求仍未得到答复，等待方法将返回一个 SQLException ，并且 Connection 或从 Connection 创建的对象将被标记为已关闭。除了 close 、 isClosed 或 Connection.isValid 方法之外，对象的任何后续使用都将导致 SQLException 。

笔记：此方法旨在解决一种罕见但严重的情况，在这种情况下，网络分区可能导致发出 JDBC 调用的线程在套接字读取中不间断地挂起，直到操作系统 TCP 超时（通常为 10 分钟）。此方法与 abort() 方法相关，后者为管理员线程提供了一种方法，可以在管理员线程可以访问 JDBC 连接的情况下释放任何此类线程。 setNetworkTimeout 方法将涵盖没有管理员线程或无法访问连接的情况。这个方法的影响很严重，应该给它一个足够高的值，这样它就不会在任何更正常的超时之前被触发，比如事务超时。

在没有网络的环境中，JDBC 驱动程序实现也可以选择支持 setNetworkTimeout 方法来限制数据库响应时间。

驱动程序可以通过多个内部驱动程序-数据库传输在内部实现它们的部分或全部 API 调用，并且由驱动程序实现来确定限制是否始终应用于对 API 调用的响应，或任何单个请求在 API 调用期间。

该方法可以多次调用，例如为 JDBC 代码区域设置限制，并在退出该区域时重置为默认值。调用此方法对已经未完成的请求没有影响。

Statement.setQueryTimeout() 超时值独立于 setNetworkTimeout 中指定的超时值。如果查询超时在网络超时之前到期，则语句执行将被取消。如果网络仍处于活动状态，结果将是语句和连接仍然可用。但是，如果网络超时在查询超时之前到期，或者语句超时由于网络问题而失败，则连接将被标记为已关闭，连接占用的所有资源都将被释放，连接和语句都将无法使用。

当驱动程序确定 setNetworkTimeout 超时值已过期时，JDBC 驱动程序将连接标记为关闭并释放连接占用的所有资源。

在允许该方法继续之前，此方法会检查是否存在 SQLPermission 对象。如果 SecurityManager 存在且其 checkPermission 方法拒绝调用 setNetworkTimeout，则此方法将抛出 java.lang.SecurityException。

参数：

executor - setNetworkTimeout 将使用的 Executor 实现。

milliseconds - 等待数据库操作完成的时间（以毫秒为单位）。如果 JDBC 驱动程序不支持毫秒，JDBC 驱动程序会将值四舍五入到最接近的秒数。如果超时期限在操作完成之前到期，将抛出 SQLException。值为 0 表示数据库操作没有超时。

抛出：

SQLException - 如果发生数据库访问错误，则在关闭的连接上调用此方法，executor 为 null，或者为 seconds 指定的值小于 0。

SecurityException - 如果安全管理器存在且其 checkPermission 方法拒绝调用 setNetworkTimeout。

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.7

参见：

• SecurityManager.checkPermission(java.security.Permission)
• Statement.setQueryTimeout(int)
• getNetworkTimeout()
• abort(java.util.concurrent.Executor)
• Executor

getNetworkTimeout

int getNetworkTimeout() throws SQL异常 
            

检索驱动程序将等待数据库请求完成的毫秒数。如果超出限制，则会抛出 SQLException。

返回：

当前超时限制（以毫秒为单位）；零意味着没有限制

抛出：

SQLException - 如果发生数据库访问错误或在关闭的 Connection 上调用此方法

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法

自从：

1.7

参见：

• setNetworkTimeout(java.util.concurrent.Executor, int)

beginRequest

default void beginRequest() throws SQL异常 
            

向驱动程序提示一个请求，一个独立的工作单元，正在这个连接上开始。每个请求都独立于客户端或服务上连接本地状态的所有其他请求。在 beginRequest 和 endRequest 对之间完成的工作不依赖于连接上完成的任何其他工作，无论是作为另一个请求的一部分还是在任何请求之外。一个请求可能包含多个事务。可能依赖于提交的数据库状态，因为它不是连接的本地状态。

本地状态定义为与 Connection 关联的任何状态，该 Connection 对于当前 Connection 在客户端或数据库中是本地的，并且不可透明地重现。

对 beginRequest 和 endRequest 的调用不是嵌套的。多次调用 beginRequest 而中间没有调用 endRequest 不是错误。第一个 beginRequest 调用标志着请求的开始，后续调用被视为空操作

beginRequest 和 endRequest 的使用是可选的，特定于供应商并且应该在很大程度上是透明的。在特定的实现中，可以检测指示依赖于其他工作（例如开放事务）的条件。建议（但不要求）如果存在活动事务并调用 beginRequest，则实现会抛出 SQLException。使用这些方法可以提高性能或提供其他好处。有关其他信息，请参阅您的供应商文档。

建议将每个工作单元包含在 beginRequest、endRequest 对中，以便在请求的开始或结束时没有打开的事务，并且不依赖于跨越请求边界的本地状态。提交的数据库状态不是本地的。

API 注意：

此方法将由连接池管理器使用。

在将连接返回给调用者之前，池管理器应该在底层连接上调用 beginRequest。

在以下情况下，池管理器不需要调用 beginRequest：

• 连接池缓存PooledConnection个对象
• 当应用程序调用 getConnection 时返回逻辑连接句柄
• 在将 PooledConnection 返回到缓存之前，通过调用 Connection.close 关闭逻辑 Connection。

实现要求：

默认实现是空操作。

抛出：

SQLException - 如果发生错误

自从：

9

参见：

• endRequest()
• PooledConnection

endRequest

default void endRequest() throws SQL异常 
            

向驱动程序提示请求（一个独立的工作单元）已完成。对 beginRequest 和 endRequest 的调用不是嵌套的。多次调用 endRequest 而中间没有调用 beginRequest 不是错误。第一个 endRequest 调用标记请求已完成，后续调用被视为空操作。如果 endRequest 在没有初始调用的情况下被调用，则 beginRequest 是空操作。

此方法的确切行为是特定于供应商的。在特定的实现中，可以检测指示依赖于其他工作（例如开放事务）的条件。建议（但不要求）如果存在活动事务并调用 endRequest，则实现会抛出 SQLException。

API 注意：

此方法将由连接池管理器使用。

当应用程序将连接返回连接池时，池管理器应在基础连接上调用 endRequest。

在以下情况下，池管理器不需要调用 endRequest：

• 连接池缓存PooledConnection个对象
• 当应用程序调用 getConnection 时返回逻辑连接句柄
• 在将 PooledConnection 返回到缓存之前，通过调用 Connection.close 关闭逻辑 Connection。

实现要求：

默认实现是空操作。

抛出：

SQLException - 如果发生错误

自从：

9

参见：

• beginRequest()
• PooledConnection

setShardingKeyIfValid

default boolean setShardingKeyIfValid(ShardingKey  shardingKey, ShardingKey  superShardingKey, int timeout) throws SQL异常 
            

设置并验证此连接的分片键。可以为分片键指定null值。 null 分片键的有效性是特定于供应商的。有关其他信息，请参阅供应商的文档。

API 注意：

此方法验证分片键对 Connection 有效。超时值表示在 setShardingKeyIfValid 返回 false 之前驱动程序应等待 Connection 验证分片键有效的时间。

实现要求：

默认实现将抛出一个 SQLFeatureNotSupportedException 。

参数：

shardingKey - 要针对此连接验证的分片键。分片键可能是null

superShardingKey - 要针对此连接验证的超级分片键。超级分片键可能是 null 。

timeout - 预计完成验证过程的时间（以秒为单位），否则验证过程将中止。值 0 表示验证过程不会超时。

返回：

如果连接有效并且分片键有效并在此连接上设置，则为真；如果分片键无效或超时期限在操作完成之前到期，则为 false。

抛出：

SQLException - 如果在执行此验证时发生错误；指定了 superShardingKey 而没有 shardingKey ；此方法在关闭的 connection 上调用；或者 timeout 值为负。

SQLFeatureNotSupportedException - 如果驱动程序不支持分片

自从：

9

参见：

• ShardingKey
• ShardingKeyBuilder

setShardingKeyIfValid

default boolean setShardingKeyIfValid(ShardingKey  shardingKey, int timeout) throws SQL异常 
            

设置并验证此连接的分片键。可以为分片键指定null值。 null 分片键的有效性是特定于供应商的。有关其他信息，请参阅供应商的文档。

API 注意：

此方法验证分片键对 Connection 有效。超时值表示在 setShardingKeyIfValid 返回 false 之前驱动程序应等待 Connection 验证分片键有效的时间。

实现要求：

默认实现将抛出一个 SQLFeatureNotSupportedException 。

参数：

shardingKey - 要针对此连接验证的分片键。分片键可能是null

timeout - 预计完成验证过程的时间（以秒为单位），否则验证过程将中止。值 0 表示验证过程不会超时。

返回：

如果连接有效并且分片键在此连接上设置有效，则为真；如果分片键无效或超时期限在操作完成之前到期，则为 false。

抛出：

SQLException - 如果在执行此验证时出现错误；此方法在关闭的 connection 上调用；或者 timeout 值为负。

SQLFeatureNotSupportedException - 如果驱动程序不支持分片

自从：

9

参见：

• ShardingKey
• ShardingKeyBuilder

setShardingKey

default void setShardingKey(ShardingKey  shardingKey, ShardingKey  superShardingKey) throws SQL异常 
            

指定与此连接一起使用的 shardingKey 和 superShardingKey

API 注意：

此方法设置指定的分片键，但不需要往返数据库以验证分片键对 Connection 有效。

实现要求：

默认实现将抛出一个 SQLFeatureNotSupportedException 。

参数：

shardingKey - 在此连接上设置的分片键。分片键可能是null

superShardingKey - 在此连接上设置的超级分片键。超级分片键可能是null

抛出：

SQLException - 如果设置分片键时发生错误；此方法在关闭的 connection 上调用；或者在没有shardingKey的情况下指定superShardingKey

SQLFeatureNotSupportedException - 如果驱动程序不支持分片

自从：

9

参见：

• ShardingKey
• ShardingKeyBuilder

setShardingKey

default void setShardingKey(ShardingKey  shardingKey) throws SQL异常 
            

指定与此连接一起使用的 shardingKey

API 注意：

此方法设置指定的分片键，但不需要往返数据库以验证分片键对 Connection 有效。

实现要求：

默认实现将抛出一个 SQLFeatureNotSupportedException 。

参数：

shardingKey - 在此连接上设置的分片键。分片键可能是null

抛出：

SQLException - 如果设置分片键时发生错误；或者在关闭的 connection 上调用此方法

SQLFeatureNotSupportedException - 如果驱动程序不支持分片

自从：

9

参见：

• ShardingKey
• ShardingKeyBuilder