パッケージ org.apache.commons.dbcp

データベースコネクションプールのための API です。

参照:
          説明

インタフェースの概要
ConnectionFactory Connection を生成するための抽象ファクトリインターフェイスです。
 

クラスの概要
AbandonedConfig 破棄されたデータベースコネクションを処理するための設定情報です。
AbandonedObjectPool JDBC コネクションを追跡し、破棄されたもの回復することのできる Jakarta-Commons ObjectPool の実装です。
AbandonedTrace データベースコネクションを回復するために追跡し、破棄されたデータベースコネクションの情報をレポートします。
BasicDataSource JavaBeans プロパティを介して設定される javax.sql.DataSource の基本的な実装です。
BasicDataSourceFactory 指定された ReferenceRefAddr の値(これは BasicDataSource の bean プロパティと一致する必要があります)に基づいて設定された BasicDataSource のインスタンスを生成する JNDI オブジェクトファクトリです。
DataSourceConnectionFactory DataSource をベースにした ConnectionFactory の実装です。
DelegatingCallableStatement 基盤となる CallableStatement の委譲を行う実装です。
DelegatingConnection 基盤となる Connection の委譲を行う実装です。
DelegatingPreparedStatement 基盤となる PreparedStatement の委譲を行う実装です。
DelegatingResultSet 基盤となる ResultSet の委譲を行う実装です。
DelegatingStatement 基盤となる Statement の委譲を行う実装です。
DriverConnectionFactory Driver をベースにした ConnectionFactory の実装です。
DriverManagerConnectionFactory DriverManager をベースにした ConnectionFactory の実装です。
PoolableConnection 自身がクローズされる際に内部のコネクションをクローズせず、自身を ObjectPool に返す、内部の Connection に処理を委託する Connection です。
PoolableConnectionFactory PoolableConnection を生成する PoolableObjectFactory です。
PoolablePreparedStatement PreparedStatement のプールを実現するために PoolingConnection と協力して動作する DelegatingPreparedStatement です。
PoolingConnection PreparedStatement をプールする DelegatingConnection です。
PoolingDataSource 指定された ObjectPool から Connection を取得するシンプルな DataSource の実装です。
PoolingDriver 登録された ObjectPool から Connection を取得する Driver の実装です。
 

例外の概要
DbcpException JDK 1.4 の"元となる原因"のパターンを(1.4の実行環境を必要とせずに)使用して SQLException をラップする RuntimeException のサブクラスです。
 

パッケージ org.apache.commons.dbcp の説明

データベースコネクションプールのための API です。

対話形式の概要

Q: どのようにして DBCP パッケージを使えばよいのですか?

A: DBCP プールにアクセスする方法は主に Driver を使う方法と DataSource を使う方法の2種類です。 PoolingDriver または PoolingDataSource のインスタンスを作成し、利用することができます。. When using one of these これらのうちいずれかのインターフェースを使用することにより一般的な方法で JDBC オブジェクトを使用することができます。 Connection を閉じる場合には単純にプールに対してこれを返してください。

Q: しかし PoolingDriverPoolingDataSource は両方とも ObjectPool を入力されることが想定されています。 これはどこから持ってくればよいのでしょうか?

A: ObjectPool インターフェースは in the org.apache.commons.pool パッケージ(Commons-Pool)で定義されています。 org.apache.commons.pool.impl パッケージには対となる実装があり、独自の実装を作成すること可能です。

Q: OK、コネクションプーリングに適当と思われる ObjectPool の実装を見つけることができました。 しかし、これは PoolableObjectFactory を要求します。 これには何を使用すればよいのでしょうか?

A: DBCP パッケージはそのためのクラス PoolableConnectionFactory を提供しています。 It implements the factory and lifecycle methods of これは Connection のための PoolableObjectFactory のファクトリとライフサイクルに関するメソッドを実装しています。 しかし実際のデータベース Connection の生成はこれ自身ではなく ConnectionFactory が行います。 PoolableConnectionFactoryConnectionFactory にて生成された Connection を受け取り、 プーリングの振る舞いが実装されたクラスと共にラップします。

いくつかの ConnectionFactory の実装が提供されます -- 1つはコネクションの生成に DriverManager を使用し (DriverManagerConnectionFactory)、 1つはコネクションの生成に Driver を使用し (DriverConnectionFactory)、 もう1つはコネクションの生成に DataSource を使用します (DataSourceConnectionFactory)。

Q: 利用する準備はできたように思いますが、もう一度通して説明してもらえますか?

A: はい。 Connection をプールする DataSource を生成する、 または、プールする ConnectionDriverManager から取得する仮定しましょう。 この場合、 PoolingDataSource を生成します。

PoolingDataSourceConnection の生成と保持に 内部の ObjectPool を使用します。

ObjectPool を生成するためには、実際に Connection を生成する PoolableObjectFactory が必要です。 これは PoolableConnectionFactory を必要とします。

PoolableConnectionFactory を生成するためには以下の2つのものが必要です:

  1. 実際のデータベースの Connection を取得することのできる ConnectionFactory
  2. Connection を保持するために使用するファクトリを持たない空の ObjectPool
    ObjectPool を使用すれば 自動的に PoolableObjectFactory のプールとして登録されます。
