第21章 XTS API

本章では XTS API について説明します。XTS API を使用することで、トランザクショナルな Web Services を消費し、バックエンドシステムをコーディネートするクライアントやサーバーアプリケーションを記述することができます。

21.1. アトミックトランザクションプロトコルの API

21.1.1. 投票

2 相コミットプロトコルの間、パーティシパントは制御する作業を確認する準備ができるかどうか投票するよう指示されます。パーティシパントは com.arjuna.wst11.Vote のサブクラス に記載されている com.arjuna.wst11.Vote のサブタイプのひとつのインスタンスを返す必要があります。

com.arjuna.wst11.Vote のサブクラス

Prepared
コーディネータが要求するとパーティシパントが準備できることを示します。パーティシパントはトランザクションの最終結果を知らないため何もコミットされません。
Aborted
パーティシパントは準備できず、ロールバックしました。パーティシパントは 2 つ目のフェーズメッセージの取得を期待すべきではありません。
ReadOnly
パーティシパントは状態に変更を加えておらず、トランザクションの最終結果を知る必要もありません。本質的にはパーティシパントはトランザクションから辞退しています。

例21.1 2PC パーティシパントの prepare メソッドのサンプル実装

public Vote prepare () throws WrongStateException, SystemException
{
  // Some participant logic here

  if(/* some condition based on the outcome of the business logic */)
  {
    // Vote to confirm
    return new com.arjuna.wst.Prepared();
  }
  else if(/*another condition based on the outcome of the business logic*/)
  {
    // Resign
    return new com.arjuna.wst.ReadOnly();
  }
  else
  {
    // Vote to cancel
    return new com.arjuna.wst.Aborted();
  }
}

21.1.2. TXContext

com.arjuna.mw.wst11.TxContext はトランザクションコンテキストのあいまいな表現です。TxContext の戻り値 で記載されているとおり 2 つの可能な値のうちひとつを返します。

TxContext の戻り値

valid
コンテンツが有効かどうか示します。
equals
等値に対して 2 つのインスタンスを比較するために使用できます。

注記

1.0 プロトコル実装で使用される該当のパーティシパントインターフェースは com.arjuna.wst パッケージにあります。

21.1.3. UserTransaction

com.arjuna.mw.wst11.UserTransaction は、クライアントが通常使用するクラスです。クライアントが新しいアトミックトランザクションを開始するためには、まず UserTransactionFactory から UserTransaction を取得する必要があります。このクラスはユーザーを XTS 実装の基礎となるプロトコル固有のアスペクトから分離します。UserTransaction は特定のトランザクションを表していません。代わりに、JTA 仕様の UserTransaction に似た、スレッドごとの暗黙的なトランザクションコンテキストへのアクセスを提供しています。すべての UserTransaction メソッドは暗黙的に現在のスレッドで実行します。

userTransaction メソッド

begin
新しいトランザクションを開始し、それを呼び出しスレッドと関連付けるために使用します。

パラメータ

timeout
このオプションのパラメータはミリ単位で時間間隔を指定し、その後新しく作成されたトランザクションは自動的にコーディネータによりロールバックされます。

例外

WrongStateException
トランザクションはすでにスレッドと関連付けられています。
commit
トランザクションに登録された Volatile2PC および Durable2PC パーティシパントは、まず準備を行い次に変更をコミットするよう要求されます。パーティシパントのいずれかが最初のフェーズで準備に失敗すると、他のすべてのパーティシパントは中断するよう要求されます。

例外

UnknownTransactionException
呼び出しスレッドに関連付けられているトランザクションはありません。
TransactionRolledBackException
タイムアウトまたはパーティシパントがコミットできなかったかどちらかの理由により、トランザクションはロールバックされました。
rollback
トランザクションを終了します。完了時に rollback メソッドは、現在のスレッドからトランザクションの関連付けを解除し、すべてのトランザクションと現在関連付けないままにします。

例外

UnknownTransactionException
呼び出しスレッドに関連付けられているトランザクションはありません。

21.1.4. UserTransactionFactory

getUserTransaction メソッドを呼び出し、UserTransactionFactory から 「UserTransaction」 インスタンスを取得します。

21.1.5. TransactionManager

トランザクショナルな Web サービスと基礎となるトランザクションサービス実装の間のやりとりを定義します。TransactionManager は固有のトランザクションを表していません。代わりに、スレッドごとの暗黙的なトランザクションコンテキストへのアクセスを提供します。

メソッド

currentTransaction
現在のトランザクションに対する TxContext を返します。コンテキストがない場合は null となります。currentTransaction メソッドを使用して、Web サービスが既存のトランザクション内から呼び出されたか決定します。戻り値を使用して、複数のスレッドを有効にし、同じトランザクションのスコープ内で実行することも可能です。currentTransaction メソッドを呼び出すことで、トランザクションから現在のスレッドの関連付けの解除はしません。
suspend
すべてのトランザクションからスレッドの関連付けを解除します。これにより固有のトランザクションに関連付けられていない作業をスレッドが行うことができます。
suspend メソッドは TxContext インスタンスを返します。これはトランザクションのハンドルです。
resume
TxContext を使用して、スレッドのトランザクションとの関連付けまたは再度の関連付けを行います。関連付けまたは再度の関連付けの前に、スレッドは現在関連付けられているすべてのトランザクションからの関連付けを解除されます。TxContext が null の場合、スレッドはトランザクションと関連付けられません。この方法では、結果はまるで suspend メソッドが代わりに使用されたかのような結果と同じになります。

パラメータ

txContext
suspend からの返しとしての TxContext インスタンスで、再開されるトランザクションを指定します。

例外

UnknownTransactionException
TxContext により参照されたトランザクションは、呼び出しスレッドのスコープでは無効です。
enlistForVolitaleTwoPhase
現在のトランザクションで特定のパーティシパントを登録します。これにより Volatile2PC プロトコルに参加することになります。パーティシパントに対し一意識別子を渡すことが必要です。

パラメータ

participant
インターフェース Volatile2PCParticipant の実装です。対応するコーディネータメッセージを受信すると、その prepare、commit、abort メソッドが呼び出されます。
id
パーティシパントの一意識別子です。この文字列値は登録されている各パーティシパントにより異なるはずです。また、所定の識別子は、同じコンテナにデプロイされた他の Web サービスではなく、登録している Web サービスにパーティシパントが属していると決定できるはずです。

例外

UnknownTransactionException
呼び出しスレッドに関連付けられているトランザクションはありません。
WrongStateException
トランザクションはパーティシパントを登録できる状態にはありません。例えば、終了のプロセスにある可能性もあります。
enlistForDurableTwoPhase
現在のトランザクションで特定のパーティシパントを登録します。これにより Durable2PC プロトコルに参加することになります。パーティシパントに対し一意識別子を渡すことが必要です。

例外

UnknownTransactionException
呼び出しスレッドに関連付けられているトランザクションはありません。
WrongStateException
トランザクションはパーティシパントを登録できる状態にはありません。例えば、終了のプロセスにある可能性もあります。

21.1.6. TransactionManagerFactory

getTransactionManager メソッドを使用して、TransactionManagerFactory から 「TransactionManager」 を取得します。