java.sql
接口 Connection

所有超级接口：

Wrapper

public interface Connection
extends Wrapper

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

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

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

使用 JDBC 2.1 核心 API 创建的新 Connection 对象有一个与之关联的最初为空的类型映射。用户可以为此类型映射中的 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);
 

另请参见：

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

TRANSACTION_NONE

static final int TRANSACTION_NONE

指示事务不受支持的常量。

另请参见：

常量字段值

TRANSACTION_READ_UNCOMMITTED

static final int TRANSACTION_READ_UNCOMMITTED

指示可以发生脏读 (dirty read)、不可重复读和虚读 (phantom read) 的常量。此级别允许被某一事务更改的行在已提交该行所有更改之前被另一个事务读取（“脏读”）。如果所有更改都被回滚，则第二个事务将获取无效的行。

另请参见：

常量字段值

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 SQLException

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

使用返回的 Statement 对象创建的结果集在默认情况下类型为 TYPE_FORWARD_ONLY，并带有 CONCUR_READ_ONLY 并发级别。已创建结果集的可保存性可调用 getHoldability() 确定。

返回：

一个新的默认 Statement 对象

抛出：

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

prepareStatement

PreparedStatement prepareStatement(String sql)
                                   throws SQLException

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

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

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

使用返回的 PreparedStatement 对象创建的结果集在默认情况下类型为 TYPE_FORWARD_ONLY，并带有 CONCUR_READ_ONLY 并发级别。已创建结果集的可保存性可调用 getHoldability() 确定。

参数：

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

返回：

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

抛出：

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

prepareCall

CallableStatement prepareCall(String sql)
                              throws SQLException

创建一个 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 SQLException

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

参数：

sql - 可以包含一个或多个 '?' 参数占位符的 SQL 语句

返回：

此语句的本机形式

抛出：

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

setAutoCommit

void setAutoCommit(boolean autoCommit)
                   throws SQLException

将此连接的自动提交模式设置为给定状态。如果连接处于自动提交模式下，则它的所有 SQL 语句将被执行并作为单个事务提交。否则，它的 SQL 语句将聚集到事务中，直到调用 commit 方法或 rollback 方法为止。默认情况下，新连接处于自动提交模式。

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

• 对于 DML 语句（比如 Insert、Update 或 Delete）和 DDL 语句，语句在执行完毕时完成。
• 对于 Select 语句，语句在关联结果集关闭时完成。
• 对于 CallableStatement 对象或者返回多个结果的语句，语句在所有关联结果集关闭并且已获得所有更新计数和输出参数时完成。

注：如果在事务和自动提交模式更改期间调用此方法，则提交该事务。如果调用 setAutoCommit 而自动提交模式未更改，则该调用无操作（no-op）。

参数：

autoCommit - 为 true 表示启用自动提交模式；为 false 表示禁用自动提交模式

抛出：

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

另请参见：

getAutoCommit()

getAutoCommit

boolean getAutoCommit()
                      throws SQLException

获取此 Connection 对象的当前自动提交模式。

返回：

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

抛出：

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

另请参见：

getAutoCommit(), setAutoCommit(boolean)

commit

void commit()
            throws SQLException

使所有上一次提交/回滚后进行的更改成为持久更改，并释放此 Connection 对象当前持有的所有数据库锁。此方法只应该在已禁用自动提交模式时使用。

抛出：

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

另请参见：

setAutoCommit(boolean)

rollback

void rollback()
              throws SQLException

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

抛出：

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

另请参见：

setAutoCommit(boolean)

close

void close()
           throws SQLException

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

在已经关闭的 Connection 对象上调用 close 方法无操作 (no-op)。

建议最好在调用 close 方法之前，应用程序显式提交或回滚一个活动事务。如果调用 close 方法并且有一个活动事务，那么结果将由实现定义。

抛出：

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

isClosed

boolean isClosed()
                 throws SQLException

查询此 Connection 对象是否已经被关闭。如果在连接上调用了 close 方法或者发生某些严重的错误，则连接被关闭。只有在调用了 Connection.close 方法之后被调用时，此方法才保证返回 true。

