Torque - Jdbc2 Connection Pool

This document is only relevant for Torque-3.0b3 and higher versions. For instructions on configuring torque's built-in connection pool in earlier versions see the runtime configuration section of the tutorial.

この文書は Torque-3.0b3 およびそれ以降のバージョンにだけ関連しています。それ以前のバージョンに組み込まれている接続プール機能の使用方法については、チュートリアルのランタイムコンフィグレーションの章を見てください

Starting with Torque-3.0b3, torque no longer requires use of a built-in pool. Torque's old pool has been updated to be a javax.sql.DataSource implementation so that any connection pool implementing the DataSource can be used in its place. Torque now expects a factory that can return a DataSource and can be configured using torque's configuration file.

Torque-3.0b3からは、もはや組み込まれたプールの使用を必要としません。Torqueの古いプール機能は、javax.sql.DataSourceの実装に更新されました。そしてDataSourceを実装すれば、その場でどんな接続プールでも使用可能になったのです。Torqueは今DataSourceを返すことができ、Torqueのコンフィギュレーションファイルを使用してコンフィギュレーションすることができるファクトリとなることを見込んでいます

Torque provides two special purpose factories as well as a general factory that uses jndi to retrieve the DataSource. The first factory discussed below uses the updated version of torque's old pool and the second uses the more full featured pool available in the commons.dbcp package. The jndi factory looks up a DataSource bound to jndi; it also provides a simple property file based way to configure and deploy most DataSource's, though in many cases a pool may already be bound to jndi and torque only needs to use it.

TorqueはDataSourceを検索するためにjndiを使用する一般的なファクトリと同じように2つの特別な目的のファクトリを提供します。下で話する第1のファクトリは、torqueの古いプール機能が更新されたバージョンを使用しています。そして、2つ目のファクトリはcommons.dbcpパッケージにおいて利用可能で、より多くの注目を浴びているプールを使用します。jndiファクトリはjndiに結びついたDataSourceを探します; それは、またほとんどのDataSourceのコンフィギュレーションをし、デプロイするための方法に基づいた単純なプロパティファイルを提供します。しかしながら、多くの場合、プールはjndiに既に結び付けられている可能性もありますし、Torqueがそれを単に使用する必要があるのかもしれません。

Before going over how to configure the factories which will take up most the content of this document, there is one other configuration that needs covered: adapters.

この文書の内容の大部分を占めていると思われるファクトリのコンフィギュレーションの方法へ行く前にニーズをカバーしているもう一つのコンフィギュレーションがあります。アダプターです。

Database Adapters

Previously, Torque provided an internal map between many Drivers and a set of adapter classes which are used to account for differences among databases. This arrangement is no longer possible using DataSource, so the adapter must be given in the configuration. In all examples that follow we will use the handle, bookstore. This is the name attribute that is used in the <database> tag in the schema.xml. If the name attribute is not used, then the handle would be 'default'. The adapter property is given as:

以前に、Torqueは多くのドライバーと1セットのアダプタークラスの間の内部の図を提供していましたが、それはデータベース中の違いを説明するために使用されていました。その仕組みはDataSourceの使用によってもはや使えなくなりました。そしてそのアダプターはコンフィギュレーションにとって代わったに違いありません。以下に続く全ての例の中ではハンドル（bookstore）を使用します。これはschema.xmlの中のデータベースタグの中で使用されるname属性です。もしname属性が使われなかったら、ハンドルは'default'になります。アダプターのプロパティは次のように与えられます:

torque.database.bookstore.adapter=mysql

The valid values are:

有効な値は次のとおりです:

as400
db2app
db2net
cloudscape
hypersonic

interbase
instantdb
mssql
mysql
oracle

postgresql
sapdb
sybase
weblogic.

TorqueDataSourceFactory

This factory gives a DataSource version of the old built-in pool. The old pool was extracted and updated and is now part of the commons-jdbc2pool package. TorqueDataSourceFactory provides an easy way to configure this pool and it assumes you will have a jdbc Driver class providing the physical database connections. First you must let torque know you are using this factory.

