カスタム例外ハンドラの使い方

注意: Worklist クライアント アプリケーションは WebLogic Integration リリース 7.0 より非推奨となりました。代替機能に関する詳細については、『WebLogic Integration リリース ノート』を参照してください。

この節では、Order Fulfillment ワークフローで使用されるユーザ定義の例外ハンドラの例を示し、Studio の例外処理機能を中心に説明します。この節ではワークフロー内のすべてのノードを概説した後で、以下の方法について説明します。

• カスタム例外ハンドラとそのアクションを定義する。

• カスタム例外ハンドラを起動する。

• 特定の例外を検出するための条件を評価する。

• 実行時エラーを修正するため、クライアントへ XML メッセージを送信する。

チュートリアルのこの節では、Order Fulfillment ワークフロー、Create OrderBean と Calculate Total Price ビジネス オペレーション、cancelledorder イベント キーが、ワークフロー オブジェクトのインポート : チュートリアル パッケージ ファイルのインポートの説明に従ってインポート済みであることを前提とします。

 

---

Order Fulfillment ワークフローの概要

Order Processing ワークフローから呼び出される Order Fulfillment ワークフローには、受注品の出荷と請求を処理するタスクが含まれています。ワークフロー内の 2 つのタスクは平行して実行する必要があるので、両者は開始ノードに直接結び付けられます。両方のタスクがワークフローの終了前に必ず実行されるようにするため、AND ノードで 2 つのタスクを結合します。

また、ワークフローは、Order Processing Trigger ワークフロー内の元の XML ドキュメントで指定されていた無効な国名の省略形の修正を Worklist ユーザに求めるカスタム例外ハンドラを定義し、呼び出します。

Order Fulfillment ワークフローの詳細を次の図に示します。図中に表示された番号が振られている手順については、図の下の表で説明しています。この表では、実際のプロセスをサンプル ワークフロー内の実際の実装にマップします。

図6-1 Start Order Fulfillment ワークフロー : 詳細表示

 

 

---

例外ハンドラ

すべての WebLogic Integration ワークフローのテンプレート定義には、システム例外ハンドラというデフォルトの例外ハンドラが設定されています。システム例外ハンドラは、アクティブなトランザクションをロールバックのみにマーク付けしたり、例外をクライアントに送出したりすることにより、実行時に発生する例外に応答します。

カスタム例外ハンドラを定義し、ワークフローのアクションを例外発生時に実行させることもできます。カスタム例外ハンドラをコンフィグレーションすると、実行時に発生するすべての例外の検出や、呼び出し EJB に定義済みの特定の例外処理が可能になります。カスタム例外ハンドラを定義するには、アクティブなトランザクションに対して実行されるコミット およびロールバック アクションを指定します （詳細は、例外ハンドラのアクションを参照してください）。

ワークフロー レベルの例外ハンドラは、任意のノード内から呼び出すことができます。例外ハンドラを定義した後で、以下の 2 つのアクションのいずれかを使用して、ノード内から例外ハンドラを起動します。

• ワークフロー例外ハンドラを設定 − システム例外ハンドラを非アクティブ化し、指定のワークフローの有効期間に例外ハンドラを設定します。例外ハンドラ アクションは、例外が実際に送出されたときにのみ起動されます。必要に応じてこの例外アクションを使用して、例外ハンドラをシステム例外ハンドラにリセットできます。

• 例外ハンドラの呼び出し − このアクションは、ワークフローの任意の時点で、例外が実際に発生するかどうかとは無関係に、指定の例外ハンドラで定義されたアクションを開始します。システム例外ハンドラは、コントロールがメイン ワークフローに戻るときにリセットされます。

フォルダ ツリーと、テンプレート定義の [プロパティ] ダイアログ ボックスにある [例外ハンドラ] タブの両方から、例外ハンドラを新規に作成したり既存の例外ハンドラを表示したりできます。

フォルダ ツリーで Order Fulfillment ワークフロー用に定義された例外ハンドラを表示する手順は、次のとおりです。

1. フォルダ ツリーで、[Order Fulfillment] テンプレートを展開し、テンプレート定義を右クリックします。表示されるポップアップメニューから [開く] を選択してワークフローを開きます。

2. フォルダ ツリーで [例外ハンドラ] フォルダを展開します。展開すると次の図のようになります。

   図6-2 Start Order Fulfillment ワークフロー : 例外ハンドラ

   
    

   このワークフローには、Bad Data to OrderBean というユーザ定義例外ハンドラが 1 つ含まれます。