オプションとして、各 Connection 毎に PreparedStatement をプールするための KeyedObjectPool を生成するための KeyedObjectPoolFactory を利用することもできます。

実際のコードは以下のようになります:

GenericObjectPool connectionPool = new GenericObjectPool(null);
DriverManagerConnectionFactory connectionFactory = new DriverConnectionFactory("jdbc:some:connect:string",null);
PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,connectionPool,null,null,false,true);
PoolingDataSource dataSource = new PoolingDataSource(connectionPool);

PoolingDriver を生成する場合も最後の行の DataSource のインスタンス化の部分以外は同じです。 代わりに PoolingDriver を生成し connectionPool を登録します。 例をあげると以下のようになります:

GenericObjectPool connectionPool = new GenericObjectPool(null);
DriverManagerConnectionFactory connectionFactory = new DriverConnectionFactory("jdbc:some:connect:string",null);
PoolableConnectionFactory poolableConnectionFactory = new PoolableConnectionFactory(connectionFactory,connectionPool,null,null,false,true);
PoolingDriver driver = new PoolingDriver();
driver.registerPool("example",connectionPool);

PoolingDriver が生成される時にそれ自身に DriverManager を登録するため、(登録の際に使用した "example" を使って)以下のような通常の方法で DriverManager から Connection を生成することができます:

Connection conn = DriverManager.getConnection("jdbc:apache:commons:dbcp:example");

Q: なんだか複雑そうですが、簡単な方法はありませんか?

A: PoolingDriver を使用すれば必ずしもこの設定をコード内で行う必要はありません。 代わりにコネクションプールを定義する JOCL ドキュメント を準備すれば実行時に PoolingDriver が読み込みます。

PoolingDriver が まだ登録されていないプールから Connection を取得しようとした場合、 プールの設定内から指定された名前のリソースを探し、そのプールを生成します。

"/eg" という名前のプールを JOCL ドキュメントにて作成する場合を例に挙げます。 このプールに接続するための文字列(URL)は "jdbc:apache:commons:dbcp:/eg" になります。 この設定を行うためにはプールのための JOCL の記述を行った resource を(クラスパス内のファイルとして)作成する必要があります。 この JOCL ドキュメントにはプールの取得元となる PoolableConnectionFactory の設定を記述します。 例は以下のようになります:

<object class="org.apache.commons.dbcp.PoolableConnectionFactory" xmlns="http://apache.org/xml/xmlns/jakarta/commons/jocl">
   <!-- (コンストラクタの)最初の引数となる ConnectionFactory -->
   <object class="org.apache.commons.dbcp.DriverManagerConnectionFactory">
      <string value="jdbc:some:connect:string"/>
      <object class="java.util.Properties" null="true"/>
   </object>
   <!-- (コンストラクタの)2番目の引数となる ObjectPool -->
   <object class="org.apache.commons.pool.impl.GenericObjectPool">
      <object class="org.apache.commons.pool.PoolableObjectFactory" null="true"/>
      <int value="10"/> <!-- アクティブなコネクションの最大数 -->
      <byte value="1"/> <!-- コネクションが使い尽くされている場合の処理, 0 = 失敗, 1 = 待機, 2 = 新たに生成 -->
      <long value="2000"/> <!-- 最長待機時間 -->
      <int value="10"/> <!-- アイドル状態のコネクションの最大数 -->
      <boolean value="false"/> <!-- コネクションを取得するときにテストするか -->
      <boolean value="false"/> <!-- コネクションを返すときにテストするか -->
      <long value="10000"/> <!-- プール内オブジェクト排除スレッドの実行間隔 -->
      <int value="5"/> <!-- 排除スレッドが一度のチェックで対象とするコネクションの数 -->
      <long value="5000"/> <!-- 排除対象となるまでの最短アイドル時間 -->
      <boolean value="true"/> <!-- アイドル状態のコネクションのテストを行うか -->
   </object>
   <!-- (コンストラクタの)3番目の引数となる KeyedObjectPoolFactory -->
   <object class="org.apache.commons.pool.StackKeyedObjectPoolFactory">
      <int value="5"/> <!-- アイドル状態のコネクションの最大数 -->
   </object>
   <string value="SELECT COUNT(*) FROM DUAL"/> <;!-- チェックに使用されるクエリー -->
   <boolean value="false"/> <!-- デフォルトで読み込み専用にするか -->
   <boolean value="true"/> <!-- デフォルトでオートコミットにするか -->
</object>

このファイルを eg.jocl という名前でクラスパスの参照できる場所に配置すれば PoolingDriver は自動的にこのファイルを検索します。 後は PoolingDriver を(jdbc.drivers プロパティなどで)登録すれば DriverManager を使った以下のような一般的な方法で Connection を生成することができます:

Connection conn = DriverManager.getConnection("jdbc:apache:commons:dbcp:/eg");

(スラッシュ("/")を付けなかった場合には定義ファイルをクラスパス内の org/apache/commons/dbcp/PoolingDriver/eg.jocl に配置しなくてはならなくなります。 詳細に関しては Class.getResource(java.lang.String) を参照ください。)

翻訳者:
日置 聡


このドキュメントは、Ja-Jakartaにより訳されました。 コメントがある場合は report@jajakarta.orgまでお願いします。
Translated into Japanese by jajakarta.org. The original page is here.
Copyright (c) 2002-2003 - Apache Software Foundation