このファクトリは、古い組み込まれたプールのDataSourceバージョンを与えます。古いプールは抽出され更新され、今はcommons-jdbc2poolパッケージの一部になっています。TorqueDataSourceFactoryはこのプールをコンフィギュレーションする簡単な方法を提供しています。しかしながら、それは物理的なデータベース接続を提供するjdbcドライバークラスがあるということが前提となります。まずはじめにやらないといけないことはこのファクトリを使用していることをTorqueに知らせることです。

torque.dsfactory.bookstore.factory=org.apache.torque.dsfactory.TorqueDataSourceFactory

Then there are two sets of properties related to the pool configuration and settings for making the connection to the database.

それから、データベースへの接続を行なうためのセッティングとプールコンフィギュレーションに関係する2セットのプロパティがあります

torque.dsfactory.bookstore.pool.defaultMaxConnections=10
torque.dsfactory.bookstore.pool.maxExpiryTime=3600
torque.dsfactory.bookstore.pool.connectionWaitTimeout=10

torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.bookstore.connection.url = jdbc:mysql://localhost:3306/bookstore
torque.dsfactory.bookstore.connection.user = root
torque.dsfactory.bookstore.connection.password = 1234

The TorqueClassicDataSource used with this factory has a few other configuration options which could be set above in the "pool" section, but the three shown are enough for most cases. Please see the javadoc for the class for more information.

このファクトリと共に使用されるTorqueClassicDataSourceには、"プール"の所で上位にセットされるかも知れないコンフィギュレーションオプションが少しあります。しかし、上で示した3つの例は、ほとんどの場合にとって十分です。より多くの情報を得るために、そのクラスに関しては、javadocを参照してください。

Jdbc2PoolDataSourceFactory

This factory uses the more full featured DataSource available in the commons-dbcp package. Jdbc2PoolDataSourceFactory provides an easy way to configure this pool and it assumes you will have a jdbc Driver class providing the physical database connections. Again, you must let torque know you are using this factory.

このファクトリは、commons-dbcp packageの中で、利用可能でより多くの注目を集めているデータソースを使用します。Jdbc2PoolDataSourceFactoryは、このプールをコンフィギュレーションする簡単な方法を提供しています。そしてそれは、あなたが物理的なデータベース接続を提供するjdbcドライバークラスを持っているだろうと仮定します。再び、はじめにこのファクトリを使用していることをTorqueに知らせなければなりません。

torque.dsfactory.bookstore.factory= \
  org.apache.torque.dsfactory.Jdbc2PoolDataSourceFactory

Then there are two sets of properties related to the pool configuration and settings for making the connection to the database.

それから、データベースへの接続を行なうためのセッティングとプールコンフィギュレーションに関係する2セットのプロパティがあります

torque.dsfactory.bookstore.pool.defaultMaxActive=30
torque.dsfactory.bookstore.pool.testOnBorrow=true
torque.dsfactory.bookstore.pool.validationQuery=SELECT 1

torque.dsfactory.bookstore.connection.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.bookstore.connection.url = jdbc:mysql://localhost:3306/bookstore
torque.dsfactory.bookstore.connection.user = root
torque.dsfactory.bookstore.connection.password = 1234

Comparing this with the torque's old pool, you can see that this pool does not rely on expirying connections periodically to maintain their validity. The pool can be setup to test each connection before returning it to the application, so the likelihood of the application receiving a bad connection is much smaller than using TorqueClassicDataSource. Jdbc2PoolDataSource contains several other options, for example, the ability have several usernames sharing the same pool settings. Please see the commons-dbcp javadoc for more info.

Torqueの古いプールとこれを比較すると、このプールが有効性を維持するために、周期的に接続をつくりだすことに依存していないことがわかります。プールはアプリケーションに返す前に各接続をテストするセットアップにも成りえます。したがって、アプリケーションが間違った接続を受け取るという可能性は、TorqueClassicDataSourceを使うよりもはるかに小さいのです。Jdbc2PoolDataSourceは他のいくつかのオプションを含んでいます、例えば、その機能は同じプールセッティングを共有するいくつかのユーザー名を持っています。より多くの情報に関しては、commons-dbcp のjavadocを参照してください。

JndiDataSourceFactory

This factory is used if the DataSource is to be available via jndi. It is possible to use this factory to deploy a DataSource into jndi, but in many cases for using this factory the DataSource is already deployed. This factory is specified with the following property:

