Apache Karaf トランザクションガイド

以下の機能は、リソースの QoS(Quality of Service) を決定します。

以下の機能は、トランザクションマネージャーの QoS (Quality of Service) を決定します。

ローカルトランザクションマネージャー は、1 つのリソースに対してのみトランザクションを調整できるトランザクションマネージャーです。ローカルトランザクションマネージャーの実装は通常、リソース自体に組み込まれ、アプリケーションが使用するトランザクションマネージャーは、この組み込みトランザクションマネージャーに関連するシンラッパーです。

たとえば、Oracle データベースには、デマケーション操作をサポートする組み込みトランザクションマネージャーがあり (SQL BEGIN、COMMIT、または ROLLBACK ステートメントを使用するか、ネイティブ Oracle API を使用)、さまざまなレベルのトランザクション分離があります。Oracle トランザクションマネージャーの制御は JDBC を介してエクスポートでき、この JDBC API は、アプリケーションがトランザクションの境界を定めるために使用します。

このコンテキストでは、リソース設定要素を理解することが重要です。たとえば、JMS 製品を使用している場合、JMS リソースは個別のキューやトピックではなく、JMS 製品の単一で実行中のインスタンスになります。さらに、同じ基になるリソースに異なる方法でアクセスする場合、複数のリソースのように見えるものが実際には単一のリソースである場合があります。たとえば、アプリケーションは、(JDBC を介して) 直接 (JDBC を介して) および間接的 (Hibernate などのオブジェクト関係マッピングツールを介して) リレーショナルデータベースにアクセスする可能性があります。この場合、基礎となるトランザクションマネージャーは同じため、これらのコードフラグメントの両方を同じトランザクションに登録できるはずです。

アプリケーションでは、多くの異なるローカルトランザクションマネージャーが互いに独立して動作させることができます。たとえば、JMS キューとトピックを操作する 1 つの Camel ルートがあり、JMS エンドポイントが JMS トランザクションマネージャーを参照しているとします。もう 1 つのルートは JDBC 経由でリレーショナルデータベースにアクセスできます。しかし、JDBC と JMS アクセスを同じルートで組み合わせて、両方を同じトランザクションに参加させることはできません。

グローバルトランザクションマネージャーは、複数のリソースでトランザクションを調整できるトランザクションマネージャーです。これは、リソース自体に構築されたトランザクションマネージャーに依存できない場合に必要です。トランザクション処理モニター (TP モニター) と呼ばれる外部システムは、異なるリソース間のトランザクションを調整できます。

以下は、複数のリソースで動作するトランザクションの前提条件です。

通常、サーバーはトランザクションに関連するリソースに直接接続します。ただし、分散システムでは、Web サービスを介して間接的にのみ公開されるリソースに接続する必要がある場合があります。この場合、分散トランザクションをサポートすることができる TP モニターが必要です。Web サービスの WS-AtomicTransactions 仕様など、さまざまな分散プロトコルのトランザクションをサポートする方法を記述するいくつかの標準が利用できます。

前述のように、javax.transaction.UserTransaction は通常 JavaEE アプリケーションの JNDI から取得されます。ただし、Spring は多くのシナリオでこのインターフェイスの明示的な実装を提供します。常に完全な JTA シナリオが必要なく、アプリケーションは単一のリソース (JDBC など) のみにアクセスする必要がある場合があります。

通常、org.springframework.transaction.PlatformTransactionManager は 従来のトランザクションクライアントの操作 (begin、commit および rollback) を提供する Spring トランザクションクライアント API です。つまり、このインターフェイスは実行時にトランザクションの制御に必要なメソッドを提供します。

public interface PlatformTransactionManager {

    TransactionStatus getTransaction(TransactionDefinition definition) throws TransactionException;

    void commit(TransactionStatus status) throws TransactionException;

    void rollback(TransactionStatus status) throws TransactionException;
}

public interface TransactionStatus extends SavepointManager, Flushable {

    boolean isNewTransaction();

    boolean hasSavepoint();

    void setRollbackOnly();

    boolean isRollbackOnly();

    void flush();

    boolean isCompleted();
}

通常、PlatformTransactionManager インターフェイスを直接使用しません。Apache Camel では、通常以下のようにトランザクションマネージャーを使用します。

本セクションでは、Spring Framework で提供されるトランザクションマネージャーの実装を概説します。この実装は、ローカルトランザクションマネージャーとグローバルトランザクションマネージャーの 2 つのカテゴリーに分類されます。

Camel から開始:

ご覧のとおり、このインターフェイスの実装が いくつか 必要です。シナリオによっては、必要なプラットフォームトランザクションマネージャーを設定できます。

InitialContext context = new InitialContext();
UserTransaction ut = (UserTransaction) context.lookup("java:comp/UserTransaction");
TransactionManager tm = (TransactionManager) context.lookup("java:/TransactionManager");

JtaTransactionManager jta = new JtaTransactionManager();
jta.setUserTransaction(ut);
jta.setTransactionManager(tm);

TransactionTemplate jtaTx = new TransactionTemplate(jta);

jtaTx.execute((status) -> {
    // Perform resource access in the context of global transaction.
    return ...;
});

JTA UserTransaction インターフェイスは以下のように定義されます。

public interface javax.transaction.UserTransaction {

    public void begin();

    public void commit();

    public void rollback();

    public void setRollbackOnly();

    public int getStatus();

    public void setTransactionTimeout(int seconds);
}

UserTransaction インターフェイスは以下のメソッドを定義します。

JTA TransactionManager インターフェイスの定義は以下のとおりです。

interface javax.transaction.TransactionManager {

    // Same as UserTransaction methods

    public void begin();

    public void commit();

    public void rollback();

    public void setRollbackOnly();

    public int getStatus();

    public void setTransactionTimeout(int seconds);

    // Extra TransactionManager methods

    public Transaction getTransaction();

    public Transaction suspend() ;

    public void resume(Transaction tobj);
}

TransactionManager インターフェイスは、UserTransaction インターフェイスにあるすべてのメソッドをサポートします。トランザクションのデマケーションには TransactionManager オブジェクトを使用できます。さらに、TransactionManager オブジェクトは以下のメソッドをサポートします。

JTA Transaction インターフェイスの定義は以下のとおりです。

interface javax.transaction.Transaction {

    public void commit();

    public void rollback();

    public void setRollbackOnly();

    public int getStatus();

    public boolean enlistResource(XAResource xaRes);

    public boolean delistResource(XAResource xaRes, int flag);

    public void registerSynchronization(Synchronization sync);
}

commit()、rollback()、setRollbackOnly()、および getStatus() メソッドは、UserTransaction インターフェイスからの該当のメソッドと同じ動作をします。実際、UserTransaction オブジェクトは現在のトランザクションを取得し、Transaction オブジェクトで対応するメソッドを呼び出す便利なラッパーです。

また、Transaction インターフェイスは、UserTransaction インターフェイスにカウンターがない以下のメソッドを定義します。

XA リソースをトランザクションに登録するには、Transaction インターフェイスで enlistResource() メソッドを呼び出す必要があります。たとえば、TransactionManager オブジェクトおよび XAResource オブジェクトの場合は、以下のように XAResource オブジェクトを登録できます。

// Java
import javax.transaction.Transaction;
import javax.transaction.TransactionManager;
import javax.transaction.xa.XAResource;
...
// Given:
// 'tm' of type TransactionManager
// 'xaResource' of type XAResource

// Start the transaction
tm.begin();

Transaction transaction = tm.getTransaction();
transaction.enlistResource(xaResource);

// Do some work...
...

// End the transaction
tm.commit();

リソース登録が難しい点として、リソースを新しいトランザクション ごと に登録する必要があるので、リソースの使用を開始する前にリソースを登録する必要があります。リソースを明示的に登録すると、エラーが発生しやすいコードに enlistResource() 呼び出しがいくつもある状態になる可能性があります。さらに、適切な場所で enlistResource() を呼び出すことが困難なことがあります。たとえば、トランザクションの詳細の一部を非表示にするフレームワークを使用している場合などです。

XA リソースを明示的に登録する代わりに、XA リソースの自動登録をサポートする機能を使用するほうが簡単かつ安全です。たとえば、JMS および JDBC リソースを使用する場合に、標準の手法として自動登録に対応するラッパークラスを使用することが挙げられます。

JDBC および JMS アクセスの両方で一般的なパターンは次のとおりです。

このようにして、アプリケーションコードは引き続き javax.sql.DataSource および javax.jms.ConnectionFactory を使用しますが、内部的にこれらのコードがアクセスされると、通常は以下に関する追加機能があります。

自動登録では、アプリケーションコードを変更する必要はありません。

JDBC データソースおよび JMS 接続ファクトリーのラッパーのプールとエンリストに関する詳細は、6章JDBC データソースの使用 および 7章JMS 接続ファクトリーの作成 を参照してください。

JDBC データソースの実装は 2 つのカテゴリーに分類されます。

汎用 javax.sql.DataSource 実装によって独自のデータベース固有の接続を作成できないことが紛らわしい可能性があります。汎用 データソースが java.sql.Driver.connect() または java.sql.DriverManager.getConnection() を使用できたとしても、データベース固有の javax.sql.DataSource 実装でこの 汎用 データソースを設定するのが通常、適切またはクリーンです。

汎用 データソースが JTA と対話する場合は、javax.sql.XADataSource のデータベース固有の実装で設定する 必要 があります。

イメージを閉じるには、通常、汎用 データソースは、接続プーリングを実行するために javax.sql.ConnectionPoolDataSource のデータベース固有の実装を必要としません。既存のプールは通常、標準の JDBC インターフェイス (javax.sql.ConnectionPoolDataSource および javax.sql.PooledConnection) なしでプーリングを処理し、代わりに独自のカスタム実装を使用します。

サンプルのよく知られた汎用データソースである ApacheCommonsDBCP(2) を見ていきます。

上記のシーケンス図に示すように、ドライバーは javax.sql.ConnectionPoolDataSource を直接提供するか、org.apache.commons.dbcp2.cpdsadapter.DriverAdapterCPDS アダプター の助けを借りて提供します。一方、DBCP2 は、以下のいずれかで アプリケーションサーバー コントラクトを以下のいずれかで実装します。

これらのプールは、設定段階で javax.sql.ConnectionPoolDataSource のインスタンスを取ります。

これは DBCP2 の最も重要で興味深い部分です。

以下は、DBCP2 の 通常 のデータソースの一覧です。

2 つの 軸 があります。

いずれの種類のデータソースも、java.sql.Connection オブジェクトの プーリング を実行します。唯一 の違いは、以下の点です。

推奨のパターンは以下のとおりです。

以下は 正規 の例です。

// Database-specific, non-pooling, non-enlisting javax.sql.XADataSource
PGXADataSource postgresql = new org.postgresql.xa.PGXADataSource();
// Database-specific configuration
postgresql.setUrl("jdbc:postgresql://localhost:5432/reportdb");
postgresql.setUser("fuse");
postgresql.setPassword("fuse");
postgresql.setCurrentSchema("report");
postgresql.setConnectTimeout(5);
// ...

// Non database-specific, pooling, enlisting javax.sql.DataSource
BasicManagedDataSource pool = new org.apache.commons.dbcp2.managed.BasicManagedDataSource();
// Delegate to database-specific XADatasource
pool.setXaDataSourceInstance(postgresql);
// Delegate to JTA transaction manager
pool.setTransactionManager(transactionManager);
// Non database-specific configuration
pool.setMinIdle(3);
pool.setMaxTotal(10);
pool.setValidationQuery("select schema_name, schema_owner from information_schema.schemata");
// ...