通常不能调用此方法确定到数据库的连接是有效的还是无效的。通过捕获在试图进行某一操作时可能抛出的异常，典型的客户端可以确定某一连接是无效的。

返回：

如果此 Connection 对象是关闭的，则返回 true；如果它仍然处于打开状态，则返回 false

抛出：

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

getMetaData

DatabaseMetaData getMetaData()
                             throws SQLException

获取一个 DatabaseMetaData 对象，该对象包含关于此 Connection 对象所连接的数据库的元数据。元数据包括关于数据库的表、受支持的 SQL 语法、存储过程、此连接功能等等的信息。

返回：

此 Connection 对象的一个 DatabaseMetaData 对象

抛出：

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

setReadOnly

void setReadOnly(boolean readOnly)
                 throws SQLException

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

注：此方法不能在事务处理期间调用。

参数：

readOnly - 为 true 表示启用只读模式；为 false 表示禁用只读模式

抛出：

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

isReadOnly

boolean isReadOnly()
                   throws SQLException

查询此 Connection 对象是否处于只读模式。

返回：

如果此 Connection 对象是只读的，则返回 true；否则返回 false

抛出：

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

setCatalog

void setCatalog(String catalog)
                throws SQLException

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

如果驱动程序不支持这些目录，那么它将直接忽略此请求。

参数：

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

抛出：

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

另请参见：

getCatalog()

getCatalog

String getCatalog()
                  throws SQLException

获取此 Connection 对象的当前目录名称。

返回：

当前目录名称；如果不存在，则返回 null

抛出：

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

另请参见：

setCatalog(java.lang.String)

setTransactionIsolation

void setTransactionIsolation(int level)
                             throws SQLException

试图将此 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 SQLException

获取此 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 SQLException

获取此 Connection 对象上的调用报告的第一个警告。如果有多个警告，则后续警告将被链接到第一个警告，可以通过对之前获得的警告调用 SQLWarning.getNextWarning 方法获取。

不可以在关闭的连接上调用此方法，这样做将导致抛出 SQLException。

注：后续警告将被链接到此 SQLWarning。

返回：

第一个 SQLWarning 对象；如果不存在，则返回 null

抛出：

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

另请参见：

SQLWarning

clearWarnings

void clearWarnings()
                   throws SQLException

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

抛出：

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

createStatement

Statement createStatement(int resultSetType,
                          int resultSetConcurrency)
                          throws SQLException

创建一个 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 SQLException

创建一个 PreparedStatement 对象，该对象将生成具有给定类型和并发性的 ResultSet 对象。此方法与上述 prepareStatement 方法相同，但它允许重写默认结果集类型和并发性。已创建结果集的可保存性可调用 getHoldability() 确定。

参数：

sql - 一个 String 对象，它是将被发送到数据库的 SQL 语句，可以包含一个或多个 '?' IN 参数

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

resultSetConcurrency - 并发类型，它是 ResultSet.CONCUR_READ_ONLY 或 ResultSet.CONCUR_UPDATABLE 之一

返回：

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

抛出：

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

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

从以下版本开始：

1.2

prepareCall

CallableStatement prepareCall(String sql,
                              int resultSetType,
                              int resultSetConcurrency)
                              throws SQLException

创建一个 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 之一

返回：

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

抛出：

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

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

从以下版本开始：

1.2

getTypeMap

Map<String,Class<?>> getTypeMap()
                                throws SQLException

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

返回：

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

抛出：

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

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

从以下版本开始：

1.2

另请参见：

setTypeMap(java.util.Map>)

setTypeMap

void setTypeMap(Map<String,Class<?>> map)
                throws SQLException

将给定的 TypeMap 对象安装为此 Connection 对象的类型映射。该映射将用于 SQL 结构类型和独特类型的自定义映射。

参数：

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

抛出：

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

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

从以下版本开始：

1.2

另请参见：

getTypeMap()

setHoldability

void setHoldability(int holdability)
                    throws SQLException

将使用此 Connection 对象创建的 ResultSet 对象的默认可保存性 (holdability) 更改为给定可保存性。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 SQLException

