Module java.sql
Package javax.sql

Interface DataSource

所有超级接口:
CommonDataSource, Wrapper
public interface DataSource extends CommonDataSource, Wrapper

连接到此DataSource对象表示的物理数据源的连接工厂。作为DriverManager设施的替代方案，DataSource对象是获取连接的首选方式。实现DataSource接口的对象通常会在基于Java命名和目录（JNDI）API的命名服务中注册。

DataSource接口由驱动程序供应商实现。有三种类型的实现:

  1. 基本实现 -- 生成标准的Connection对象
  2. 连接池实现 -- 生成一个Connection对象，该对象将自动参与连接池。此实现与中间层连接池管理器一起工作。
  3. 分布式事务实现 -- 生成一个Connection对象，可用于分布式事务，并几乎总是参与连接池。此实现与中间层事务管理器以及几乎总是与连接池管理器一起工作。

DataSource对象具有在必要时可以修改的属性。例如，如果数据源移动到不同的服务器，可以更改服务器的属性。好处是，因为数据源的属性可以更改，访问该数据源的任何代码都不需要更改。

通过DataSource对象访问的驱动程序不会向DriverManager注册自身。相反，通过查找操作检索DataSource对象，然后用于创建Connection对象。使用基本实现时，通过DataSource对象获取的连接与通过DriverManager设施获取的连接相同。

DataSource的实现必须包括一个公共无参构造函数。

自1.4版本起:
1.4

  • Method Details

    • getConnection

      Connection getConnection() throws SQLException

      尝试与此DataSource对象表示的数据源建立连接。

      返回:
      数据源的连接
      抛出:
      SQLException - 如果发生数据库访问错误
      SQLTimeoutException - 当驱动程序确定已超过setLoginTimeout方法指定的超时值，并且至少尝试取消当前数据库连接尝试时

    • getConnection

      Connection getConnection(String username, String password) throws SQLException

      尝试与此DataSource对象表示的数据源建立连接。

      参数:
      username - 进行连接的数据库用户
      password - 用户的密码
      返回:
      数据源的连接
      抛出:
      SQLException - 如果发生数据库访问错误
      SQLTimeoutException - 当驱动程序确定已超过setLoginTimeout方法指定的超时值，并且至少尝试取消当前数据库连接尝试时
      自1.4版本起:
      1.4

    • getLogWriter

      PrintWriter getLogWriter() throws SQLException

      检索此DataSource对象的日志写入器。

      日志写入器是一个字符输出流，用于打印此数据源的所有日志和跟踪消息。这包括由此对象的方法打印的消息，由此对象制造的其他对象的方法打印的消息等。打印到特定数据源日志写入器的消息不会打印到与java.sql.DriverManager类关联的日志写入器。创建DataSource对象时，日志写入器最初为null；换句话说，默认情况下日志记录被禁用。

      指定者:
      getLogWriter 在接口 CommonDataSource
      返回:
      此数据源的日志写入器，如果日志记录被禁用，则为null
      抛出:
      SQLException - 如果发生数据库访问错误
      自1.4版本起:
      1.4
      参见:

    • setLogWriter

      void setLogWriter(PrintWriter out) throws SQLException

      将此DataSource对象的日志写入器设置为给定的java.io.PrintWriter对象。

      日志写入器是一个字符输出流，用于打印此数据源的所有日志和跟踪消息。这包括由此对象的方法打印的消息，由此对象制造的其他对象的方法打印的消息等。打印到特定数据源日志写入器的消息不会打印到与java.sql.DriverManager类关联的日志写入器。创建DataSource对象时，日志写入器最初为null；换句话说，默认情况下日志记录被禁用。

      指定者:
      setLogWriter 在接口 CommonDataSource
      参数:
      out - 新的日志写入器；要禁用日志记录，请设置为null
      抛出:
      SQLException - 如果发生数据库访问错误
      自1.4版本起:
      1.4
      参见:

    • setLoginTimeout

      void setLoginTimeout(int seconds) throws SQLException

      设置此数据源在尝试连接到数据库时将等待的最长时间（以秒为单位）。如果值为零，则指定超时为默认系统超时（如果有）；否则，指定没有超时。创建DataSource对象时，登录超时最初为零。

      指定者:
      setLoginTimeout 在接口 CommonDataSource
      参数:
      seconds - 数据源登录时间限制
      抛出:
      SQLException - 如果发生数据库访问错误。
      自1.4版本起:
      1.4
      参见:

    • getLoginTimeout

      int getLoginTimeout() throws SQLException
      获取此数据源在尝试连接到数据库时可以等待的最长时间（以秒为单位）。如果值为零，则超时为默认系统超时（如果有）；否则，表示没有超时。创建DataSource对象时，登录超时最初为零。
      指定者:
      getLoginTimeout 在接口 CommonDataSource
      返回:
      数据源登录时间限制
      抛出:
      SQLException - 如果发生数据库访问错误。
      自1.4版本起:
      1.4
      参见:

    • createConnectionBuilder

      default ConnectionBuilder createConnectionBuilder() throws SQLException
      创建一个新的ConnectionBuilder实例
      实现要求:
      默认实现将抛出一个SQLFeatureNotSupportedException
      返回:
      创建的ConnectionBuilder实例
      抛出:
      SQLException - 如果创建构建器时发生错误
      SQLFeatureNotSupportedException - 如果驱动程序不支持分片
      自9版本起:
      9
      参见: