モジュール java.sql
パッケージ javax.sql

インタフェースDataSource

すべてのスーパー・インタフェース:
CommonDataSource, Wrapper
public interface DataSource
extends CommonDataSource, Wrapper

このDataSourceオブジェクトが表す物理データ・ソースへの接続に対するファクトリです。 DriverManager機能の代わりに、DataSourceオブジェクトが接続を得るための適切な手段となります。 DataSourceインタフェースを実装するオブジェクトは、通常、Java Naming and Directory (JNDI) APIに基づいてネーミング・サービスに登録されます。

DataSourceインタフェースは、ドライバ・ベンダーによって実装されています。 実装には3種類あります。

  1. 基本実装 -- 標準Connectionオブジェクトを生成する
  2. 接続プール実装 -- 自動的に接続プールに参加するConnectionオブジェクトを生成する。 この実装は中間層の接続プール管理プログラムとともに動作する。
  3. 分散トランザクション実装 -- 分散トランザクションで使用され、ほとんどの場合に常に接続プールに参加するConnectionオブジェクトを生成する。 この実装は中間層のトランザクション・マネージャと、多くの場合は常に接続プール管理プログラムとともに動作する。

DataSourceオブジェクトは、必要に応じて変更可能なプロパティを保持します。 たとえば、データ・ソースが別のサーバーへ移動した場合、そのサーバーについてのプロパティを変更できます。 データ・ソースのプロパティを変更できるため、データ・ソースにアクセスするコードを変更する必要がないという利点があります。

DataSourceオブジェクトを介してアクセスされたドライバは、自分自身をDriverManagerで登録しません。 むしろ、DataSourceオブジェクトはルックアップ操作で検索され、Connectionオブジェクトの作成に使用されます。 基本実装では、DataSourceオブジェクトにより取得された接続は、DriverManager機能により取得した接続と同じものになります。

DataSourceの実装には引数なしのpublicコンストラクタが含まれている必要があります。

導入されたバージョン:
1.4

  • メソッドのサマリー

    修飾子と型 メソッド 説明
    default ConnectionBuilder createConnectionBuilder()
    新しいConnectionBuilderインスタンスを作成
    Connection getConnection()
    このDataSourceオブジェクトが表すデータ・ソースへの接続の確立を試みます。
    Connection getConnection​(String username, String password)
    このDataSourceオブジェクトが表すデータ・ソースへの接続の確立を試みます。
    int getLoginTimeout()
    データベースへの接続試行中に、このデータ・ソースが待機する最長時間(秒)を取得します。
    PrintWriter getLogWriter()
    このDataSourceオブジェクトのログ・ライターを取得します。
    void setLoginTimeout​(int seconds)
    データベースへの接続試行中に、このデータ・ソースが待機する最長時間(秒)を指定します。
    void setLogWriter​(PrintWriter out)
    このDataSourceオブジェクトのログ・ライターをjava.io.PrintWriterオブジェクトに設定します。

    インタフェース javax.sql.CommonDataSourceで宣言されたメソッド

    createShardingKeyBuilder, getParentLogger

    インタフェース java.sql.Wrapperで宣言されたメソッド

    isWrapperFor, unwrap

  • メソッドの詳細

    • 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オブジェクトが作成されると、ログ・ライターはnullに初期化されます。つまり、デフォルトではロギングは無効です。

      定義:
      インタフェースCommonDataSource内のgetLogWriter
      戻り値:
      このデータ・ソースのログ・ライター。ログの取得が無効の場合はnull
      例外:
      SQLException - データベース・アクセス・エラーが発生した場合
      導入されたバージョン:
      1.4
      関連項目:
      CommonDataSource.setLogWriter(java.io.PrintWriter)

    • setLogWriter

      void setLogWriter​(PrintWriter out) throws SQLException

      このDataSourceオブジェクトのログ・ライターをjava.io.PrintWriterオブジェクトに設定します。

      ログ・ライターとは、このデータ・ソースに対するすべてのロギング・メッセージやトレース・メッセージの出力先となるキャラクタ出力ストリームのことです。 このオブジェクトのメソッドによって出力されたメッセージや、このオブジェクトが作成した他のオブジェクトのメソッドによって出力されたメッセージなども含まれます。 データ・ソース固有のログ・ライターに表示されたメッセージは、java.sql.DriverManagerクラスに関連付けられたログ・ライターには出力されません。 DataSourceオブジェクトが作成されると、ログ・ライターはnullに初期化されます。つまり、デフォルトではロギングは無効です。

      定義:
      インタフェースCommonDataSource内のsetLogWriter
      パラメータ:
      out - 新しいログ・ライター。ロギングを無効にする場合はnullに設定する
      例外:
      SQLException - データベース・アクセス・エラーが発生した場合
      導入されたバージョン:
      1.4
      関連項目:
      CommonDataSource.getLogWriter()

    • setLoginTimeout

      void setLoginTimeout​(int seconds) throws SQLException

      データベースへの接続試行中に、このデータ・ソースが待機する最長時間(秒)を指定します。 値が0のとき、デフォルトのシステム・タイムアウトが設定されている場合はその値になります。そうでない場合はタイムアウトしないことを意味します。 DataSourceオブジェクトが作成されると、ログイン・タイムアウトは0に初期化されます。

      定義:
      インタフェースCommonDataSource内のsetLoginTimeout
      パラメータ:
      seconds - データ・ソースのログイン制限時間
      例外:
      SQLException - データベース・アクセス・エラーが発生した場合。
      導入されたバージョン:
      1.4
      関連項目:
      CommonDataSource.getLoginTimeout()

    • getLoginTimeout

      int getLoginTimeout() throws SQLException
      データベースへの接続試行中に、このデータ・ソースが待機する最長時間(秒)を取得します。 値が0のとき、デフォルトのシステム・タイムアウトが設定されている場合はその値になります。そうでない場合はタイムアウトしないことを意味します。 DataSourceオブジェクトが作成されると、ログイン・タイムアウトは0に初期化されます。
      定義:
      インタフェースCommonDataSource内のgetLoginTimeout
      戻り値:
      データ・ソースのログイン制限時間
      例外:
      SQLException - データベース・アクセス・エラーが発生した場合。
      導入されたバージョン:
      1.4
      関連項目:
      CommonDataSource.setLoginTimeout(int)

    • createConnectionBuilder

      default ConnectionBuilder createConnectionBuilder() throws SQLException
      新しいConnectionBuilderインスタンスを作成
      実装要件:
      デフォルトの実装では、SQLFeatureNotSupportedExceptionがスローされます。
      戻り値:
      作成されたConnectionBuilderインスタンス
      例外:
      SQLException - ビルダーの作成中にエラーが発生した場合
      SQLFeatureNotSupportedException - 運転手がシャーディングをサポートしていない場合
      導入されたバージョン:
      9
      関連項目:
      ConnectionBuilder