3. Bad Data to OrderBean 例外ハンドラが呼び出される位置を確認します。フォルダ ツリーでそのフォルダを右クリックし、表示されるポップアップメニューから [使用] を選択します。[例外ハンドラの使用場所] ダイアログ ボックスが表示されます。

   図6-3 [例外ハンドラの使用場所] ダイアログ ボックス

   
    

   このウィンドウで示すように、カスタム例外ハンドラは [Generate Invoice] ノードから呼び出されます。次に、このノードについてもっと詳しく検討したうえで、Bad Data to OrderBean 例外ハンドラのプロパティを詳細に見ることにします。

4. [OK] をクリックします。[例外ハンドラの使用場所] ダイアログ ボックスを終了します。

 

---

Generate Invoice タスクの表示

最初に、ビジネス オペレーションや Bad Data to OrderBean カスタム例外ハンドラへの呼び出しを含め、Generate Invoice タスクを構成するアクションを見てみましょう。

Generate Invoice タスクのプロパティを表示する手順は、次のとおりです。

1. [ワークフロー設計] ウィンドウ内で、Generate Invoice タスクをダブルクリックします。[タスクのプロパティ] ダイアログ ボックスを表示します。[アクティブ時] タブには、Accounting ロールにタスクを割り当てるアクションが 1 つ含まれています。

2. [実行時] タブを選択します。

   図6-4 [Generate Invoice タスク プロパティ] ダイアログ ボックス : [実行時] タブ

   
    

[実行時] タブには以下のアクションが表示されます。

• 例外ハンドラを “Bad Data to OrderBean” に設定 − これは、この時点以降ワークフローの有効期間中に、ワークフローが別の例外ハンドラを設定するまで、ユーザ定義の例外ハンドラを設定する例外処理 アクションです。例外ハンドラの定義については、カスタム例外ハンドラの定義 Bad Data to OrderBean 例外ハンドラで詳細に説明しています。

• ビジネス オペレーション “Create OrderBean” を実行 − これは、POBean 上の checkInventory() メソッドを呼び出す前に、Create OrderBean ビジネス オペレーションを実行するで使用した統合アクションと同じものです。このアクションでは、実行時にサーバ上に EJB のインスタンスが作成されます。

• ビジネス オペレーション “Calculate Total Price” を実行 − これは、POBean 上の calculate() メソッドを呼び出す統合アクションです。Calculate Total Price ビジネス オペレーションの表示で詳細に説明しています。

• 例外ハンドラを “(system exception handler)” に設定 − これは、ワークフローの例外ハンドラをリセットして、実行時にすべてのワークフローに有効なデフォルトのシステム例外ハンドラに戻す例外処理アクションです。

• タスク Generate Invoice に完了マークを付ける − これは、Generate Invoice タスクを完了するタスク アクションです。Shipping タスクも完了にマークされたときに、ワークフローは完了ノードに進み、ワークフローは終了します。

 

---

Calculate Total Price ビジネス オペレーションの表示

ビジネス オペレーション Calculate Total Price を実行 アクションをダブルクリックして、プロパティを表示します。

図6-5 [ビジネス オペレーションを実行] ダイアログ ボックス : Calculate Total Price アクション

 

calculate() メソッドは、国または州の売上税を含む合計金額を OrderTotalPrice 変数に返します。

calculate() メソッドに関する詳細は、ビジネス オペレーションのコンフィグレーションを参照してください。

Calculate Total Price ビジネス オペレーションのコンフィグレーションを表示する手順は次のとおりです。

1. [取消し] をクリックして、[ビジネス オペレーションを実行] ダイアログ ボックスを終了します。

2. [取消し] をクリックして、[タスクのプロパティ] ダイアログ ボックスを終了します。

3. [コンフィグレーション｜ビジネス オペレーション] を選択します。[ビジネス オペレーション] ダイアログ ボックスが表示されます。

4. ビジネス オペレーションのリストで、Calculate Total Price ビジネス オペレーションをダブルクリックします。[ビジネス オペレーションを定義] ダイアログ ボックスが表示されます。

   図6-6 [ビジネス オペレーションを定義 ] ダイアログ ボックス : Calculate Total Price アクション

   
    

   [呼び出すメソッド] フィールドで、calculate() メソッドによる例外 BadStateException の送出を確認できます。EJB のクラス ファイルでは、この例外は、無効な州データがメソッドに渡された場合に発生するように定義されています。ソース コードにおいて無効な州データとは、アメリカが州名として採用する有効な 2 文字の略称と整合がとれないテキストのことです。

   この例外の送出に備えて、Bad Data to OrderBean 例外ハンドラがワークフローに設定され、実行時にエラーを修正します。この例外ハンドラを、以下の節で更に詳しく説明します。

   注意: POBean.jar EJB の詳細は、『BEA WebLogic Integration Javadoc』を参照してください。