DataSourceがjndi経由で使用可能な場合このファクトリが使用されます。jndiの中にDataSourceをデプロイするために、このファクトリを使用することができます。しかし多くの場合、このファクトリを使用するときにはDataSourceは既にデプロイされています。このファクトリは、次ののプロパティで指定されます:

torque.dsfactory.bookstore.factory=org.apache.torque.dsfactory.JndiDataSourceFactory

Using pre-configured pool

If a pool is known to already be available via jndi, only one more property is required.

プールが既にjndiによって利用可能であるとわかっている場合、あと一つのプロパティが必要です。

torque.dsfactory.bookstore.jndi.path=jdbc/bookstore

This line defines the string that will be used to lookup the DataSource within the default jndi InitialContext. If everything is configured and the default InitialContext contains the DataSource, this is all that is needed. The default InitialContext is chosen according to the rules given in the class's javadoc. If the default has not been configured, you can specify any other environment properties that are needed to instantiate the InitialContext as extra properties of the form, torque.jndi.<handle>.<env-var>. A couple examples are shown below:

この行では、デフォルトjndiのInitialContextの中でDataSourceをルックアップするために使われる文字列を定義しています。すべてコンフィギュレーションされデフォルトのInitialContextが、DataSourceを含んでいる場合は、これが必要なものの全てといえます。デフォルトのInitialContextは、クラスのjavadocの中で述べられている規則に従って選ばれています。デフォルトのものがコンフィギュレーションされていない場合、他の環境プロパティを指定することもできますが、 torque.jndi.<handle>.<env-var>のように、フォームの特別なプロパティとして、InitialContextを具体的に定義する必要があります。少しですが、以下に例を示します:

torque.dsfactory.bookstore.jndi.java.naming.factory.initial = org.apache.naming.java.javaURLContextFactory
torque.dsfactory.bookstore.jndi.java.naming.factory.url.pkgs = org.apache.naming

Such environment settings will likely not be necessary when running within a J2EE container, but they are useful in other cases. One such case is when running torque's unit/run-time tests

J2EEコンテナ内で動作するときには、そのような環境設定はおそらく必要ないと思われますが、他のケースの場合に置いては有用です。Torqueのユニット/ランタイムテストを実行する場合が、そのような1つのケースにあたります。

Using torque to bind pool

Generally a J2EE environment such as a servlet engine or application server is expected to provide a jdbc2 compatible connection pool. If your application is not running within such an environment, or even if it is and torque is your only use of a connection pool, torque provides a simple properties file method of configuring a DataSource and deploying it via jndi. The one property that is necessary for all DataSource's is the classname the DataSource implementation. Beyond that the properties are implementation specific. DataSource's contain getters/setters for configuration. You can specify the values for these properties as shown below:

一般的にサーブレットエンジンやアプリケーションサーバーのようなJ2EE環境にはjdbc2の互換性のある接続プールを供給することが期待されています。アプリケーションがそのような環境で動作していない場合、あるいはアプリケーションやTorqueが唯一の接続プールの使用しかない場合、TorqueはDataSourceをコンフィギュレーションし、それをjndi経由でデプロイしてくれる方法を簡単なプロパティファイルに提供してくれます。全てのDataSourceに必要なプロパティの一つは、実装しているDataSourceのクラス名です。その他にも、プロパティには、独特の実装があります。DataSourceの実装はコンフィギュレーションのためのgetters/settersも含んでいます。以下に示されるようなこれらのプロパティに対する値を指定することができます:

torque.dsfactory.bookstore.datasource.classname=org.apache.torque.pool.TorqueClassicDataSource
torque.dsfactory.bookstore.datasource.dataSourceName=jdbc/DBbookstore
torque.dsfactory.bookstore.datasource.defaultMaxConnections=10

torque.dsfactory.DBbookstore.datasource.factory=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
torque.dsfactory.DBbookstore.datasource.driver = org.gjt.mm.mysql.Driver
torque.dsfactory.DBbookstore.datasource.url = jdbc:mysql://localhost:3306/bookstore
torque.dsfactory.DBbookstore.datasource.user = root
torque.dsfactory.DBbookstore.datasource.password = 1234