获取使用此 Connection 对象创建的 ResultSet 对象的当前可保存性。

返回：

可保存性，它是 ResultSet.HOLD_CURSORS_OVER_COMMIT 或 ResultSet.CLOSE_CURSORS_AT_COMMIT 之一

抛出：

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

从以下版本开始：

1.4

另请参见：

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

setSavepoint

Savepoint setSavepoint()
                       throws SQLException

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

如果在活动事务范围之外调用 setSavepoint，则将在新创建的保存点上启动事务。

返回：

新的 Savepoint 对象

抛出：

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

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

从以下版本开始：

1.4

另请参见：

Savepoint

setSavepoint

Savepoint setSavepoint(String name)
                       throws SQLException

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

如果在活动事务范围之外调用 setSavepoint，则将在新创建的保存点上启动事务。

参数：

name - 包含保存点名称的 String

返回：

新的 Savepoint 对象

抛出：

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

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

从以下版本开始：

1.4

另请参见：

Savepoint

rollback

void rollback(Savepoint savepoint)
              throws SQLException

取消所有设置给定 Savepoint 对象之后进行的更改。

此方法只应该在已禁用自动提交时使用。

参数：

savepoint - 要回滚到的 Savepoint 对象

抛出：

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

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

从以下版本开始：

1.4

另请参见：

Savepoint, rollback()

releaseSavepoint

void releaseSavepoint(Savepoint savepoint)
                      throws SQLException

从当前事务中移除指定的 Savepoint 和后续 Savepoint 对象。在已移除保存点之后，对该保存点的任何引用都会导致抛出 SQLException。

参数：

savepoint - 将移除的 Savepoint 对象

抛出：

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

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

从以下版本开始：

1.4

createStatement

Statement createStatement(int resultSetType,
                          int resultSetConcurrency,
                          int resultSetHoldability)
                          throws SQLException

创建一个 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 SQLException

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

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

参数：

sql - 一个 String 对象，它是将被发送到数据库的 SQL 语句，可以包含一个或多个 '?' IN 参数

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

返回：

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

抛出：

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

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法，或者对于指定结果集类型、结果集可保存性和结果集并发性，此方法不受支持。

从以下版本开始：

1.4

另请参见：

ResultSet

prepareCall

CallableStatement prepareCall(String sql,
                              int resultSetType,
                              int resultSetConcurrency,
                              int resultSetHoldability)
                              throws SQLException

创建一个 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

返回：

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

抛出：

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

SQLFeatureNotSupportedException - 如果 JDBC 驱动程序不支持此方法，或者对于指定结果集类型、结果集可保存性和结果集并发性，此方法不受支持。

从以下版本开始：

1.4

另请参见：

ResultSet

prepareStatement

PreparedStatement prepareStatement(String sql,
                                   int autoGeneratedKeys)
                                   throws SQLException

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

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

使用返回的 PreparedStatement 对象创建的结果集在默认情况下类型为 TYPE_FORWARD_ONLY，并带有 CONCUR_READ_ONLY 并发级别。已创建结果集的可保存性可调用 getHoldability() 确定。

参数：

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

autoGeneratedKeys - 指示是否应该返回自动生成的键的标志，它是 Statement.RETURN_GENERATED_KEYS 或 Statement.NO_GENERATED_KEYS 之一

返回：

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

抛出：

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

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

从以下版本开始：

1.4

prepareStatement

PreparedStatement prepareStatement(String sql,
                                   int[] columnIndexes)
                                   throws SQLException

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

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

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

使用返回的 PreparedStatement 对象创建的结果集在默认情况下类型为 TYPE_FORWARD_ONLY，并带有 CONCUR_READ_ONLY 并发级别。已创建结果集的可保存性可调用 getHoldability() 确定。

参数：

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

columnIndexes - 列索引数组，这些索引指示应该从一个或多个插入行中返回的那些列

返回：

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

抛出：

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

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

从以下版本开始：

1.4

prepareStatement

PreparedStatement prepareStatement(String sql,
                                   String[] columnNames)
                                   throws SQLException

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

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

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