5. [取消し] をクリックして、[ビジネス オペレーションを定義] ダイアログ ボックスを終了します。

6. [閉じる] をクリックして、[ビジネス オペレーション] ダイアログ ボックスを終了します。

 

---

カスタム例外ハンドラの定義 Bad Data to OrderBean 例外ハンドラ

ワークフロー オブジェクトとプロパティで、Order Processing ワークフローをトリガした Neworder XML ドキュメントに含まれる <shiptostate> 値内の POBean に無効なデータのオカレンスが渡される場合をシミュレートしました。そのワークフローでは、ShipToState 変数を不正な値 KK に設定し、それが [Start Order Fulfillment] タスクノードによって Order Fulfillment ワークフローに渡されていました。

Generate Invoice タスクが実行されると、ビジネス オペレーションを実行 アクションは間違った ShipToState 変数の値を入力に使用して、calculate() メソッドを呼び出そうと試みます。POBean の calculate() メソッドは、無効な州データを受け取った場合に BadStateException を送出するため、サーバはカスタム定義の例外ハンドラ Bad Data to OrderBean を呼び出します。

ここで、Bad Data to OrderBean 例外ハンドラと、その中に定義されているアクションを見てみましょう。

Bad Data to OrderBean 例外ハンドラを表示する手順は次のとおりです。

1. フォルダ ツリーで、[例外ハンドラ] フォルダを展開し、Bad Data to OrderBean 例外ハンドラを右クリックします。表示されるポップアップ メニューから [プロパティ] を選択します。[例外ハンドラのプロパティ] ダイアログ ボックスが表示されます。

   図6-7 [例外ハンドラのプロパティ] ダイアログ ボックス

   
    

例外ハンドラのアクション

[コミット時アクション] と [ロールバック時アクション] タブを使用すると、トランザクションのコミット パスやロールバック パスで実行するワークフロー アクションを指定できます。トランザクションがロールバック専用にマークされている場合を除き、ほとんどの場合はトランザクションがコミットされます。この場合、例外ハンドラはロールバック タブで指定されたアクションを実行します。呼び出された EJB メソッドでトランザクションをロールバックのみにマークすることは可能ですが、両方のタイプのアクションを指定することをお勧めします。

• コミット時アクション − このタブで、例外ハンドラを終了 アクションを含め、以下のオプションを付けた任意のワークフロー アクションを指定する。

  • 終了してロールバック

  • 終了して停止 (残っている処理を実行しない)

  • 終了して再試行(失敗した処理を再試行する)

  • 終了して続行 (次の処理で再開する)

• ロールバック時アクション − 使用可能なアクションは、ワークフロー変数を設定、統合 アクション、例外ハンドラおよびロールバックを終了、電子メール送信、処理なし、条件を評価、監査エントリを作成 です。

[例外ハンドラのプロパティ] ダイアログ ボックスにあるように、Bad Data to OrderBean 例外ハンドラは以下のアクションを定義しています。

• コミット

  • 条件を評価 −例外処理アクションの適用対象となる特定の条件をテストしたり、テスト結果に基づいて true または false アクションを指定したりするその他のアクションです。このアクションについては、条件を評価 アクションの表示で詳細を説明します。

  • 例外ハンドラを終了して続行 − 例外ハンドラを停止し、次の操作でワークフローの実行を継続しようとする例外処理アクションです（この場合、例外の原因となったビジネス オペレーションのあとに続くアクション）。

• ロールバック

  例外ハンドラを終了してロールバック−例外ハンドラを停止して、アクティブなトランザクションを例外が送出される前の状態にロールバックし、例外をクライアントに再送出する例外処理アクションです。

 

---

条件を評価 アクションの表示

条件を評価 アクションを表示するには、[例外ハンドラのプロパティ] ダイアログ ボックスで、条件を評価 アクションをダブルクリックします。[条件を評価] ダイアログ ボックスが表示されます。

図6-8 [条件を評価] ダイアログ ボックス

 

条件は次の式で定義されます。

