Module  java.sql
软件包  javax.sql

Interface DataSource

  • All Superinterfaces:
    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的实现必须包含一个public no-arg构造函数。

    从以下版本开始：
    1.4

    • 方法详细信息

      • 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

      • getLogWriter

        PrintWriter getLogWriter​()
                  throws SQLException

        检索此DataSource对象的日志记录器。

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

        Specified by:
        getLogWriter接口 CommonDataSource
        结果
        此数据源的日志写入程序，如果禁用日志记录，则为空
        异常
        SQLException - 如果发生数据库访问错误
        从以下版本开始：
        1.4
        另请参见：
        CommonDataSource.setLogWriter(java.io.PrintWriter)

      • setLogWriter

        void setLogWriter​(PrintWriter out)
           throws SQLException

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

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

        Specified by:
        setLogWriter在接口 CommonDataSource
        参数
        out - 新的日志记录器 禁用日志记录，设置为null
        异常
        SQLException - 如果发生数据库访问错误
        从以下版本开始：
        1.4
        另请参见：
        CommonDataSource.getLogWriter()

      • setLoginTimeout

        void setLoginTimeout​(int seconds)
              throws SQLException

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

        Specified by:
        setLoginTimeout在接口 CommonDataSource
        参数
        seconds - 数据源登录时间限制
        异常
        SQLException - 如果发生数据库访问错误。
        从以下版本开始：
        1.4
        另请参见：
        CommonDataSource.getLoginTimeout()

      • getLoginTimeout

        int getLoginTimeout​()
             throws SQLException
        获取此数据源在尝试连接到数据库时可以等待的最长时间（秒）。 值为零表示超时是默认的系统超时，如果有的话; 否则，这意味着没有超时。 当创建一个DataSource对象时，登录超时最初为零。
        Specified by:
        getLoginTimeout在接口 CommonDataSource
        结果
        数据源登录时间限制
        异常
        SQLException - 如果发生数据库访问错误。
        从以下版本开始：
        1.4
        另请参见：
        CommonDataSource.setLoginTimeout(int)

      • createConnectionBuilder

        default ConnectionBuilder createConnectionBuilder​()
                                           throws SQLException
        创建一个新的 ConnectionBuilder实例
        实现要求：
        默认实现将抛出一个 SQLFeatureNotSupportedException
        结果
        已创建的ConnectionBuilder实例
        异常
        SQLException - 如果创建构建器发生错误
        SQLFeatureNotSupportedException - 如果驱动程序不支持分片
        从以下版本开始：
        9
        另请参见：
        ConnectionBuilder