Jakarta Commons Database Connection Pool

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

参照:
説明

パッケージ

org.apache.commons.dbcp	データベースコネクションプールのための API です。
org.apache.commons.dbcp.cpdsadapter	このパッケージは古い Driver ベースの JDBC の実装に適用するための ConnectionPoolDataSource (CPDS) を実装した1つの public クラスを持ちます。
org.apache.commons.dbcp.jdbc2pool	このパッケージはデータベースコネクションプールの機能を提供する DataSource を実装した1つの public クラスを持ちます。
org.apache.commons.jocl	Java Object Configuration Language は記述された Java オブジェクトをインスタンス化するためののXMLアプリケーションです。

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

対話形式の概要

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

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

Q: しかし PoolingDriver と PoolingDataSource は両方とも 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 が行います。 PoolableConnectionFactory は ConnectionFactory にて生成された Connection を受け取り、 プーリングの振る舞いが実装されたクラスと共にラップします。

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

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

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

PoolingDataSource は Connection の生成と保持に 内部の 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) を参照ください。)

翻訳者:

日置 聡