WorkflowAttribute("ExceptionType") = "com.bea.wlpi.tour.po.BadStateException"

この場合、この式はワークフロー属性 例外タイプ を使用して、送出された例外が POBean で指定された BadStateException と等しいかどうかをテストします。このような条件を使用することは、特定の例外を検出するように例外ハンドラを設定する場合の一般的な方法です。WorkflowAttribute 関数を使用して、以下に挙げるさまざまな例外の属性によって目的の例外を識別することができます。

• "ExceptionType"(String) − 例外の完全修飾 Java クラス名

• "Exception Text"(String) − 例外メッセージのテキスト

• "ExceptionObject"(Exception) − 例外オブジェクト自体

ワークフローの関数と属性の全リストについては、『WebLogic Integration Studio ユーザーズ ガイド』の「ワークフローの式を使用する」を参照してください。

条件を評価 アクションは、テスト結果、つまり、式による true または false の評価に従って実行するアクションを指定します。この例では、このアクションは以下のようなアクションを指定します。

• True

  XML をクライアントに送信 − calculate() メソッドに渡された無効なデータの修正を Worklist ユーザに求める XML メッセージを Worklist ユーザに送信し、Generate Invoice タスクを再実行する統合アクションです。このアクションについては、XML をクライアントに送信 アクションの表示で詳しく説明します。

• False

  ここではアクションの指定はありません。条件によって false となった場合、例外ハンドラが、[例外ハンドラのプロパティ] ダイアログ ボックスで指定された ロールバック アクションを実行します。

 

---

XML をクライアントに送信 アクションの表示

XML をクライアントに送信 アクションは、POBean に渡され、BadStateException の発生原因となった誤った不正なデータの修正を求めるメッセージを Worklist ユーザに送信します。次に、[Generate Invoice タスク プロパティ] ダイアログ ボックスの [実行時] タブで指定されたアクションを再実行し、タスクが正常に終了するようにします。

XML をクライアントに送信 アクションを表示するには、[条件を評価] ダイアログ ボックスで、[True] タブを選択し、続いて XML をクライアントに送信 アクションをダブルクリックします。[XML をクライアントに送信] ダイアログ ボックスが表示されます。

図6-9 [Bad Data to OrderBean] 例外ハンドラ : [XML をクライアントに送信] ダイアログ ボックス

 

この XML をクライアントに送信 アクションでは、ClientSetVarsReq DTD に基づき、XML ドキュメントが Worklist クライアントに送信され、Worklist ユーザが情報を入力するためのフィールドを含むメッセージ ボックスが Worklist によって表示されます。XML ドキュメントは、次のような構造になっています。

コード リスト 6-1 ClientSetVarsReq XML ドキュメントの構造

<set-variables title="text">
text
   <actionid>provided by default	</actionid>
   <variable name="variable name" prompt="text" />
   [<variable name="variable name" prompt="text" />]
</set-variables>

Worklist クライアントによって表示されるメッセージ ボックスに対応する XML ドキュメント内のタグと値を、次の図に示します。

図6-10 [Error Warning] メッセージ ボックス

 

Worklist ユーザからの応答を取り込むために、データは ClientSetVarsResp.dtd に基づいて Worklist クライアントが返した XML ドキュメント、特にリスト6-2 に示す<variable name>属性から抽出されます。

コード リスト 6-2 ClientMsgBoxReq XML ドキュメントの構造

<set-variables>
   <variable name="variable name" /> 
   [<variable name="variable name" />] 
</set-variables>

必要な情報を抽出するために、次の XPath 式が定義されます。

XPath("/set-variables/variable[@name=¥"ShipToState¥"]/text()")

次に、[XML をクライアントに送信] ダイアログ ボックスの [コールバック変数] タブで、結果が ShipToState 変数に割り当てられます。

最後にコールバック アクションが指定されます。

このアクションは、Worklist ユーザが有効なデータを入力した後で、[Generate Invoice タスク プロパティ] ダイアログ ボックスの [実行時] タブにリストされるすべてのアクションを再実行します（Generate Invoice タスクの表示を参照）。ユーザが無効なデータを入力した場合は、許容できるデータが入力されるまで、メッセージ ボックスが繰り返し表示され、正しく入力するよう求められます。

Generate Invoice タスクの最後のアクションによってタスクの完了がマークされると、ワークフローは AND ノードに進みます。Ship Order タスクが完了とマークされると、ワークフローは終了します。この時点で、ワークフローの実行中に収集された変数値が、Order Processing ワークフローに返されます。