In the above example two objects are being configured. One is a DataSource that is used by the application (torque). The other is a ConnectionPoolDataSource that is provided as part of a jdbc2 driver. If the jdbc driver implementation you are using does not fully implement the jdbc2 specification. commons-dbcp provides an adapter for older Driver based drivers. Another alternative is provided in commons-dbcp where BasicDataSource provides a DataSource frontend, and has properties to directly configure a jdbc1 Driver. But regardless of the implementation torque uses commons-beanutils package to call the setters on the object using reflection.

上記の例では、2つの対象がコンフィギュレーションされています。1つはアプリケーションによって使用されるDataSource です(torque)。もう一方はjdbc2ドライバーの一部として提供されるConnectionPoolDataSourceです。使用しているjdbcドライバーの実装がjdbc2の仕様に十分に対応していない場合、commons-dbcpは、ドライバーに基づいて古いDriverのアダプタを提供します。commons-dbcpには他にも代替機能が提供されていて、そこではBasicDataSourceが、フロントエンドにDataSourceを提供するようになってます。また、直接jdbc1 のDriverをコンフィギュレーションするようなプロパティも用意されています。しかし、そのような実装がされているにもかかわらず、Torqueはオブジェクトへの反映をするセッターを呼ぶためにcommons-beanutilsパッケージを使っています。

Torque uses the jndi path properties to know where to deploy the configured objects. So you would have the two following properties in addition to the datasource props:

Torqueは、コンフィギュレーションされたオブジェクトをどこにデプロイすべきなのかを知るためにjndiのパスプロパティを使用します。したがって、datasourceプロパティに加えて、次の2つのプロパティを定義することになるでしょう:

torque.dsfactory.bookstore.jndi.path=jdbc/bookstore
torque.dsfactory.DBbookstore.jndi.path=jdbc/DBbookstore

The second handle, DBbookstore, has no relevance to torque, other than to uniquely identify this group of properties as belonging together. Any unique handle may be used.

二番目のハンドル（DBbookstore）は、このプロパティグループを一緒に属するものとしてユニークに識別できることを除いては、Torqueには関係ありません。ユニークなハンドルならばどんなものでも使用される可能性があります

Tomcat example of external configuration/binding

If you have other parts of your application that need to use the same connection pool and torque cannot be guaranteed to be initialized in time for these other uses, or if you just want to follow your j2ee environment's standard jndi deployment pattern, torque can just make use of these externally deployed pools. Here is an example using catalina of deploying the pool that used to come with torque, but is now part of commons-jdbc2pool.

同じ接続プールを使用する必要のあるアプリケーションの他の部分があったり、トルクがこれらの他に使用される時に、初期化することを保証できない場合、もしくは、j2ee環境における標準jndiのデプロイパターンを使用したい場合、Torqueは外部にデプロイされたプールを使用することができます。ここでは、以前はTorqueに付随してきましたが、いまはcommons-jdbc2poolの一部となっているプールをデプロイしているcatalinaの使用例を示します。

In server.xml, the following would be added to the <Context> for your webapp:

server.xmlの中で、webアプリケーションのために<Context>に次のようなものを追加することになるでしょう:

 <Resource name="jdbc/ScarabDB" auth="Container"
            type="org.apache.torque.pool.TorqueClassicDataSource"/>
  <ResourceParams name="jdbc/bookstore">
    <parameter>
      <name>factory</name>
      <value>org.apache.torque.pool.TorqueClassicDataSource</value>
    </parameter>
    <parameter>
      <name>dataSourceName</name><value>java:comp/env/jdbc/DBbookstore</value>
    </parameter>
    <parameter>
      <name>defaultMaxConnections</name><value>30</value>
    </parameter>
    <parameter>
      <name>maxExpiryTime</name><value>3600</value>
    </parameter>
    <parameter>
      <name>connectionWaitTimeout</name><value>10</value>
    </parameter>
    <parameter>
      <name>logInterval</name><value>0</value>
    </parameter>

  </ResourceParams>

In web.xml. Elements must be given in the order of the dtd described in the servlet specification:

web.xmlの中では、要素は、servlet仕様に記述されたdtdの順序でかかれなければいけません:

