B.4. データソース設定

B.4.1. データソースのパラメーター

表B.2 非 XA および XA データソースに共通のデータソースパラメーター

パラメーター 説明
jndi-name データソースの一意の JNDI 名。
pool-name データソースの管理プール名。
enabled データソースが有効かどうかを指定します。
use-java-context
データソースをグローバルの JNDI にバインドするかどうかを指定します。
spy
JDBC レイヤーで spy 機能を有効にします。この機能は、データソースへの JDBC トラフィックをすべてログに記録します。ロギングカテゴリーの jboss.jdbc.spy もロギングサブシステムのログレベルである DEBUG に設定する必要があることに注意してください。
use-ccm キャッシュ接続マネージャーを有効にします。
new-connection-sql 接続プールに接続が追加された時に実行する SQL ステートメント。
transaction-isolation
次のいずれかになります。
  • TRANSACTION_READ_UNCOMMITTED
  • TRANSACTION_READ_COMMITTED
  • TRANSACTION_REPEATABLE_READ
  • TRANSACTION_SERIALIZABLE
  • TRANSACTION_NONE
url-selector-strategy-class-name インターフェース org.jboss.jca.adapters.jdbc.URLSelectorStrategy を実装するクラス。
security
セキュリティー設定である子要素が含まれます。表B.7「セキュリティーパラメーター」を参照してください。
validation
検証設定である子要素が含まれます。表B.8「検証パラメーター」を参照してください。
timeout
タイムアウト設定である子要素が含まれます。表B.9「タイムアウトパラメーター」を参照してください。
statement
ステートメント設定である子要素が含まれます。表B.10「ステートメントのパラメーター」を参照してください。

表B.3 非 XA データソースのパラメーター

パラメーター 説明
jta 非 XA データソースの JTA 統合を有効にします。XA データソースには適用されません。
connection-url JDBC ドライバーの接続 URL。
driver-class JDBC ドライバークラスの完全修飾名。
connection-property
Driver.connect(url,props) メソッドに渡される任意の接続プロパティー。各 connection-property は、文字列名と値のペアを指定します。プロパティー名は名前、値は要素の内容に基づいています。
pool
プーリング設定である子要素が含まれます。表B.5「非 XA および XA データソースに共通のプールパラメーター」を参照してください。

表B.4 XA データソースのパラメーター

パラメーター 説明
xa-datasource-property
実装クラス XADataSource に割り当てるプロパティー。name=value で指定。 setName という形式で setter メソッドが存在する場合、プロパティーは setName(value) という形式の setter メソッドを呼び出すことで設定されます。
xa-datasource-class
実装クラス javax.sql.XADataSource の完全修飾名。
driver
JDBC ドライバーが含まれるクラスローダーモジュールへの一意参照。driverName#majorVersion.minorVersion の形式にのみ対応しています。
xa-pool
プーリング設定である子要素が含まれます。表B.5「非 XA および XA データソースに共通のプールパラメーター」および表B.6「XA プールパラメーター」を参照してください。
recovery
リカバリー設定である子要素が含まれます。表B.11「リカバリーパラメーター」を参照してください。

表B.5 非 XA および XA データソースに共通のプールパラメーター

パラメーター 説明
min-pool-size プールが保持する最小接続数
max-pool-size プールが保持可能な最大接続数
prefill 接続プールのプレフィルを試行するかどうかを指定します。要素が空の場合は true を示します。デフォルトは、false です。
use-strict-min pool-size が厳密かどうかを指定します。デフォルトは false に設定されています。
flush-strategy
エラーの場合にプールをフラッシュするかどうかを指定します。有効な値は次の通りです。
  • FailingConnectionOnly
  • IdleConnections
  • EntirePool
デフォルトは FailingConnectionOnly です。
allow-multiple-users 複数のユーザーが getConnection(user, password) メソッドを使いデータソースへアクセスするかどうか、また内部プールタイプがこの動作に対応するかを指定します。