// JDBC code:
javax.sql.DataSource applicationDataSource = pool;

try (Connection c = applicationDataSource.getConnection()) {
    try (Statement st = c.createStatement()) {
        try (ResultSet rs = st.executeQuery("select ...")) {
            // ....

Fuse 環境では設定オプションが多くなり、DBCP2 を使用する必要はありません。

pax-jdbc (または pax-jdbc-mysql、pax-jdbc-oracle など​) のバンドルでは、org.osgi.service.jdbc.DataSourceFactory サービスを登録でき、それを使用して、指定のデータベースのデータソースを取得できます (「データベース固有のデータソースおよび汎用データソース」参照)。しかし、実際のデータソースはまだありません。

mvn:org.ops4j.pax.jdbc/pax-jdbc-config/1.3.0 バンドルは、以下の 2 つを行う管理対象サービスファクトリーを提供します。

以下は、Fuse の新規インストールを開始するために順をおって説明した 標準的な ガイドです。

これで、実際のデータベース固有 (まだプールなし) データソースができました。必要な場所に注入することができます。たとえば、Karaf コマンドを使用してデータベースにクエリーすることができます。

karaf@root()> feature:install -v jdbc
Adding features: jdbc/[4.2.0.fuse-000237-redhat-1,4.2.0.fuse-000237-redhat-1]
...
karaf@root()> jdbc:ds-list
Mon May 14 08:46:22 CEST 2018 WARN: Establishing SSL connection without server's identity verification is not recommended. According to MySQL 5.5.45+, 5.6.26+ and 5.7.6+ requirements SSL connection must be established by default if explicit option isn't set. For compliance with existing applications not using SSL the verifyServerCertificate property is set to 'false'. You need either to explicitly disable SSL by setting useSSL=false, or set useSSL=true and provide truststore for server certificate verification.
Name    │ Product │ Version │ URL                                  │ Status
────────┼─────────┼─────────┼──────────────────────────────────────┼───────
mysqlds │ MySQL   │ 5.7.21  │ jdbc:mysql://localhost:3306/reportdb │ OK

karaf@root()> jdbc:query mysqlds 'select * from incident'
Mon May 14 08:46:46 CEST 2018 WARN: Establishing SSL connection without server's identity verification is not recommended. According to MySQL 5.5.45+, 5.6.26+ and 5.7.6+ requirements SSL connection must be established by default if explicit option isn't set. For compliance with existing applications not using SSL the verifyServerCertificate property is set to 'false'. You need either to explicitly disable SSL by setting useSSL=false, or set useSSL=true and provide truststore for server certificate verification.
date                  │ summary    │ name   │ details                       │ id │ email
──────────────────────┼────────────┼────────┼───────────────────────────────┼────┼─────────────────
2018-02-20 08:00:00.0 │ Incident 1 │ User 1 │ This is a report incident 001 │ 1  │ user1@redhat.com
2018-02-20 08:10:00.0 │ Incident 2 │ User 2 │ This is a report incident 002 │ 2  │ user2@redhat.com
2018-02-20 08:20:00.0 │ Incident 3 │ User 3 │ This is a report incident 003 │ 3  │ user3@redhat.com
2018-02-20 08:30:00.0 │ Incident 4 │ User 4 │ This is a report incident 004 │ 4  │ user4@redhat.com

上記の例では、MySQL の警告が表示されます。これは問題ではありません。すべてのプロパティー (OSGi JDBC 固有のものだけでなく) が提供されます。

karaf@root()> config:property-set --pid org.ops4j.datasource.a7941498-9b62-4ed7-94f3-8c7ac9365313 useSSL false

karaf@root()> jdbc:ds-list
Name    │ Product │ Version │ URL                                  │ Status
────────┼─────────┼─────────┼──────────────────────────────────────┼───────
mysqlds │ MySQL   │ 5.7.21  │ jdbc:mysql://localhost:3306/reportdb │ OK

管理 ファクトリー PID の設定からのプロパティーは、関連する org.osgi.service.jdbc.DataSourceFactory 実装に渡されます。

pax-jdbc-config バンドルは、jdbc. で始まるプロパティーを処理します。これらのプロパティーを使用すると、すべてこの接頭辞が削除され、残りの名前が引き継がれます。

以下に例を示します。こちらも、Fuse の新規インストールから始めます。

karaf@root()> install -s mvn:mysql/mysql-connector-java/5.1.34
Bundle ID: 223
karaf@root()> install -s mvn:org.osgi/org.osgi.service.jdbc/1.0.0
Bundle ID: 224
karaf@root()> install -s mvn:org.ops4j.pax.jdbc/pax-jdbc-mysql/1.3.0
Bundle ID: 225
karaf@root()> install -s mvn:org.ops4j.pax.jdbc/pax-jdbc/1.3.0
Bundle ID: 226
karaf@root()> install -s mvn:org.ops4j.pax.jdbc/pax-jdbc-pool-common/1.3.0
Bundle ID: 227
karaf@root()> install -s mvn:org.ops4j.pax.jdbc/pax-jdbc-config/1.3.0
Bundle ID: 228

karaf@root()> config:edit --factory --alias mysql org.ops4j.datasource
karaf@root()> config:property-set osgi.jdbc.driver.name mysql
karaf@root()> config:property-set dataSourceName mysqlds
karaf@root()> config:property-set dataSourceType DataSource
karaf@root()> config:property-set jdbc.url jdbc:mysql://localhost:3306/reportdb
karaf@root()> config:property-set jdbc.user fuse
karaf@root()> config:property-set jdbc.password fuse
karaf@root()> config:property-set jdbc.useSSL false
karaf@root()> config:update

karaf@root()> config:list '(service.factoryPid=org.ops4j.datasource)'
----------------------------------------------------------------
Pid:            org.ops4j.datasource.7c3ee718-7309-46a0-ae3a-64b38b17a0a3
FactoryPid:     org.ops4j.datasource
BundleLocation: ?
Properties:
   dataSourceName = mysqlds
   dataSourceType = DataSource
   felix.fileinstall.filename = file:/data/servers/7.8.0.fuse-780038-redhat-00001/etc/org.ops4j.datasource-mysql.cfg
   jdbc.password = fuse
   jdbc.url = jdbc:mysql://localhost:3306/reportdb
   jdbc.useSSL = false
   jdbc.user = fuse
   osgi.jdbc.driver.name = mysql
   service.factoryPid = org.ops4j.datasource
   service.pid = org.ops4j.datasource.7c3ee718-7309-46a0-ae3a-64b38b17a0a3

karaf@root()> service:list javax.sql.DataSource
[javax.sql.DataSource]
----------------------
 dataSourceName = mysqlds
 dataSourceType = DataSource
 felix.fileinstall.filename = file:${karaf.etc}/org.ops4j.datasource-mysql.cfg
 jdbc.password = fuse
 jdbc.url = jdbc:mysql://localhost:3306/reportdb
 jdbc.user = fuse
 jdbc.useSSL = false
 osgi.jdbc.driver.name = mysql
 osgi.jndi.service.name = mysqlds
 pax.jdbc.managed = true
 service.bundleid = 228
 service.factoryPid = org.ops4j.datasource
 service.id = 246
 service.pid = org.ops4j.datasource.7c3ee718-7309-46a0-ae3a-64b38b17a0a3
 service.scope = singleton
Provided by :
 OPS4J Pax JDBC Config (228)

pax-jdbc-config バンドルには以下のプロパティーが必要です

関連する org.osgi.service.jdbc.DataSourceFactory メソッドを見つけて呼び出すには、以下を実行します。jdbc. の接頭辞が付けられたプロパティーは (接頭辞の削除後)、org.osgi.service.jdbc.DataSourceFactory.createDataSource(properties) などに渡されます。ただし、これらのプロパティーは、javax.sql.DataSource OSGi サービスなどのプロパティーとして、接頭辞を削除せずに追加されます。

以前の例では、データベース固有のデータソース ファクトリー を登録する方法を説明しました。データソース 自体は接続のファクトリーであるため、org.osgi.service.jdbc.DataSourceFactory は 3 種類のデータソースを生成できるメタファクトリー として扱われる可能性があります (さらに java.sql.Driver)。

たとえば、pax-jdbc-mysql は、以下を作成する org.ops4j.pax.jdbc.mysql.impl.MysqlDataSourceFactory を登録します。

PostgreSQL ドライバー自体は OSGi JDBC サービスを実装し、以下を生成します。

標準の DataSource 例 に記載されているように、JTA 環境で機能する場合は、プーリング、汎用 データソースは、(XA) 接続を実際に取得するには データベース固有 のデータソースが必要です。

すでに後者があるので、実際の信頼性がある、汎用接続プールが必要です。

標準の DataSource 例 は、データベース固有のデータソースを使用して汎用プールを設定する方法を示しています。pax-jdbc-pool-* バンドルは上記の org.osgi.service.jdbc.DataSourceFactory サービスとスムーズに連携します。

OSGI Enterprise R6 JDBC 仕様が org.osgi.service.jdbc.DataSourceFactory 標準インターフェイスを提供するのと同じように、pax-jdbc-pool-common は プロプライエタリーの org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory インターフェイスを提供します。

public interface PooledDataSourceFactory {

    javax.sql.DataSource create(org.osgi.service.jdbc.DataSourceFactory dsf, Properties config)

}

このインターフェイスは、以前に提示されたこの重要なメモに完全に準拠しており、繰り返す価値があります。

このインターフェイスは、データベース固有の非プーリングデータからプーリングデータソースを作成するだけです。また、これは データソースファクトリー(メタファクトリー) で、データベース固有のデータソースのファクトリーをデータソースのプーリングファクトリーに変換します。

以下の表は、プールされたデータソースファクトリーを登録するバンドルを示しています。この表では、o.o.p.j.p のインスタンスは org.ops4j.pax.jdbc.pool を表します。

上記のバンドルはデータソースファクトリーのみをインストールし、データソース自体にはインストールしません。アプリケーションは javax.sql.DataSource create(org.osgi.service.jdbc.DataSourceFactory dsf, Properties config) メソッドを呼び出す何かが必要です。

一般的なデータソースのセクションでは、Apache Commons DBCP モジュール を使用し、設定する方法の例 を紹介します。ここでは、Fuse OSGi 環境で設定方法を説明します。

「PAX-JDBC 設定サービス」 バンドルについて見てみましょう。以下を追跡するだけでなく、ほかも追跡します。

このバンドルは、pax-jdbc-pool-* バンドルのいずれかによって登録された org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory のインスタンスも追跡します。

ファクトリー設定 に pool プロパティーが含まれる場合、pax-jdbc-config バンドルによって登録される最終データソースはデータベース固有のデータソースになりますが、pool=dbcp2 の場合は以下のいずれかの内部でラッピングされます。

これは、一般的なデータソースの例 と同じです。pool プロパティーと、非 xa または xa データソースを選択するブール値 xa プロパティーの他に、org.ops4j.datasource ファクトリー PID に 接頭辞 が付いたプロパティーが含まれることがあります。

各プロパティーが使用される場所は、使用される pax-jdbc-pool-* バンドルによって異なります。DBCP2 の場合は以下のようになります。

# Configuration for pax-jdbc-config to choose and configure specific org.osgi.service.jdbc.DataSourceFactory
dataSourceName = mysqlds
dataSourceType = DataSource
osgi.jdbc.driver.name = mysql
jdbc.url = jdbc:mysql://localhost:3306/reportdb
jdbc.user = fuse
jdbc.password = fuse
jdbc.useSSL = false

# Hints for pax-jdbc-config to use org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory
pool = dbcp2
xa = false

# dbcp2 specific configuration of org.apache.commons.pool2.impl.GenericObjectPoolConfig
pool.minIdle = 10
pool.maxTotal = 100
pool.initialSize = 8
pool.blockWhenExhausted = true
pool.maxWaitMillis = 2000
pool.testOnBorrow = true
pool.testWhileIdle = false
pool.timeBetweenEvictionRunsMillis = 120000
pool.evictionPolicyClassName = org.apache.commons.pool2.impl.DefaultEvictionPolicy

# dbcp2 specific configuration of org.apache.commons.dbcp2.PoolableConnectionFactory
factory.maxConnLifetimeMillis = 30000
factory.validationQuery  = select schema_name from information_schema.schemata
factory.validationQueryTimeout = 2

karaf@root()> feature:install pax-jdbc-pool-dbcp2

karaf@root()> bundle:services -p org.ops4j.pax.jdbc.pool.dbcp2

OPS4J Pax JDBC Pooling DBCP2 (230) provides:
--------------------------------------------
objectClass = [org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory]
pool = dbcp2
service.bundleid = 230
service.id = 337
service.scope = singleton
xa = false
-----
objectClass = [org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory]
pool = dbcp2
service.bundleid = 230
service.id = 338
service.scope = singleton
xa = true

pax-jdbc-pool-narayna モジュールはほぼすべてが pax-jdbc-pool-dbcp2 として行われます。XA および XA 以外のシナリオ向けに DBCP2 固有の org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory をインストールします。唯一 の違いは、XA のシナリオでは追加の統合ポイントがあることです。org.jboss.tm.XAResourceRecovery OSGi サービスは、Narayana トランザクションマネージャーに含まれる com.arjuna.ats.arjuna.recovery.RecoveryManager で取得されるように登録されます。

pax-jdbc-pool-transx バンドルは、org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory サービスの実装を pax-transx-jdbc バンドルをもとにします。pax-transx-jdbc バンドルは、org.ops4j.pax.transx.jdbc.ManagedDataSourceBuilder 機能を使用して javax.sql.DataSource プールを作成します。これは JCA(Java™ Connector Architecture) ソリューションで、後 で説明します。

データソースの手動デプロイメントの例では、docker ベースの PostgreSQL インストールを使用します。この方法では、pax-jdbc-config は必要ありません。アプリケーションコードは、データベース固有および汎用データソースの両方の登録を行います。

これらの 3 つのバンドルが必要です。

<!--
    Database-specific, non-pooling, non-enlisting javax.sql.XADataSource
-->
<bean id="postgresql" class="org.postgresql.xa.PGXADataSource">
    <property name="url" value="jdbc:postgresql://localhost:5432/reportdb" />
    <property name="user" value="fuse" />
    <property name="password" value="fuse" />
    <property name="currentSchema" value="report" />
    <property name="connectTimeout" value="5" />
</bean>

<!--
    Fuse/Karaf exports this service from fuse-pax-transx-tm-narayana bundle
-->
<reference id="tm" interface="javax.transaction.TransactionManager" />

<!--
    Non database-specific, generic, pooling, enlisting javax.sql.DataSource
-->
<bean id="pool" class="org.apache.commons.dbcp2.managed.BasicManagedDataSource">
    <property name="xaDataSourceInstance" ref="postgresql" />
    <property name="transactionManager" ref="tm" />
    <property name="minIdle" value="3" />
    <property name="maxTotal" value="10" />
    <property name="validationQuery" value="select schema_name, schema_owner from information_schema.schemata" />
</bean>

<!--
    Expose datasource to use by application code (like Camel, Spring, ...)
-->
<service interface="javax.sql.DataSource" ref="pool">
    <service-properties>
        <entry key="osgi.jndi.service.name" value="jdbc/postgresql" />
    </service-properties>
</service>

上記の Blueprint XML フラグメントは 標準の DataSource 例 と一致します。以下は、その使用方法を示すシェルコマンドです。

karaf@root()> install -s mvn:org.postgresql/postgresql/42.2.5
Bundle ID: 233
karaf@root()> install -s mvn:org.apache.commons/commons-pool2/2.5.0
Bundle ID: 224
karaf@root()> install -s mvn:org.apache.commons/commons-dbcp2/2.1.1
Bundle ID: 225
karaf@root()> install -s blueprint:file://$PQ_HOME/databases/blueprints/postgresql-manual.xml
Bundle ID: 226

karaf@root()> bundle:services -p 226

Bundle 226 provides:
--------------------
objectClass = [javax.sql.DataSource]
osgi.jndi.service.name = jdbc/postgresql
osgi.service.blueprint.compname = pool
service.bundleid = 226
service.id = 242
service.scope = bundle
-----
objectClass = [org.osgi.service.blueprint.container.BlueprintContainer]
osgi.blueprint.container.symbolicname = postgresql-manual.xml
osgi.blueprint.container.version = 0.0.0
service.bundleid = 226
service.id = 243
service.scope = singleton

karaf@root()> feature:install jdbc

karaf@root()> jdbc:ds-list
Name            │ Product    │ Version                       │ URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           │ Status
────────────────┼────────────┼───────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────
jdbc/postgresql │ PostgreSQL │ 10.3 (Debian 10.3-1.pgdg90+1) │ jdbc:postgresql://localhost:5432/reportdb?prepareThreshold=5&preparedStatementCacheQueries=256&preparedStatementCacheSizeMiB=5&databaseMetadataCacheFields=65536&databaseMetadataCacheFieldsMiB=5&defaultRowFetchSize=0&binaryTransfer=true&readOnly=false&binaryTransferEnable=&binaryTransferDisable=&unknownLength=2147483647&logUnclosedConnections=false&disableColumnSanitiser=false&tcpKeepAlive=false&loginTimeout=0&connectTimeout=5&socketTimeout=0&cancelSignalTimeout=10&receiveBufferSize=-1&sendBufferSize=-1&ApplicationName=PostgreSQL JDBC Driver&jaasLogin=true&useSpnego=false&gsslib=auto&sspiServiceClass=POSTGRES&allowEncodingChanges=false&currentSchema=report&targetServerType=any&loadBalanceHosts=false&hostRecheckSeconds=10&preferQueryMode=extended&autosave=never&reWriteBatchedInserts=false │ OK

karaf@root()> jdbc:query jdbc/postgresql 'select * from incident';
date                │ summary    │ name   │ details                       │ id │ email
────────────────────┼────────────┼────────┼───────────────────────────────┼────┼─────────────────
2018-02-20 08:00:00 │ Incident 1 │ User 1 │ This is a report incident 001 │ 1  │ user1@redhat.com
2018-02-20 08:10:00 │ Incident 2 │ User 2 │ This is a report incident 002 │ 2  │ user2@redhat.com
2018-02-20 08:20:00 │ Incident 3 │ User 3 │ This is a report incident 003 │ 3  │ user3@redhat.com
2018-02-20 08:30:00 │ Incident 4 │ User 4 │ This is a report incident 004 │ 4  │ user4@redhat.com

上記の一覧に示すように、Blueprint バンドルは、汎用的でデータベース固有でない接続プールである javax.sql.DataSource サービスをエクスポートします。Blueprint XML には明示的な <service ref="postgresql"> 宣言がないため、データベース固有の javax.sql.XADataSource バンドルは OSGi サービスとして登録されません。

データソースのファクトリーデプロイメントは、標準的 な方法で pax-jdbc-config バンドルを使用します。これは、サービスプロパティーとしてプーリング設定を指定する必要があった Fuse6.x で推奨されていた方法とは少し異なります。

Blueprint XML の例を以下に示します。

<!--
    A database-specific org.osgi.service.jdbc.DataSourceFactory that can create DataSource/XADataSource/
    /ConnectionPoolDataSource/Driver using properties. It is registered by pax-jdbc-* or for example
    mvn:org.postgresql/postgresql/42.2.5 bundle natively.
-->
<reference id="dataSourceFactory"
        interface="org.osgi.service.jdbc.DataSourceFactory"
        filter="(osgi.jdbc.driver.class=org.postgresql.Driver)" />

<!--
    Non database-specific org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory that can create
    pooled data sources using some org.osgi.service.jdbc.DataSourceFactory. dbcp2 pool is registered
    by pax-jdbc-pool-dbcp2 bundle.
-->
<reference id="pooledDataSourceFactory"
        interface="org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory"
        filter="(&amp;(pool=dbcp2)(xa=true))" />

<!--
    Finally, use both factories to expose pooled, xa-aware data source.
-->
<bean id="pool" factory-ref="pooledDataSourceFactory" factory-method="create">
    <argument ref="dataSourceFactory" />
    <argument>
        <props>
            <!--
                Properties needed by postgresql-specific org.osgi.service.jdbc.DataSourceFactory.
                Cannot prepend them with 'jdbc.' prefix as the DataSourceFactory is implemented directly
                by PostgreSQL driver, not by pax-jdbc-* bundle.
            -->
            <prop key="url" value="jdbc:postgresql://localhost:5432/reportdb" />
            <prop key="user" value="fuse" />
            <prop key="password" value="fuse" />
            <prop key="currentSchema" value="report" />
            <prop key="connectTimeout" value="5" />
            <!-- Properties needed by dbcp2-specific org.ops4j.pax.jdbc.pool.common.PooledDataSourceFactory -->
            <prop key="pool.minIdle" value="2" />
            <prop key="pool.maxTotal" value="10" />
            <prop key="pool.blockWhenExhausted" value="true" />
            <prop key="pool.maxWaitMillis" value="2000" />
            <prop key="pool.testOnBorrow" value="true" />
            <prop key="pool.testWhileIdle" value="false" />
            <prop key="factory.validationQuery" value="select schema_name from information_schema.schemata" />
            <prop key="factory.validationQueryTimeout" value="2" />
        </props>
    </argument>
</bean>

<!--
    Expose data source for use by application code (such as  Camel, Spring, ...).
-->
<service interface="javax.sql.DataSource" ref="pool">
    <service-properties>
        <entry key="osgi.jndi.service.name" value="jdbc/postgresql" />
    </service-properties>
</service>

この例では、データソース ファクトリー を使用してデータソースを作成するファクトリー Bean を使用します。XA 対応の PooledDataSourceFactory によって内部的に追跡されるため、javax.transaction.TransactionManager サービスを明示的に参照する必要はありません。

以下の例は Fuse/Karaf シェルと同じです。

karaf@root()> feature:install jdbc pax-jdbc-config pax-jdbc-pool-dbcp2
karaf@root()> install -s mvn:org.postgresql/postgresql/42.2.5
Bundle ID: 232
karaf@root()> install -s blueprint:file://$PQ_HOME/databases/blueprints/postgresql-pax-jdbc-factory-dbcp2.xml
Bundle ID: 233
karaf@root()> bundle:services -p 233

Bundle 233 provides:
--------------------
objectClass = [javax.sql.DataSource]
osgi.jndi.service.name = jdbc/postgresql
osgi.service.blueprint.compname = pool
service.bundleid = 233
service.id = 336
service.scope = bundle
-----
objectClass = [org.osgi.service.blueprint.container.BlueprintContainer]
osgi.blueprint.container.symbolicname = postgresql-pax-jdbc-factory-dbcp2.xml
osgi.blueprint.container.version = 0.0.0
service.bundleid = 233
service.id = 337
service.scope = singleton

karaf@root()> jdbc:ds-list
Name            │ Product    │ Version                       │ URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           │ Status
────────────────┼────────────┼───────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────
jdbc/postgresql │ PostgreSQL │ 10.3 (Debian 10.3-1.pgdg90+1) │ jdbc:postgresql://localhost:5432/reportdb?prepareThreshold=5&preparedStatementCacheQueries=256&preparedStatementCacheSizeMiB=5&databaseMetadataCacheFields=65536&databaseMetadataCacheFieldsMiB=5&defaultRowFetchSize=0&binaryTransfer=true&readOnly=false&binaryTransferEnable=&binaryTransferDisable=&unknownLength=2147483647&logUnclosedConnections=false&disableColumnSanitiser=false&tcpKeepAlive=false&loginTimeout=0&connectTimeout=5&socketTimeout=0&cancelSignalTimeout=10&receiveBufferSize=-1&sendBufferSize=-1&ApplicationName=PostgreSQL JDBC Driver&jaasLogin=true&useSpnego=false&gsslib=auto&sspiServiceClass=POSTGRES&allowEncodingChanges=false&currentSchema=report&targetServerType=any&loadBalanceHosts=false&hostRecheckSeconds=10&preferQueryMode=extended&autosave=never&reWriteBatchedInserts=false │ OK

karaf@root()> jdbc:query jdbc/postgresql 'select * from incident';
date                │ summary    │ name   │ details                       │ id │ email
────────────────────┼────────────┼────────┼───────────────────────────────┼────┼─────────────────
2018-02-20 08:00:00 │ Incident 1 │ User 1 │ This is a report incident 001 │ 1  │ user1@redhat.com
2018-02-20 08:10:00 │ Incident 2 │ User 2 │ This is a report incident 002 │ 2  │ user2@redhat.com
2018-02-20 08:20:00 │ Incident 3 │ User 3 │ This is a report incident 003 │ 3  │ user3@redhat.com
2018-02-20 08:30:00 │ Incident 4 │ User 4 │ This is a report incident 004 │ 4  │ user4@redhat.com

上記の一覧に示すように、Blueprint バンドルは、汎用的でデータベース固有でない接続プールである javax.sql.DataSource サービスをエクスポートします。Blueprint XML には明示的な <service ref="postgresql"> 宣言がないため、データベース固有の javax.sql.XADataSource バンドルは OSGi サービスとして登録されません。

データソースの混合デプロイメントでは、pax-jdbc-config 1.3.0 バンドルは、サービスプロパティーを使用して、プーリングデータソース内でデータベース固有のデータソースを ラッピング する別の方法を追加します。このメソッドは、Fuse 6.x で動作した方法と一致します。

以下は Blueprint XML の例です。

<!--
    Database-specific, non-pooling, non-enlisting javax.sql.XADataSource
-->
<bean id="postgresql" class="org.postgresql.xa.PGXADataSource">
    <property name="url" value="jdbc:postgresql://localhost:5432/reportdb" />
    <property name="user" value="fuse" />
    <property name="password" value="fuse" />
    <property name="currentSchema" value="report" />
    <property name="connectTimeout" value="5" />
</bean>

<!--
    Expose database-specific data source with service properties.
    No need to expose pooling, enlisting, non database-specific javax.sql.DataSource. It is registered
    automatically by pax-jdbc-config with the same properties as this <service>, but with higher service.ranking.
-->
<service id="pool" ref="postgresql" interface="javax.sql.XADataSource">
    <service-properties>
        <!-- "pool" key is needed for pax-jdbc-config to wrap database-specific data source inside connection pool -->
        <entry key="pool" value="dbcp2" />
        <entry key="osgi.jndi.service.name" value="jdbc/postgresql" />
        <!-- Other properties that configure given connection pool, as indicated by pool=dbcp2 -->
        <entry key="pool.minIdle" value="2" />
        <entry key="pool.maxTotal" value="10" />
        <entry key="pool.blockWhenExhausted" value="true" />
        <entry key="pool.maxWaitMillis" value="2000" />
        <entry key="pool.testOnBorrow" value="true" />
        <entry key="pool.testWhileIdle" value="false" />
        <entry key="factory.validationQuery" value="select schema_name from information_schema.schemata" />
        <entry key="factory.validationQueryTimeout" value="2" />
    </service-properties>
</service>

上記の例では、データベース固有のデータソースのみが手動で登録されています。pool=dbcp2 サービスプロパティーは、pax-jdbc-config バンドルによって管理されるデータソーストラッカーのヒントです。このサービスプロパティーを持つデータソースサービスは、プーリングデータソース内でラップされます (この例では pax-jdbc-pool-dbcp2)。

以下は、Fuse/Karaf シェルと同じ例です。

karaf@root()> feature:install jdbc pax-jdbc-config pax-jdbc-pool-dbcp2
karaf@root()> install -s mvn:org.postgresql/postgresql/42.2.5
Bundle ID: 232
karaf@root()> install -s blueprint:file://$PQ_HOME/databases/blueprints/postgresql-pax-jdbc-discovery.xml
Bundle ID: 233
karaf@root()> bundle:services -p 233

Bundle 233 provides:
--------------------
factory.validationQuery = select schema_name from information_schema.schemata
factory.validationQueryTimeout = 2
objectClass = [javax.sql.XADataSource]
osgi.jndi.service.name = jdbc/postgresql
osgi.service.blueprint.compname = postgresql
pool = dbcp2
pool.blockWhenExhausted = true
pool.maxTotal = 10
pool.maxWaitMillis = 2000
pool.minIdle = 2
pool.testOnBorrow = true
pool.testWhileIdle = false
service.bundleid = 233
service.id = 336
service.scope = bundle
-----
objectClass = [org.osgi.service.blueprint.container.BlueprintContainer]
osgi.blueprint.container.symbolicname = postgresql-pax-jdbc-discovery.xml
osgi.blueprint.container.version = 0.0.0
service.bundleid = 233
service.id = 338
service.scope = singleton

karaf@root()> service:list javax.sql.XADataSource
[javax.sql.XADataSource]
------------------------
 factory.validationQuery = select schema_name from information_schema.schemata
 factory.validationQueryTimeout = 2
 osgi.jndi.service.name = jdbc/postgresql
 osgi.service.blueprint.compname = postgresql
 pool = dbcp2
 pool.blockWhenExhausted = true
 pool.maxTotal = 10
 pool.maxWaitMillis = 2000
 pool.minIdle = 2
 pool.testOnBorrow = true
 pool.testWhileIdle = false
 service.bundleid = 233
 service.id = 336
 service.scope = bundle
Provided by :
 Bundle 233
Used by:
 OPS4J Pax JDBC Config (224)

karaf@root()> service:list javax.sql.DataSource
[javax.sql.DataSource]
----------------------
 factory.validationQuery = select schema_name from information_schema.schemata
 factory.validationQueryTimeout = 2
 osgi.jndi.service.name = jdbc/postgresql
 osgi.service.blueprint.compname = postgresql
 pax.jdbc.managed = true
 pax.jdbc.service.id.ref = 336
 pool.blockWhenExhausted = true
 pool.maxTotal = 10
 pool.maxWaitMillis = 2000
 pool.minIdle = 2
 pool.testOnBorrow = true
 pool.testWhileIdle = false
 service.bundleid = 224
 service.id = 337
 service.ranking = 1000
 service.scope = singleton
Provided by :
 OPS4J Pax JDBC Config (224)

karaf@root()> jdbc:ds-list
Name            │ Product    │ Version                       │ URL                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           │ Status
────────────────┼────────────┼───────────────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┼───────
jdbc/postgresql │ PostgreSQL │ 10.3 (Debian 10.3-1.pgdg90+1) │ jdbc:postgresql://localhost:5432/reportdb?prepareThreshold=5&preparedStatementCacheQueries=256&preparedStatementCacheSizeMiB=5&databaseMetadataCacheFields=65536&databaseMetadataCacheFieldsMiB=5&defaultRowFetchSize=0&binaryTransfer=true&readOnly=false&binaryTransferEnable=&binaryTransferDisable=&unknownLength=2147483647&logUnclosedConnections=false&disableColumnSanitiser=false&tcpKeepAlive=false&loginTimeout=0&connectTimeout=5&socketTimeout=0&cancelSignalTimeout=10&receiveBufferSize=-1&sendBufferSize=-1&ApplicationName=PostgreSQL JDBC Driver&jaasLogin=true&useSpnego=false&gsslib=auto&sspiServiceClass=POSTGRES&allowEncodingChanges=false&currentSchema=report&targetServerType=any&loadBalanceHosts=false&hostRecheckSeconds=10&preferQueryMode=extended&autosave=never&reWriteBatchedInserts=false │ OK
jdbc/postgresql │ PostgreSQL │ 10.3 (Debian 10.3-1.pgdg90+1) │ jdbc:postgresql://localhost:5432/reportdb?prepareThreshold=5&preparedStatementCacheQueries=256&preparedStatementCacheSizeMiB=5&databaseMetadataCacheFields=65536&databaseMetadataCacheFieldsMiB=5&defaultRowFetchSize=0&binaryTransfer=true&readOnly=false&binaryTransferEnable=&binaryTransferDisable=&unknownLength=2147483647&logUnclosedConnections=false&disableColumnSanitiser=false&tcpKeepAlive=false&loginTimeout=0&connectTimeout=5&socketTimeout=0&cancelSignalTimeout=10&receiveBufferSize=-1&sendBufferSize=-1&ApplicationName=PostgreSQL JDBC Driver&jaasLogin=true&useSpnego=false&gsslib=auto&sspiServiceClass=POSTGRES&allowEncodingChanges=false&currentSchema=report&targetServerType=any&loadBalanceHosts=false&hostRecheckSeconds=10&preferQueryMode=extended&autosave=never&reWriteBatchedInserts=false │ OK

karaf@root()> jdbc:query jdbc/postgresql 'select * from incident'
date                │ summary    │ name   │ details                       │ id │ email
────────────────────┼────────────┼────────┼───────────────────────────────┼────┼─────────────────
2018-02-20 08:00:00 │ Incident 1 │ User 1 │ This is a report incident 001 │ 1  │ user1@redhat.com
2018-02-20 08:10:00 │ Incident 2 │ User 2 │ This is a report incident 002 │ 2  │ user2@redhat.com
2018-02-20 08:20:00 │ Incident 3 │ User 3 │ This is a report incident 003 │ 3  │ user3@redhat.com
2018-02-20 08:30:00 │ Incident 4 │ User 4 │ This is a report incident 004 │ 4  │ user4@redhat.com

このリストには、jdbc:ds-list 出力からわかるように、元のデータソースとラッパーデータソースという 2 つのデータソースがあります。

javax.sql.XADataSource は Blueprint バンドルから登録され、pool = dbcp2 プロパティーが宣言されています。

javax.sql.DataSource は pax-jdbc-config バンドルから登録されます。また、

META-INF/persistence.xml 記述子 (JPA 2.1 仕様 8.2.1.5 jta-data-source, non-jta-data-sourceを参照) は、2 種類のデータソース参照を定義します。

これらの 2 つのデータソースは、javax.sql.DataSource または javax.sql.XADataSource とは関連性がありません。これは、JPA アプリケーションを開発する時によくある誤解です。両方の JNDI 名は JNDI でバインドされた javax.sql.DataSource サービスを参照する必要があります。

OSGi サービスを osgi.jndi.service.name プロパティーに登録すると、OSGi JNDI サービスで バインドされます。OSGi ランタイム (Fuse/Karaf など) では、JNDI は name → value ペアの単純なディクショナリーではありません。OSGi の JNDI 名を使用してオブジェクトを参照するには、サービスルックアップやその他の複雑な OSGi メカニズム (サービスフックなど) が必要です。

Fuse の新規インストールでは、以下のリストはデータソースが JNDI に登録される方法を示します。

karaf@root()> install -s mvn:mysql/mysql-connector-java/5.1.34
Bundle ID: 223
karaf@root()> install -s mvn:org.osgi/org.osgi.service.jdbc/1.0.0
Bundle ID: 224
karaf@root()> install -s mvn:org.ops4j.pax.jdbc/pax-jdbc-mysql/1.3.0
Bundle ID: 225
karaf@root()> install -s mvn:org.ops4j.pax.jdbc/pax-jdbc/1.3.0
Bundle ID: 226
karaf@root()> install -s mvn:org.ops4j.pax.jdbc/pax-jdbc-pool-common/1.3.0
Bundle ID: 227
karaf@root()> install -s mvn:org.ops4j.pax.jdbc/pax-jdbc-config/1.3.0
Bundle ID: 228

karaf@root()> config:edit --factory --alias mysql org.ops4j.datasource
karaf@root()> config:property-set osgi.jdbc.driver.name mysql
karaf@root()> config:property-set dataSourceName mysqlds
karaf@root()> config:property-set osgi.jndi.service.name jdbc/mysqlds
karaf@root()> config:property-set dataSourceType DataSource
karaf@root()> config:property-set jdbc.url jdbc:mysql://localhost:3306/reportdb
karaf@root()> config:property-set jdbc.user fuse
karaf@root()> config:property-set jdbc.password fuse
karaf@root()> config:property-set jdbc.useSSL false
karaf@root()> config:update

karaf@root()> feature:install jndi

karaf@root()> jndi:names
JNDI Name                 │ Class Name
──────────────────────────┼───────────────────────────────────────────────
osgi:service/jndi         │ org.apache.karaf.jndi.internal.JndiServiceImpl
osgi:service/jdbc/mysqlds │ com.mysql.jdbc.jdbc2.optional.MysqlDataSource

ご覧のとおり、データソースは osgi:service/jdbc/mysqlds JNDI 名で利用できます。

しかし、OSGi の JPA の場合は、完全な JNDI 名 を使用する必要があります。以下は、データソース参照を指定する META-INF/persistence.xml フラグメントの例です。

<jta-data-source>
    osgi:service/javax.sql.DataSource/(osgi.jndi.service.name=jdbc/mysqlds)
</jta-data-source>
<non-jta-data-source>
    osgi:service/javax.sql.DataSource/(osgi.jndi.service.name=jdbc/mysqlds)
</non-jta-data-source>

上記の設定がないと、以下のエラーが発生する可能性があります。

Persistence unit "pu-name" refers to a non OSGi service DataSource

以下は、Artemis ブローカーの接続ファクターを作成する方法を順をおって説明した 標準的 なガイドです。

これで、必要に応じて挿入できるブローカー固有の (まだプールなし) 接続ファクトリーができました。たとえば、jms 機能から Karaf コマンドを使用できます。

karaf@root()> feature:install -v jms
Adding features: jms/[4.2.0.fuse-000237-redhat-1,4.2.0.fuse-000237-redhat-1]
...
karaf@root()> jms:connectionfactories
JMS Connection Factory
──────────────────────
jms/artemis

karaf@root()> jms:info -u admin -p admin jms/artemis
Property │ Value
─────────┼──────────────────────────
product  │ ActiveMQ
version  │ 2.4.0.amq-711002-redhat-1

karaf@root()> jms:send -u admin -p admin jms/artemis DEV.QUEUE.1 "Hello Artemis"

karaf@root()> jms:browse -u admin -p admin jms/artemis DEV.QUEUE.1
Message ID                              │ Content       │ Charset │ Type │ Correlation ID │ Delivery Mode │ Destination                │ Expiration │ Priority │ Redelivered │ ReplyTo │ Timestamp
────────────────────────────────────────┼───────────────┼─────────┼──────┼────────────────┼───────────────┼────────────────────────────┼────────────┼──────────┼─────────────┼─────────┼──────────────────────────────
ID:2b6ea56d-574d-11e8-971a-7ee9ecc029d4 │ Hello Artemis │ UTF-8   │      │                │ Persistent    │ ActiveMQQueue[DEV.QUEUE.1] │ Never      │ 4        │ false       │         │ Mon May 14 10:02:38 CEST 2018

次のリストは、プロトコルを切り替えたときに何が起こるかを示しています。

karaf@root()> config:list '(service.factoryPid=org.ops4j.connectionfactory)'
----------------------------------------------------------------
Pid:            org.ops4j.connectionfactory.965d4eac-f5a7-4f65-ba1a-15caa4c72703
FactoryPid:     org.ops4j.connectionfactory
BundleLocation: ?
Properties:
   connectionFactoryType = ConnectionFactory
   felix.fileinstall.filename = file:${karaf.etc}/org.ops4j.connectionfactory-artemis.cfg
   jms.consumerMaxRate = 1234
   jms.password = fuse
   jms.url = tcp://localhost:61616
   jms.user = fuse
   osgi.jndi.service.name = jms/artemis
   service.factoryPid = org.ops4j.connectionfactory
   service.pid = org.ops4j.connectionfactory.965d4eac-f5a7-4f65-ba1a-15caa4c72703
   type = artemis

karaf@root()> config:edit org.ops4j.connectionfactory.312eb09a-d686-4229-b7e1-2ea38a77bb0f
karaf@root()> config:property-set protocol amqp
karaf@root()> config:property-delete user
karaf@root()> config:property-set username admin # mind the difference between artemis-jms-client and qpid-jms-client
karaf@root()> config:property-set jms.url amqp://localhost:61616
karaf@root()> config:update

karaf@root()> jms:info -u admin -p admin jms/artemis
Property │ Value
─────────┼────────────────
product  │ QpidJMS
version  │ 0.30.0.redhat-1

karaf@root()> jms:browse -u admin -p admin jms/artemis DEV.QUEUE.1
Message ID │ Content       │ Charset │ Type │ Correlation ID │ Delivery Mode │ Destination │ Expiration │ Priority │ Redelivered │ ReplyTo │ Timestamp
───────────┼───────────────┼─────────┼──────┼────────────────┼───────────────┼─────────────┼────────────┼──────────┼─────────────┼─────────┼──────────────────────────────
           │ Hello Artemis │ UTF-8   │      │                │ Persistent    │ DEV.QUEUE.1 │ Never      │ 4        │ false       │         │ Mon May 14 10:02:38 CEST 2018

このセクションでは、IBM MQ 8 および IBM MQ 9 に接続する方法を説明します。pax-jms-ibmmq は関連する pax-jms バンドルをインストールしますが、ライセンス上の理由から IBM MQ ドライバーはインストールされません。

メッセージが IBM MQ Explorer から送信されたのか、Web コンソールから送信されたのかを確認することもできます。

Fuse の Software Downloads ページから Fuse quickstarts をダウンロードできます。

クイックスタート zip ファイルの内容をローカルフォルダーに展開します (例: quickstarts という名前のフォルダー)。

次に、quickstarts/camel/camel-jms の例を OSGi バンドルとしてビルドしてインストールできます。このバンドルには、メッセージを JBoss A-MQ 6.3 JMS キューに送信する Camel ルートの Blueprint XML 定義が含まれます。JBoss A-MQ 6.3 ブローカーの接続ファクトリーを作成する手順は次のとおりです。

Configuration Admin ファクトリー PID からのプロパティーは、関連する org.ops4j.pax.jms.service.ConnectionFactoryFactory 実装に渡されます。

これまで、ブローカー固有の接続 ファクトリー を登録しました。接続ファクトリー自体は 接続ファクトリー のファクトリーであるため、org.ops4j.pax.jms.service.ConnectionFactoryFactory サービスはメタファクトリーとして扱われる可能性があります。2 種類の接続ファクトリーを生成できるはずです。

pax-jms-pool-* バンドルは、org.ops4j.pax.jms.service.ConnectionFactoryFactory サービスとスムーズに連携します。これらのバンドルは、org.ops4j.pax.jms.service.PooledConnectionFactoryFactory の実装を提供し、これで、プロパティーと、元の org.ops4j.pax.jms.service.ConnectionFactoryFactory を wrapper のように使用して、プール接続ファクトリーを作成できます。以下に例を示します。

public interface PooledConnectionFactoryFactory {

    ConnectionFactory create(ConnectionFactoryFactory cff, Map<String, Object> props);

}

以下の表は、プールされた接続ファクトリーファクトリーを登録するバンドルを示しています。この表では、o.o.p.j.p は org.ops4j.pax.jms.pool を表します。

上記のバンドルは接続ファクトリーファクトリーのみをインストールします。接続ファクトリー自体をインストールしないバンドルです。そのため、javax.jms.ConnectionFactory org.ops4j.pax.jms.service.PooledConnectionFactoryFactory.create() メソッドを呼び出すものが必要になります。

pax-jms-pool-pooledjms バンドルの使用方法を理解することで、pax-jms-pool-pooledjms バンドルだけでなく、pax-jms-pool-narayna バンドルも使用できるので、pax-jms-pool-pool-pooledjms としてほぼすべてが機能します。

pax-jms-config バンドルは以下を追跡します。

ファクトリー設定 に pool プロパティーが含まれる場合、pax-jms-config バンドルによって登録される最終的な接続ファクトリーはブローカー固有の接続ファクトリーです。pool=pooledjms の場合、接続ファクトリーは以下のいずれかの内部でラップされます。

pool プロパティー (および非 xa/xa 接続ファクトリーの 1 つを選択するブール値 xa プロパティー) のほかに、org.ops4j.connectionfactory ファクトリー PID には pool. で始まるプロパティーが含まれる場合があります。

pooled-jms ライブラリーでは、これらの接頭辞が付いたプロパティーを使用して (接頭辞を削除した後に)、以下のインスタンスを設定します。

以下のリストは、jms. で始まるプロパティーと便利な構文を使用する pooled-jms プール (org.ops4j.connectionfactory-artemis ファクトリー PID) の現実的な設定です。

# configuration for pax-jms-config to choose and configure specific org.ops4j.pax.jms.service.ConnectionFactoryFactory
name = jms/artemis
connectionFactoryType = ConnectionFactory
jms.url = tcp://localhost:61616
jms.user = fuse
jms.password = fuse
# org.apache.activemq.artemis.jms.client.ActiveMQConnectionFactory specific coniguration
jms.callTimeout = 12000
# ...

# hints for pax-jms-config to use selected org.ops4j.pax.jms.service.PooledConnectionFactoryFactory
pool = pooledjms
xa = false

# pooled-jms specific configuration of org.messaginghub.pooled.jms.JmsPoolConnectionFactory
pool.idleTimeout = 10
pool.maxConnections = 100
pool.blockIfSessionPoolIsFull = true
# ...

上記の設定では、pool と xa キーは ヒント (サービスフィルタープロパティー) で、登録された org.ops4j.pax.jms.service.PooledConnectionFactoryFactory サービスのいずれかを選択します。pooled-jms ライブラリーの場合、以下が行われます。

karaf@root()> feature:install pax-jms-pool-pooledjms

karaf@root()> bundle:services -p org.ops4j.pax.jms.pax-jms-pool-pooledjms

OPS4J Pax JMS MessagingHub JMS Pool implementation (252) provides:
------------------------------------------------------------------
objectClass = [org.ops4j.pax.jms.service.PooledConnectionFactoryFactory]
pool = pooledjms
service.bundleid = 252
service.id = 331
service.scope = singleton
xa = false
-----
objectClass = [org.ops4j.pax.jms.service.PooledConnectionFactoryFactory]
pool = pooledjms
service.bundleid = 252
service.id = 335
service.scope = singleton
xa = true

以下は、接続プールを作成して設定する手順の完全な例です。

pax-jms-pool-narayna モジュールはほぼすべてが pax-jms-pool-pooledjms として行われます。XA と XA 以外のシナリオ向けに、pooled-jms 固有の org.ops4j.pax.jms.service.PooledConnectionFactoryFactory をインストールします。唯一 の違いは XA シナリオでは、追加の統合ポイントがあることです。org.jboss.tm.XAResourceRecovery OSGi サービスは、com.arjuna.ats.arjuna.recovery.RecoveryManager によって取得されるように登録されます。

pax-jms-pool-transx モジュールは、pax-transx-jms バンドルに基づく org.ops4j.pax.jms.service.PooledConnectionFactoryFactory サービスの実装を提供します。pax-transx-jms バンドルは、org.ops4j.pax.transx.jms.ManagedConnectionFactoryBuilder 機能を使用して javax.jms.ConnectionFactory プールを作成します。これは、「pax-transx プロジェクト」 で説明されている JCA(Java™ Connector Architecture) ソリューションです。

この方法では、pax-jms-config バンドルは必要ありません。アプリケーションコードは、ブローカー固有および汎用接続プールの両方の登録を行います。

<!--
    Broker-specific, non-pooling, non-enlisting javax.jms.XAConnectionFactory
-->
<bean id="artemis" class="org.apache.activemq.artemis.jms.client.ActiveMQXAConnectionFactory">
    <argument value="tcp://localhost:61616" />
    <property name="callTimeout" value="2000" />
    <property name="initialConnectAttempts" value="3" />
</bean>

<!--
    Fuse exports this service from fuse-pax-transx-tm-narayana bundle.
-->
<reference id="tm" interface="javax.transaction.TransactionManager" />

<!--
    Non broker-specific, generic, pooling, enlisting javax.jms.ConnectionFactory
-->
<bean id="pool" class="org.messaginghub.pooled.jms.JmsPoolXAConnectionFactory">
    <property name="connectionFactory" ref="artemis" />
    <property name="transactionManager" ref="tm" />
    <property name="maxConnections" value="10" />
    <property name="idleTimeout" value="10000" />
</bean>

<!--
    Expose connection factory for use by application code (such as Camel, Spring, ...)
-->
<service interface="javax.jms.ConnectionFactory" ref="pool">
    <service-properties>
        <!-- Giving connection factory a name using one of these properties makes identification easier in jms:connectionfactories: -->
        <entry key="osgi.jndi.service.name" value="jms/artemis" />
        <!--<entry key="name" value="jms/artemis" />-->
        <!-- Without any of the above, name will fall back to "service.id" -->
    </service-properties>
</service>

以下は、その使用方法を示すシェルコマンドです。

karaf@root()> feature:install artemis-core-client artemis-jms-client
karaf@root()> install -s mvn:org.apache.commons/commons-pool2/2.5.0
Bundle ID: 244
karaf@root()> install -s mvn:org.messaginghub/pooled-jms/0.3.0
Bundle ID: 245
karaf@root()> install -s blueprint:file://$PQ_HOME/message-brokers/blueprints/artemis-manual.xml
Bundle ID: 246

karaf@root()> bundle:services -p 246

Bundle 246 provides:
--------------------
objectClass = [javax.jms.ConnectionFactory]
osgi.jndi.service.name = jms/artemis
osgi.service.blueprint.compname = pool
service.bundleid = 246
service.id = 340
service.scope = bundle
-----
objectClass = [org.osgi.service.blueprint.container.BlueprintContainer]
osgi.blueprint.container.symbolicname = artemis-manual.xml
osgi.blueprint.container.version = 0.0.0
service.bundleid = 246
service.id = 341
service.scope = singleton

karaf@root()> feature:install jms

karaf@root()> jms:connectionfactories
JMS Connection Factory
──────────────────────
jms/artemis

karaf@root()> jms:info -u admin -p admin jms/artemis
Property │ Value
─────────┼──────────────────────────
product  │ ActiveMQ
version  │ 2.4.0.amq-711002-redhat-1

上記の一覧に示すように、Blueprint バンドルは、汎用的でブローカー固有でない接続プールである javax.jms.ConnectionFactory サービスをエクスポートします。Blueprint XML には明示的な <service ref="artemis"> 宣言がないため、ブローカー固有の javax.jms.XAConnectionFactory は OSGi サービスとして登録されません。

このメソッドは、標準 の方法での pax-jms-config の使用方法を示しています。これは、Fuse 6.x で推奨されていた方法とは少し異なります。この方法では、サービスプロパティーとしてプーリング設定を指定する必要がありました。

Blueprint XML の例を以下に示します。

<!--
    A broker-specific org.ops4j.pax.jms.service.ConnectionFactoryFactory that can create (XA)ConnectionFactory
    using properties. It is registered by pax-jms-* bundles
-->
<reference id="connectionFactoryFactory"
        interface="org.ops4j.pax.jms.service.ConnectionFactoryFactory"
        filter="(type=artemis)" />

<!--
    Non broker-specific org.ops4j.pax.jms.service.PooledConnectionFactoryFactory that can create
    pooled connection factories with the help of org.ops4j.pax.jms.service.ConnectionFactoryFactory

    For example, pax-jms-pool-pooledjms bundle registers org.ops4j.pax.jms.service.PooledConnectionFactoryFactory
    with these properties:
     - pool = pooledjms
     - xa = true|false (both are registered)
-->
<reference id="pooledConnectionFactoryFactory"
        interface="org.ops4j.pax.jms.service.PooledConnectionFactoryFactory"
        filter="(&amp;(pool=pooledjms)(xa=true))" />

<!--
    When using XA connection factories, javax.transaction.TransactionManager service is not needed here.
    It is used internally by xa-aware pooledConnectionFactoryFactory.
-->
<!--<reference id="tm" interface="javax.transaction.TransactionManager" />-->

<!--
    Finally, use both factories to expose the pooled, xa-aware, connection factory.
-->
<bean id="pool" factory-ref="pooledConnectionFactoryFactory" factory-method="create">
    <argument ref="connectionFactoryFactory" />
    <argument>
        <props>
            <!--
                Properties needed by artemis-specific org.ops4j.pax.jms.service.ConnectionFactoryFactory
            -->
            <prop key="jms.url" value="tcp://localhost:61616" />
            <prop key="jms.callTimeout" value="2000" />
            <prop key="jms.initialConnectAttempts" value="3" />
            <!-- Properties needed by pooled-jms-specific org.ops4j.pax.jms.service.PooledConnectionFactoryFactory -->
            <prop key="pool.maxConnections" value="10" />
            <prop key="pool.idleTimeout" value="10000" />
        </props>
    </argument>
</bean>

<!--
    Expose connection factory for use by application code (such as Camel, Spring, ...)
-->
<service interface="javax.jms.ConnectionFactory" ref="pool">
    <service-properties>
        <!-- Giving connection factory a name using one of these properties makes identification easier in jms:connectionfactories: -->
        <entry key="osgi.jndi.service.name" value="jms/artemis" />
        <!--<entry key="name" value="jms/artemis" />-->
        <!-- Without any of the above, name will fall back to "service.id" -->
    </service-properties>
</service>

前述の例は、接続ファクトリーのファクトリーを使用して、接続ファクトリーを作成するファクトリー Bean を使用します。XA 対応の PooledConnectionFactoryFactory によって内部的に追跡されるため、javax.transaction.TransactionManager サービスを明示的に参照する必要はありません。

Fuse/Karaf シェルでは、以下のようになります。

karaf@root()> feature:install jms pax-jms-artemis pax-jms-pool-pooledjms

karaf@root()> install -s blueprint:file://$PQ_HOME/message-brokers/blueprints/artemis-pax-jms-factory-pooledjms.xml
Bundle ID: 253
karaf@root()> bundle:services -p 253

Bundle 253 provides:
--------------------
objectClass = [javax.jms.ConnectionFactory]
osgi.jndi.service.name = jms/artemis
osgi.service.blueprint.compname = pool
service.bundleid = 253
service.id = 347
service.scope = bundle
-----
objectClass = [org.osgi.service.blueprint.container.BlueprintContainer]
osgi.blueprint.container.symbolicname = artemis-pax-jms-factory-pooledjms.xml
osgi.blueprint.container.version = 0.0.0
service.bundleid = 253
service.id = 348
service.scope = singleton

karaf@root()> jms:connectionfactories
JMS Connection Factory
──────────────────────
jms/artemis

karaf@root()> jms:info -u admin -p admin jms/artemis
Property │ Value
─────────┼──────────────────────────
product  │ ActiveMQ
version  │ 2.4.0.amq-711002-redhat-1

上記の一覧に示すように、Blueprint バンドルは、汎用的でブローカー固有でない接続プールである javax.jms.ConnectionFactory サービスをエクスポートします。Blueprint XML には明示的な <service ref="artemis"> 宣言がないため、ブローカー固有の javax.jms.XAConnectionFactory は OSGi サービスとして登録されません。

pax-jms-config 1.0.0 バンドルは、サービスプロパティーを使用して、プーリング接続ファクトリー内にブローカー固有の接続ファクトリーを ラッピング する別の方法を追加します。このメソッドは、Fuse 6.x での作業に使用した方法と同じです。

Blueprint XML の例を以下に示します。

<!--
    Broker-specific, non-pooling, non-enlisting javax.jms.XAConnectionFactory
-->
<bean id="artemis" class="org.apache.activemq.artemis.jms.client.ActiveMQXAConnectionFactory">
    <argument value="tcp://localhost:61616" />
    <property name="callTimeout" value="2000" />
    <property name="initialConnectAttempts" value="3" />
</bean>

<!--
    Expose broker-specific connection factory with service properties.
    No need to expose pooling, enlisting, non broker-specific javax.jms.XAConnectionFactory. It will be registered
    automatically by pax-jms-config with the same properties as this <service>, but with a higher service.ranking
-->
<service id="pool" ref="artemis" interface="javax.jms.XAConnectionFactory">
    <service-properties>
        <!-- "pool" key is needed for pax-jms-config to wrap broker-specific connection factory inside connection pool -->
        <entry key="pool" value="pooledjms" />
        <!-- <service>/@id attribute does not propagate, but name of the connection factory is required using one of: -->
        <entry key="osgi.jndi.service.name" value="jms/artemis" />
        <!-- or: -->
        <!--<entry key="name" value="jms/artemis" />-->
        <!-- Other properties, that normally by e.g., pax-jms-pool-pooledjms -->
        <entry key="pool.maxConnections" value="10" />
        <entry key="pool.idleTimeout" value="10000" />
    </service-properties>
</service>

上記の例では、ブローカー固有の接続ファクトリーのみを手動で登録できます。pool=pooledjms サービスプロパティーは、pax-jms-config バンドルによって管理される接続ファクトリートラッカーのヒントです。このサービスプロパティーを持つ接続ファクトリーサービスは、プール接続ファクトリー内でラップされます (この例では pax-jms-pool-pooledjms 。

Fuse/Karaf シェルでは、以下のようになります。

karaf@root()> feature:install jms pax-jms-config pax-jms-artemis pax-jms-pool-pooledjms

karaf@root()> install -s blueprint:file://$PQ_HOME/message-brokers/blueprints/artemis-pax-jms-discovery.xml
Bundle ID: 254

karaf@root()> bundle:services -p 254

Bundle 254 provides:
--------------------
objectClass = [javax.jms.XAConnectionFactory]
osgi.jndi.service.name = jms/artemis
osgi.service.blueprint.compname = artemis
pool = pooledjms
pool.idleTimeout = 10000
pool.maxConnections = 10
service.bundleid = 254
service.id = 349
service.scope = bundle
-----
objectClass = [org.osgi.service.blueprint.container.BlueprintContainer]
osgi.blueprint.container.symbolicname = artemis-pax-jms-discovery.xml
osgi.blueprint.container.version = 0.0.0
service.bundleid = 254
service.id = 351
service.scope = singleton

karaf@root()> service:list javax.jms.XAConnectionFactory
[javax.jms.XAConnectionFactory]
-------------------------------
 osgi.jndi.service.name = jms/artemis
 osgi.service.blueprint.compname = artemis
 pool = pooledjms
 pool.idleTimeout = 10000
 pool.maxConnections = 10
 service.bundleid = 254
 service.id = 349
 service.scope = bundle
Provided by :
 Bundle 254
Used by:
 OPS4J Pax JMS Config (251)

karaf@root()> service:list javax.jms.ConnectionFactory
[javax.jms.ConnectionFactory]
-----------------------------
 osgi.jndi.service.name = jms/artemis
 osgi.service.blueprint.compname = artemis
 pax.jms.managed = true
 pax.jms.service.id.ref = 349
 pool.idleTimeout = 10000
 pool.maxConnections = 10
 service.bundleid = 251
 service.id = 350
 service.ranking = 1000
 service.scope = singleton
Provided by :
 OPS4J Pax JMS Config (251)

karaf@root()> jms:connectionfactories
JMS Connection Factory
──────────────────────
jms/artemis

karaf@root()> jms:info -u admin -p admin jms/artemis
Property │ Value
─────────┼──────────────────────────
product  │ ActiveMQ
version  │ 2.4.0.amq-711002-redhat-1

前述の例では、このコマンドは重複した名前を削除するため、jms:connectionfactories は 1 つのサービスのみを示しています。データソースの混合デプロイメントにおいて、2 つのサービスが jdbc:ds-list によって表されました。

javax.jms.XAConnectionFactory は Blueprint バンドルから登録され、pool = pooledjms プロパティーが宣言されています。

javax.jms.ConnectionFactory は pax-jms-config バンドルから登録されます。また、

図9.1「ルートをマークすることによる境界」 は、ルートに transacted() DSL コマンドを追加することで、トランザクションになるルートの例を示しています。transacted() ノードに続くすべてのルートノードはトランザクションスコープに含まれます。この例では、以下の 2 つのノードが JDBC リソースにアクセスします。

以下の Java DSL の例は、transacted() DSL コマンドでルートをマークしてトランザクションルートを定義する方法を示しています。

import org.apache.camel.builder.RouteBuilder;

class MyRouteBuilder extends RouteBuilder {
    public void configure() {
        from("file:src/data?noop=true")
                .transacted()
                .bean("accountService","credit")
                .bean("accountService","debit");
    }
}

この例では、ファイルエンドポイントは、あるアカウントから別のアカウントへの資金の移動を記述するいくつかの XML 形式のファイルを読み取ります。最初の bean() 呼び出しでは、指定された金額が受取人の口座に加算され、2 回目の bean() 呼び出しでは、支払人の口座からから指定の金額が差し引かれます。どちらの bean() 呼び出しでも、データベースリソースに対する更新が行われます。データベースリソースがトランザクションマネージャーを介してトランザクションにバインドされることを前提とします (例:6章JDBC データソースの使用)。

上記のルートは Blueprint XML で表現することもできます。<transacted /> タグは、以下の XML のようにルートをトランザクションとしてマークします。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ...>

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <route>
            <from uri="file:src/data?noop=true" />
            <transacted />
            <bean ref="accountService" method="credit" />
            <bean ref="accountService" method="debit" />
        </route>
    </camelContext>

</blueprint>

トランザクションを区別するには、トランザクションプロセッサーを特定のトランザクションマネージャーインスタンスに関連付ける必要があります。transacted() を呼び出すたびにトランザクションマネージャーを指定しなくても、トランザクションプロセッサーが適切なデフォルトを自動的に選択します。たとえば、設定にトランザクションマネージャーのインスタンスが 1 つしかない場合、transacted プロセッサーはこのトランザクションマネージャーを暗黙的に選択し、トランザクションを区別するために使用されます。

トランザクションプロセッサーは、TransactedPolicy タイプのトランザクションポリシーで設定することもできます。これは、伝播ポリシーとトランザクションマネージャーがカプセル化します (詳細は 「トランザクション伝播ポリシー」 を参照してください)。デフォルトのトランザクションマネージャーまたはトランザクションポリシーを選択するには、以下のルールが使用されます。

Bean ID を transacted() に引数として指定することで、Bean を明示的に指定するオプションもあります。「Java DSL の PROPAGATION_NEVER ポリシーを使用したルートの例」を参照してください。

トランザクションプロセッサーをルートに挿入すると、トランザクションマネージャーは、エクスチェンジがこのノードを通過するたびに新しいトランザクションを作成します。トランザクションのスコープは以下のように定義されます。

トランザクションプロセッサーの前にあるルートノードはトランザクションには含まれません。ただし、ルートがトランザクションエンドポイントで始まる場合は、ルートのすべてのノードがトランザクションに含まれます。「ルート開始時のトランザクションエンドポイント」を参照してください。

以下のルートを見てみましょう。transacted() DSL コマンドは、データベースリソースにアクセスする最初の bean() 呼び出しの後に誤って発生するため、正しくありません。

// Java
import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {
    ...
    public void configure() {
        from("file:src/data?noop=true")
                .bean("accountService", "credit")
                .transacted()  // <-- WARNING: Transaction started in the wrong place!
                .bean("accountService", "debit");
    }
}

特定のトランザクションが現在のスレッドにのみ関連付けられていることを理解することが重要です。新しいスレッドでの処理は現在のトランザクションに参加しないため、トランザクションルートの途中でスレッドプールを作成しないでください。たとえば、次のルートは問題を引き起こす可能性があります。

// Java
import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {
    ...
    public void configure() {
        from("file:src/data?noop=true")
                .transacted()
                .threads(3)  // WARNING: Subthreads are not in transaction scope!
                .bean("accountService", "credit")
                .bean("accountService", "debit");
    }
}

threads() DSL コマンドはトランザクションルートと互換性がないため、前述のルートなどのルートは、データベースが破損する可能性があります。threads() 呼び出しが transacted() 呼び出しの前であっても、ルートは想定どおりに動作しません。

ルートをフラグメントに分割し、各ルートのフラグメントを現在のトランザクションに参加させる場合は、direct: エンドポイントを使用することができます。たとえば、エクスチェンジを個別のルートフラグメントに送信するには、転送量が大きい (100 を超える) または小さい (100 以下) かに応じて以下のように choice() DSL コマンドとダイレクトエンドポイントを使用できます。

// Java
import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {
    ...
    public void configure() {
        from("file:src/data?noop=true")
                .transacted()
                .bean("accountService", "credit")
                .choice().when(xpath("/transaction/transfer[amount > 100]"))
                .to("direct:txbig")
                .otherwise()
                .to("direct:txsmall");

        from("direct:txbig")
                .bean("accountService", "debit")
                .bean("accountService", "dumpTable")
                .to("file:target/messages/big");

        from("direct:txsmall")
                .bean("accountService", "debit")
                .bean("accountService", "dumpTable")
                .to("file:target/messages/small");
    }
}

direct エンドポイントは同期されているため、direct:txbig で始まるフラグメントと direct:txsmall で始まるフラグメントの両方は、現在のトランザクションに参加します。つまり、フラグメントは最初のルートフラグメントと同じスレッドで実行されるので、同じトランザクションスコープに含まれています。

以下の Apache Camel コンポーネントは、ルートの宛先として表示される場合にリソースエンドポイントとして機能します。たとえば、to() DSL コマンドに表示される場合です。つまり、これらのエンドポイントはデータベースや永続キューなどのトランザクションリソースにアクセスできます。リソースエンドポイントは、現在のトランザクションを開始したトランザクションプロセッサーと同じトランザクションマネージャーに関連付けられている限り、現在のトランザクションに参加できます。

以下の例は、リソースエンドポイントを含むルートを示しています。これにより、送金の注文が 2 つの異なる JMS キューに送信されます。credits キューは、受取人の口座に入金するために注文を処理します。debits キューは、送金人の口座から差し引く注文を処理します。対応するデビッドがある場合にのみ、クレジットがあります。したがって、キューへの追加操作を単一のトランザクションに含める必要があります。トランザクションが成功すると、クレジット注文とデビット注文の両方がキューに入れられます。エラーが発生した場合には、どちらの注文もキューに入れられません。

from("file:src/data?noop=true")
        .transacted()
        .to("jmstx:queue:credits")
        .to("jmstx:queue:debits");

「トランザクションエンドポイントによる境界」 は、ルート (from() コマンド内で) の開始時にトランザクションエンドポイントがあることによってルートがトランザクションになる例を示しています。すべてのルートノードがトランザクションスコープに含まれます。この例では、ルートのすべてのエンドポイントが JMS リソースにアクセスします。

以下の Java DSL の例は、トランザクションエンドポイントでルートを起動してトランザクションルートを定義する方法を示しています。

from("jmstx:queue:giro")
        .to("jmstx:queue:credits")
        .to("jmstx:queue:debits");

上記の例では、トランザクションスコープにエンドポイント jmstx:queue:giro、jmstx:queue:credits および jmstx:queue:debits が含まれます。トランザクションに成功すると、エクスチェンジは giro キューから永続的に削除され、credits キューおよび debits キューにプッシュされます。トランザクションが失敗すると、エクスチェンジは credits および debits キューに配置されず、エクスチェンジは giro キューに戻されます。デフォルトでは、JMS はメッセージの再配信を自動的に試行します。以下のように、JMS コンポーネント Bean jmstx はトランザクションを使用するように明示的に設定する必要があります。

<blueprint ...>
    <bean id="jmstx" class="org.apache.camel.component.jms.JmsComponent">
        <property name="configuration" ref="jmsConfig" />
    </bean>

    <bean id="jmsConfig" class="org.apache.camel.component.jms.JmsConfiguration">
        <property name="connectionFactory" ref="jmsConnectionFactory" />
        <property name="transactionManager" ref="jmsTransactionManager" />
        <property name="transacted" value="true" />
    </bean>
    ...
</blueprint>

前述の例では、トランザクションマネージャーインスタンス jmsTransactionManager は JMS コンポーネントに関連付けられ、transacted プロパティーは true に設定され、InOnly エクスチェンジのトランザクションデマケーションを有効にします。

上記のルートは、以下のように Blueprint XML で表現できます。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <route>
            <from uri="jmstx:queue:giro" />
            <to uri="jmstx:queue:credits" />
            <to uri="jmstx:queue:debits" />
        </route>
    </camelContext>

</blueprint>

トランザクションエンドポイントで始まるルートに transacted() DSL コマンドは必要ありません。ただし、デフォルトのトランザクションポリシーが PROPAGATION_REQUIRED (「トランザクション伝播ポリシー」 を参照) であることを仮定すると、以下の例のように transacted() コマンドを含めることは通常問題ありません。

from("jmstx:queue:giro")
        .transacted()
        .to("jmstx:queue:credits")
        .to("jmstx:queue:debits");

ただし、このルートは、デフォルト以外の伝播ポリシーを持つ単一の TransactedPolicy Bean が Blueprint XML で作成されている場合など、このルートが予期せぬ方法で動作する可能性があります。「デフォルトのトランザクションマネージャーおよびトランザクションポリシー」を参照してください。そのため、通常はトランザクションエンドポイントで始まるルートに transacted() DSL コマンドを含めない方がよいでしょう。

以下の Apache Camel コンポーネントは、ルートの開始点で表示される場合にトランザクションエンドポイントとして機能します。たとえば、from() DSL コマンドに表示される場合です。つまり、これらのエンドポイントはトランザクションクライアントとして動作するよう設定でき、トランザクションリソースにもアクセスできます。

Bean レベルでトランザクションポリシーを宣言するには、以下のように tx:transaction 要素を bean 要素の子として挿入します。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
        xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.1.0">

    <bean id="accountFoo" class="org.jboss.fuse.example.Account">
        <tx:transaction method="*" value="Required" />
        <property name="accountName" value="Foo" />
    </bean>

    <bean id="accountBar" class="org.jboss.fuse.example.Account">
        <tx:transaction method="*" value="Required" />
        <property name="accountName" value="Bar" />
    </bean>

</blueprint>

上記の例では、必要なトランザクションポリシーは accountFoo Bean と accountBar Bean のすべてのメソッドに適用されます。ここで、メソッド属性はすべての Bean メソッドと一致するワイルドカード * を指定します。

トップレベルでトランザクションポリシーを宣言するには、以下のように tx:transaction 要素を blueprint 要素の子として挿入します。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
        xmlns:tx="http://aries.apache.org/xmlns/transactions/v1.1.0">

    <tx:transaction bean="account*" value="Required" />

    <bean id="accountFoo" class="org.jboss.fuse.example.Account">
        <property name="accountName" value="Foo" />
    </bean>

    <bean id="accountBar" class="org.jboss.fuse.example.Account">
        <property name="accountName" value="Bar" />
    </bean>

</blueprint>

上記の例では、Required トランザクションポリシーは、ID がパターン account* に一致するすべての Bean のメソッドに適用されます。

tx:transaction 要素は以下の属性をサポートします。

Apache Camel では、org.apache.camel.spring.spi.SpringTransactionPolicy クラスを使用して Spring トランザクションポリシーを定義できます。これは基本的にネイティブ Spring クラスのラッパーです。SpringTransactionPolicy クラスは以下の 2 つのデータをカプセル化します。

たとえば、以下のように PROPAGATION_MANDATORY 動作で Spring トランザクションポリシー Bean をインスタンス化できます。

<blueprint ...>
  <bean id="PROPAGATION_MANDATORY "class="org.apache.camel.spring.spi.SpringTransactionPolicy">
    <property name="transactionManager" ref="txManager" />
    <property name="propagationBehaviorName" value="PROPAGATION_MANDATORY" />
  </bean>
  ...
</blueprint>

Spring では、以下の伝播動作がサポートされます。これらの値は当初、JavaeEE でサポートされる伝搬動作でモデル化されました。

以下の例は、サポートされるすべての伝播動作に対してトランザクションポリシー Bean を定義する方法を示しています。便宜上、各 Bean ID は、伝播動作値で指定された値と同じですが、実際には、BeanID に任意の値を使用できます。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <bean id="PROPAGATION_MANDATORY " class="org.apache.camel.spring.spi.SpringTransactionPolicy">
        <property name="transactionManager" ref="txManager" />
        <property name="propagationBehaviorName" value="PROPAGATION_MANDATORY" />
    </bean>

    <bean id="PROPAGATION_NESTED" class="org.apache.camel.spring.spi.SpringTransactionPolicy">
        <property name="transactionManager" ref="txManager" />
        <property name="propagationBehaviorName" value="PROPAGATION_NESTED" />
    </bean>

    <bean id="PROPAGATION_NEVER" class="org.apache.camel.spring.spi.SpringTransactionPolicy">
        <property name="transactionManager" ref="txManager" />
        <property name="propagationBehaviorName" value="PROPAGATION_NEVER" />
    </bean>

    <bean id="PROPAGATION_NOT_SUPPORTED" class="org.apache.camel.spring.spi.SpringTransactionPolicy">
        <property name="transactionManager" ref="txManager" />
        <property name="propagationBehaviorName" value="PROPAGATION_NOT_SUPPORTED" />
    </bean>

    <!-- This is the default behavior. -->
    <bean id="PROPAGATION_REQUIRED" class="org.apache.camel.spring.spi.SpringTransactionPolicy">
        <property name="transactionManager" ref="txManager" />
    </bean>

    <bean id="PROPAGATION_REQUIRES_NEW" class="org.apache.camel.spring.spi.SpringTransactionPolicy">
        <property name="transactionManager" ref="txManager" />
        <property name="propagationBehaviorName" value="PROPAGATION_REQUIRES_NEW" />
    </bean>

    <bean id="PROPAGATION_SUPPORTS" class="org.apache.camel.spring.spi.SpringTransactionPolicy">
        <property name="transactionManager" ref="txManager" />
        <property name="propagationBehaviorName" value="PROPAGATION_SUPPORTS" />
    </bean>

</blueprint>

トランザクションポリシーがトランザクションに何らかの影響を与えることを示す簡単な方法は、次のルートに示すように、既存のトランザクションの途中に PROPAGATION_NEVER ポリシーを挿入することです。

from("file:src/data?noop=true")
        .transacted()
        .bean("accountService","credit")
        .transacted("PROPAGATION_NEVER")
        .bean("accountService","debit");

このように使用すると、PROPAGATION_NEVER ポリシーはすべてのトランザクションを必然的に中止し、トランザクションのロールバックにつながります。アプリケーションへの影響を簡単に確認できるはずです。

上記のルートは、以下のように Blueprint XML で定義できます。

<blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">

    <camelContext xmlns="http://camel.apache.org/schema/blueprint">
        <route>
            <from uri="file:src/data?noop=true" />
            <transacted />
            <bean ref="accountService" method="credit" />
            <transacted ref="PROPAGATION_NEVER" />
            <bean ref="accountService" method="debit" />
        </route>
    </camelContext>

</blueprint>

以下の方法のいずれかを使用してトランザクションをロールバックできます。

9.5.1.1. ランタイム例外を使用したロールバックのトリガー

Spring トランザクションをロールバックする最も一般的な方法は、ランタイム (チェックされていない) 例外を出力することです。つまり、例外は java.lang.RuntimeException のインスタンスまたはサブクラスです。java.lang.Error タイプの Java エラーも、トランザクションロールバックをトリガーします。一方、チェックされた例外では、ロールバックはトリガーされません。

次の図は、Java エラーと例外がトランザクションにどのように影響するかをまとめたもので、ロールバックをトリガーするクラスは灰色で網掛けされています。

注記

Spring フレームワークは、どの例外をロールバックするか、トリガーすべきでない XML アノテーションのシステムも提供します。詳細は、Spring Reference Guide の Rolling back を参照してください。

警告

ランタイム例外がトランザクション内で処理される場合、つまり、例外がトランザクションの境界を設定するコードに浸透する前に、トランザクションはロールバックされません。詳細は、「デッドレターキューを定義する方法」 を参照してください。

from("file:src/data?noop=true")
    .transacted()
    .bean("accountService","credit")
    .choice().when(xpath("/transaction/transfer[amount > 100]"))
        .rollback()
    .otherwise()
        .to("direct:txsmall");

from("direct:txsmall")
    .bean("accountService","debit")
    .bean("accountService","dumpTable")
    .to("file:target/messages/small");

from("file:src/data?noop=true")
    .transacted()
    .bean("accountService","credit")
    .choice().when(xpath("/transaction/transfer[amount > 100]"))
        .markRollbackOnly()
    .otherwise()
        .to("direct:txsmall");
...

失敗したトランザクションを追跡するには、onException() 句を定義すると、関連するエクスチェンジオブジェクトをデッドレターキューに迂回できます。ただし、トランザクションのコンテキストで使用する場合は、例外処理とトランザクション処理の間に対話がある可能性があるため、onException() 句を定義する方法に注意する必要があります。次の例は、再出力された例外を抑制する必要があると仮定して、onException() 句を適切に定義する方法を示しています。

// Java
import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {
    ...
    public void configure() {
        onException(IllegalArgumentException.class)
            .maximumRedeliveries(1)
            .handled(true)
            .to("file:target/messages?fileName=deadLetters.xml&fileExist=Append")
            .markRollbackOnly();  // NB: Must come *after* the dead letter endpoint.

        from("file:src/data?noop=true")
            .transacted()
            .bean("accountService","credit")
            .bean("accountService","debit")
            .bean("accountService","dumpTable")
            .to("file:target/messages");
    }
}

上記の例では、onException() は IllegalArgumentException 例外をキャッチするよう設定され、問題のあるエクスチェンジをデッドレターファイル deadLetters.xml に送信します。もちろん、この定義を変更して、アプリケーションで発生するあらゆる種類の例外をキャッチすることができます。例外の再出力動作とトランザクションのロールバック動作は、onException() 句の次の特別な設定によって制御されます。

onException() を使用する代わりに、トランザクションルートで例外を処理する簡単な方法は、ルートに doTry() および doCatch() 句を使用することです。たとえば、以下のコードは、無限ループに陥ることなく、トランザクションルートで IllegalArgumentException をキャッチおよび処理する方法を示しています。

// Java
import org.apache.camel.builder.RouteBuilder;

public class MyRouteBuilder extends RouteBuilder {
    ...
    public void configure() {
        from("file:src/data?noop=true")
            .doTry()
                .to("direct:split")
            .doCatch(IllegalArgumentException.class)
                .to("file:target/messages?fileName=deadLetters.xml&fileExist=Append")
            .end();

        from("direct:split")
            .transacted()
            .bean("accountService","credit")
            .bean("accountService","debit")
            .bean("accountService","dumpTable")
            .to("file:target/messages");
    }
}

この例では、ルートは 2 つのセグメントに分割されます。最初のセグメント (file:src/data エンドポイントから) は受信エクスチェンジを受け取り、doTry() および doCatch() を使用して例外処理を実行します。2 つ目のセグメント (direct:split エンドポイントから) は、すべてのトランザクション処理を実行します。このトランザクションセグメント内で例外が発生すると、最初に transacted() コマンドに伝播され、それにより現在のトランザクションがロールバックされ、最初のルートセグメントの doCatch() 句によってキャッチされます。doCatch() 句は例外を再出力しないため、ファイルエンドポイントは再試行せず、無限ループが回避されます。