<resource-ref>
  <description>
    Resource reference to a factory for java.sql.Connection
    instances that may be used for talking to a particular
    database that is configured in the server.xml file.
  </description>
  <res-ref-name>
    jdbc/bookstore
  </res-ref-name>
  <res-type>
    org.apache.torque.pool.TorqueClassicDataSource
  </res-type>
  <res-auth>
    Container
  </res-auth>
</resource-ref>

Catalina deploys all objects configured similarly to above within the java:comp/env namespace so the jndi path given in Torque.properties would be

Catalinaはthe java:comp/env namespaceの中で、上でやってきたようなコンフィギュレーションされたオブジェクトをすべてデプロイします。それゆえ、jndiパスはTorque.propertiesのなかで記述されているようになります

torque.dsfactory.bookstore.jndi.path=java:comp/env/jdbc/bookstore

Remember that jdbc2 pools expect a ConnectionPoolDataSource available via jndi under the name given in the dataSourceName, so you will need entries in server.xml and web.xml for this object as well.

jdbc2のプールはdataSourceNameの中で与えられた名前をもとにjndi経由で利用可能なConnectionPoolDataSourceを提供することが期待されていることを思い出してください。従って、この項目のためにserver.xmlとweb.xmlにも同様に登録する必要があります。

Catalina provides a default DataSource that can be used as well and it is configured similarly, but detailed information on that implementation is here. Note that the "type attribute/ref-type element" value of "javax.sql.DataSource" appears to be reserved for catalina's default implementation, which is why the implementation classname is used in our configuration example.

Catalinaは同様に、使用可能なデフォルトのDataSourceを提供しています。そしてそれは同じようにコンフィギュレーションされていますが、その実装に関しての詳細情報は、ここにあります。 "javax.sql.DataSource"の"type attribute/ref-type element"の値はcatalinaのデフォルト実装のためにとっておいているに見えますので注意してください。そのようなことから、コンフィギュレーションの例では、実装クラス名が使用されています。

An example configuration from scarab

The following example shows a complete torque configuration from scarab, an issue tracking application, running under catalina, but using torque to deploy the DataSource. It is here to put together some of the details shown above.

次の例は、catalinaで動くのですが、DataSourceをデプロイするためにtorqueを使用している問題追跡アプリケーションscarabの完全なTorqueコンフィギュレーションです。ここには、上で示した詳細のうちのいくつかをいかに組み立てたるべきかを示しています。

torque.database.scarab.adapter=mysql

# Jndi location
torque.dsfactory.scarab.jndi.path=jdbc/scarab
torque.dsfactory.DBscarabDB.jndi.path=jdbc/DBscarabDB

# Connection properties for the pooling DataSource
# These properties will vary from one datasource to another, see the class
# javadoc for a description of which properties can be set.
torque.dsfactory.scarab.datasource.classname=org.apache.torque.pool.TorqueClassicDataSource
torque.dsfactory.scarab.datasource.dataSourceName=jdbc/DBscarabDB
torque.dsfactory.scarab.datasource.defaultMaxConnections=30
torque.dsfactory.scarab.datasource.maxExpiryTime=3600
torque.dsfactory.scarab.datasource.connectionWaitTimeout=10
torque.dsfactory.scarab.datasource.logInterval=0

# Connection properties for the ConnectionPoolDataSource
torque.dsfactory.DBscarabDB.datasource.classname=org.apache.commons.dbcp.cpdsadapter.DriverAdapterCPDS
torque.dsfactory.DBscarabDB.datasource.driver=org.gjt.mm.mysql.Driver
torque.dsfactory.DBscarabDB.datasource.url=jdbc:mysql://localhost:3306/scarab
torque.dsfactory.DBscarabDB.datasource.user=xxx
torque.dsfactory.DBscarabDB.datasource.password=yyy


# Determines if the quantity column of the IDBroker's id_table should
# be increased automatically if requests for ids reaches a high
# volume.

torque.idbroker.clever.quantity=false

# Determines if IDBroker should prefetch IDs or not.  If set to false
# this property has the effect of shutting off the housekeeping thread
# that attempts to prefetch the id's.  It also sets the # of id's grabbed
# per request to 1 regardless of the settings in the database.
# Default: true

torque.idbroker.prefetch=true