表B.6 XA プールパラメーター

パラメーター 説明
is-same-rm-override javax.transaction.xa.XAResource.isSameRM(XAResource) クラスが true あるいは false のどちらを返すか。
interleaving XA 接続ファクトリーのインターリービングを有効にするかどうか。
no-tx-separate-pools
コンテキスト毎に sub-pool を作成するかどうか。これには Oracle のデータソースが必要ですが、JTA トランザクションの内部と外部の両方で XA 接続が使用できなくなります。
このオプションを使用することにより、2 つの実際のファイルが作成されるため、プールサイズの合計が max-pool-size の 2 倍になります。
pad-xid Xid のパディングを行うかどうかを指定します。
wrap-xa-resource
XAResource を org.jboss.tm.XAResourceWrapper インスタンスでラップするかどうかを指定します。

表B.7 セキュリティーパラメーター

パラメーター 説明
user-name 新規接続の作成に使うユーザー名
password 新規接続の作成に使うパスワード
security-domain 認証処理を行う JAAS security-manager 名が含まれます。この名前は、JAAS ログイン設定の application-policy/name 属性に相関します。
reauth-plugin 物理接続の再認証に使う再認証プラグインを定義します。

表B.8 検証パラメーター

パラメーター 説明
valid-connection-checker
SQLException.isValidConnection(Connection e) メソッドを提供し接続を検証するインターフェース org.jboss.jca.adaptors.jdbc.ValidConnectionChecker の実装。例外が発生すると接続が破棄されます。存在する場合、check-valid-connection-sql パラメーターが上書きされます。
check-valid-connection-sql プール接続の妥当性を確認する SQL ステートメント。これは、管理接続をプールから取得し利用する場合に呼び出される場合があります。
validate-on-match
接続ファクトリーが指定のセットに対して管理された接続をマッチしようとした時に接続レベルの検証を実行するかどうかを示します。
通常、validate-on-match に「true」を指定した時に background-validation を「true」に指定することはありません。クライアントが使用前に接続を検証する必要がある場合に Validate-on-match が必要になります。このパラメーターはデフォルトでは false になっています。
background-validation
接続がバックグラウンドスレッドで検証されることを指定します。validate-on-match を使用しない場合、バックグラウンドの検証はパフォーマンスを最適化します。validate-on-match が true の時に background-validation を使用すると、チェックが冗長になることがあります。バックグラウンド検証では、不良の接続がクライアントに提供される可能性があります (検証スキャンと接続がクライアントに提供されるまでの間に接続が悪くなります)。そのため、クライアントアプリケーションはこの接続不良の可能性に対応する必要があります。
background-validation-millis バックグラウンド検証を実行する期間 (ミリ秒単位)。
use-fast-fail
true の場合、接続が無効であれば最初に接続を割り当てしようとした時点で失敗します。デフォルトは false です。
stale-connection-checker
ブール値の isStaleConnection(SQLException e) メソッドを提供する org.jboss.jca.adapters.jdbc.StaleConnectionChecker のインスタンス。このメソッドが true を返すと、SQLException のサブクラスである org.jboss.jca.adapters.jdbc.StaleConnectionException に例外がラップされます。
exception-sorter
ブール値である isExceptionFatal(SQLException e) メソッドを提供する org.jboss.jca.adapters.jdbc.ExceptionSorter のインスタンス。このメソッドは、例外が connectionErrorOccurred メッセージとして javax.resource.spi.ConnectionEventListener のすべてのインスタンスへブロードキャストされるかどうかを検証します。

表B.9 タイムアウトパラメーター