使用返回的 PreparedStatement 对象创建的结果集在默认情况下类型为 TYPE_FORWARD_ONLY，并带有 CONCUR_READ_ONLY 并发级别。已创建结果集的可保存性可调用 getHoldability() 确定。

参数：

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

columnNames - 列名称数组，这些名称指示应该从一个或多个插入行中返回的那些列

返回：

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

抛出：

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

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

从以下版本开始：

1.4

createClob

Clob createClob()
                throws SQLException

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

返回：

实现 Clob 接口的对象

抛出：

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

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

从以下版本开始：

1.6

createBlob

Blob createBlob()
                throws SQLException

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

返回：

实现 Blob 接口的对象

抛出：

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

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

从以下版本开始：

1.6

createNClob

NClob createNClob()
                  throws SQLException

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

返回：

实现 NClob 接口的对象

抛出：

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

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

从以下版本开始：

1.6

createSQLXML

SQLXML createSQLXML()
                    throws SQLException

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

返回：

实现 SQLXML 接口的对象

抛出：

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

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

从以下版本开始：

1.6

isValid

boolean isValid(int timeout)
                throws SQLException

如果连接尚未关闭并且仍然有效，则返回 true。驱动程序将提交一个关于该连接的查询，或者使用其他某种能确切验证在调用此方法时连接是否仍然有效的机制。

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

参数：

timeout - 等待用来验证连接是否完成的数据库操作的时间，以秒为单位。如果在操作完成之前超时期满，则此方法返回 false。0 值表示不对数据库操作应用超时值。

返回：

如果连接有效，则返回 true，否则返回 false

抛出：

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

从以下版本开始：

1.6

另请参见：

DatabaseMetaData.getClientInfoProperties()

setClientInfo

void setClientInfo(String name,
                   String value)
                   throws SQLClientInfoException

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

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

驱动程序存储数据库中合适位置上指定的值。例如，在特殊注册表 (special register)、会话参数 (session parameter) 或者系统表 (system table) 列中。为了提高效率，驱动程序可以将设置数据库中的值推迟到下一次执行语句或者准备执行语句时。除了在数据库中的适当位置存储客户端信息之外，这些方法不能以任何方式改变连接的行为。为这些方法提供的值只能用于计数、诊断和调试目的。

如果指定的客户端属性名称不被驱动程序所识别，那么该驱动程序将生成一个警告。

如果为此方法指定的值大于该属性的最大长度，则驱动程序可能截取该值并生成一个警告，或者生成一个 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 SQLException

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

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

参数：

name - 要获取的客户端信息属性的名称

返回：

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

抛出：

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

从以下版本开始：

1.6

另请参见：

DatabaseMetaData.getClientInfoProperties()

getClientInfo

Properties getClientInfo()
                         throws SQLException

返回一个列表，它包含驱动程序支持的每个客户端信息属性的名称和当前值。如果客户端信息属性尚未设置并且没有默认值，那么客户端信息属性的值为 null。

返回：

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

抛出：

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

从以下版本开始：

1.6

createArrayOf

Array createArrayOf(String typeName,
                    Object[] elements)
                    throws SQLException

创建 Array 对象的工厂方法。

注：当使用 createArrayOf 创建映射到基本数据类型的数组对象时，则 Array 对象是基本数据类型数组还是 Object 数组将由实现来定义。

注：JDBC 驱动程序负责将元素 Object 数组映射到 java.sql.Types 中为 Object 的给定类定义的默认 JDBC SQL 类型。默认映射关系是在 JDBC 规范的附录 B 中指定的。如果得到的 JDBC 类型对于给定 typeName 而言不是合适的类型，则抛出 SQLException 还是驱动程序支持得到的转换将由实现来定义。

参数：

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

elements - 填充所返回对象的元素

返回：

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

抛出：

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

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

从以下版本开始：

1.6

createStruct

Struct createStruct(String typeName,
                    Object[] attributes)
                    throws SQLException

创建 Struct 对象的工厂方法。

参数：

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

attributes - 填充所返回对象的属性

返回：

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

抛出：

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

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

从以下版本开始：

1.6

版权所有 2007 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策。