パラメーター 説明
use-try-lock lock() の代わりに tryLock() を使用します。これは、ロックが使用できない場合に即座に失敗するのではなく、設定された秒数間ロックの取得を試みます。デフォルトは 60 秒です。たとえば、タイムアウトを 5 分に設定するには、<use-try-lock>300</use-try-lock> を設定します。
blocking-timeout-millis 接続待機中にブロックする最大時間 (ミリ秒)。この時間を超過すると、例外がスローされます。これは、接続許可の待機中のみブロックし、新規接続の作成に長時間要している場合は例外をスローしません。デフォルトは 30000 (30 秒) です。
idle-timeout-minutes
アイドル接続が切断されるまでの最大時間 (分単位)。実際の最大時間は idleRemover のスキャン時間によって異なります。idleRemover のスキャン時間はプールの最小 idle-timeout-minutes の半分になります。
set-tx-query-timeout
トランザクションがタイムアウトするまでの残り時間を基にクエリーのタイムアウトを設定するかどうかを指定します。トランザクションが存在しない場合は設定済みのクエリーのタイムアウトが使用されます。デフォルトは false です。
query-timeout クエリーのタイムアウト (秒)。デフォルトはタイムアウトなしです。
allocation-retry 例外をスローする前に接続の割り当てを再試行する回数。デフォルトは 0 で、初回の割り当て失敗で例外がスローされます。
allocation-retry-wait-millis
接続の割り当てを再試行するまで待機する期間 (ミリ秒単位)。デフォルトは 5000 (5 秒) です。
xa-resource-timeout
ゼロでない場合、この値は XAResource.setTransactionTimeout メソッドへ渡されます。

表B.10 ステートメントのパラメーター

パラメーター 説明
track-statements
接続がプールへ返され、ステートメントが準備済みステートメントキャッシュへ返された時に、閉じられていないステートメントをチェックするかどうかを指定します。false の場合、ステートメントは追跡されません。

有効な値

  • true: ステートメントと結果セットが追跡され、ステートメントが閉じられていない場合は警告が出力されます。
  • false: ステートメントと結果セットのいずれも追跡されません。
  • nowarn: ステートメントは追跡されますが、警告は出力されません。これがデフォルト設定となっています。
prepared-statement-cache-size LRU (Least Recently Used) キャッシュにある接続毎の準備済みステートメントの数。
share-prepared-statements
閉じずに同じステートメントを 2 回要求した場合に、同じ基盤の準備済みステートメントを使用するかどうかを指定します。デフォルトは false です。

表B.11 リカバリーパラメーター

パラメーター 説明
recover-credential リカバリーに使用するユーザー名とパスワードのペア、あるいはセキュリティドメイン。
recover-plugin
リカバリーに使用される org.jboss.jca.core.spi.recoveryRecoveryPlugin クラスの実装。
バグを報告する

B.4.2. データソース接続 URL

表B.12 データソース接続 URL

データソース 接続 URL
PostgreSQL jdbc:postgresql://SERVER_NAME:PORT/DATABASE_NAME
MySQL jdbc:mysql://SERVER_NAME:PORT/DATABASE_NAME
Oracle jdbc:oracle:thin:@ORACLE_HOST:PORT:ORACLE_SID
IBM DB2 jdbc:db2://SERVER_NAME:PORT/DATABASE_NAME
Microsoft SQLServer jdbc:microsoft:sqlserver://SERVER_NAME:PORT;DatabaseName=DATABASE_NAME
バグを報告する

B.4.3. データソースの拡張

データソースのデプロイメントは、JDBC リソースアダプターにある複数の拡張を使用して接続の検証を改善でき、例外が接続を再確立するべきかどうかを確認できます。これらの拡張は次の通りです。

表B.13 データソースの拡張

データソースの拡張 設定パラメーター 説明
org.jboss.jca.adapters.jdbc.spi.ExceptionSorter <exception-sorter> SQLException が発生した接続にとってこの例外は致命的かどうかを確認します。
org.jboss.jca.adapters.jdbc.spi.StaleConnection <stale-connection-checker> org.jboss.jca.adapters.jdbc.StaleConnectionException の古い SQLExceptions をラップします。
org.jboss.jca.adapters.jdbc.spi.ValidConnection <valid-connection-checker> アプリケーションによる接続の使用が有効であるかどうかを確認します。
JBoss EAP 6 は、これらの拡張の実装を、サポートされるいくつかのデータベース用に提供します。

拡張の実装

汎用
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullStaleConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.novendor.NullValidConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.novendor.JDBC4ValidConnectionChecker
PostgreSQL
  • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker
MySQL
  • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLReplicationValidConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.mysql.MySQLValidConnectionChecker
IBM DB2
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2StaleConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.db2.DB2ValidConnectionChecker
Sybase
  • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.sybase.SybaseValidConnectionChecker
Microsoft SQLServer
  • org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker
Oracle
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleExceptionSorter
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleStaleConnectionChecker
  • org.jboss.jca.adapters.jdbc.extensions.oracle.OracleValidConnectionChecker
バグを報告する

B.4.4. データソース統計の表示

以下のコマンドを適切に編集すると、jdbc および pool の定義済みデータソースより統計を表示できます。

手順B.3 

  • /subsystem=datasources/data-source=ExampleDS/statistics=jdbc:read-resource(include-runtime=true)

    /subsystem=datasources/data-source=ExampleDS/statistics=pool:read-resource(include-runtime=true)

注記

統計はすべてランタイムのみの情報で、デフォルトは false であるため、必ず include-runtime=true 引数を指定するようにしてください。
バグを報告する

B.4.5. データソースの統計

主要統計

サポートされるデータソースの主要統計は以下の表の通りです。

表B.14 主要統計

名前 説明
ActiveCount
アクティブな接続の数。各接続はアプリケーションによって使用されているか、プールで使用可能な状態であるかのいずれかになります。
AvailableCount
プールの使用可能な接続の数。
AverageBlockingTime
プールの排他ロックの取得をブロックするために費やされた平均時間。値はミリ秒単位です。
AverageCreationTime
接続の作成に費やされた平均時間。値はミリ秒単位です。
CreatedCount
作成された接続の数。
DestroyedCount
破棄された接続の数。
InUseCount
現在使用中の接続の数。
MaxCreationTime
接続の作成にかかった最大時間。値はミリ秒単位です。
MaxUsedCount
使用される接続の最大数。
MaxWaitCount
同時に接続を待機するリクエストの最大数。
MaxWaitTime
プールの排他ロックの待機に費やされた最大時間。
TimedOut
タイムアウトした接続の数。
TotalBlockingTime
プールの排他ロックの待機に費やされた合計時間。値はミリ秒単位です。
TotalCreationTime
接続の作成に費やされた合計時間。値はミリ秒単位です。
WaitCount
接続を待機する必要があるリクエストの数。
JDBC の統計

サポートされるデータソースの JDBC 統計は以下の表の通りです。

表B.15 JDBC の統計

名前 説明
PreparedStatementCacheAccessCount
ステートメントキャッシュがアクセスされた回数。
PreparedStatementCacheAddCount
ステートメントキャッシュに追加されたステートメントの数。
PreparedStatementCacheCurrentSize
ステートメントキャッシュに現在キャッシュされた準備済みおよび呼び出し可能ステートメントの数。
PreparedStatementCacheDeleteCount
キャッシュから破棄されたステートメントの数。
PreparedStatementCacheHitCount
キャッシュからのステートメントが使用された回数。
PreparedStatementCacheMissCount
ステートメント要求がキャッシュのステートメントと一致しなかった回数。
以下のコマンドの適切に変更されたバージョンを使用すると、Core と JDBC の統計を有効にできます。 
  • /subsystem=datasources/data-source=ExampleDS/statistics=pool:write-attribute(name=statistics-enabled,value=true)

    /subsystem=datasources/data-source=ExampleDS/statistics=jdbc:write-attribute(name=statistics-enabled,value=true)
バグを報告する