16 タスク・フローのパラメータの使用

この章では、ビュー・アクティビティおよびADFバインド・タスク・フローでパラメータを指定する方法について説明します。

この章の内容は次のとおりです。

• 16.1項「タスク・フローのパラメータの概要」

• 16.2項「ビュー・アクティビティへのパラメータ渡し」

• 16.3項「ADFバインド・タスク・フローへパラメータを渡す方法」

• 16.4項「データ・コントロール・インスタンスの共有」

• 16.5項「戻り値の指定」

• 16.6項「ELバインディング式の指定」

16.1 タスク・フローのパラメータの概要

ビュー・アクティビティ入力ページ・パラメータは別名として使用できます。別名を使用すると、バインド・タスク・フロー入力パラメータをページ・パラメータにマップできるようになります。ビュー・アクティビティ入力ページ・パラメータは、コール元のタスク・フローで使用可能なマネージドBeanおよび情報をページ自体のマネージドBeanにマップします。ビュー・アクティビティから値を渡すには、値をページ・フロー・スコープまたはマネージドBeanに格納します。タスク・フローでのビュー・アクティビティの使用に関する詳細は、15.2項「ビュー・アクティビティの使用」を参照してください。

たとえば、ページはページ・パラメータとして#{pageFlowScope.empno}を指定し、バインド・タスク・フローは入力パラメータ定義の値として#{pageFlowScope.employeeID}を指定するとします。

ビュー・アクティビティ入力ページ・パラメータのfrom-valueは#{pageFlowScope.employeeID}であり、to-valueは#{pageFlowScope.empno}です。これにより、ページ定義とバインド・タスク・フローのそれぞれが使用されているコンテキストごとにパラメータを再定義する必要がなくなるため、両方とも再利用が可能になります。

タスク・フロー内に含まれている他の値は、バインド・タスク・フローの入力パラメータ定義値のみでなく、入力ページ・パラメータにもマップできます。

16.2 ビュー・アクティビティへのパラメータ渡し

図16-1は、入力ページ・パラメータ・マッピングの指定方法を示しています。pageFlowScope値またはマネージドBeanの値として、Employeeアクティビティにパラメータを渡すことができます。Employeeアクティビティでは、to-valueに指定したEL式に基づいて、pageFlowScope内に配置することによって値を、またはマネージドBeanをTargetアクティビティに渡すことができます。

図16-1 2つのアクティビティのあるタスク・フロー

入力ページ・パラメータ値を設定して取得する手順:

1. エディタで、タスク・フロー・ダイアグラムを開きます。

2. タスク・フロー・ダイアグラムで、ビュー・アクティビティを選択します。

3. プロパティ・インスペクタで、「ページ・パラメータ」をクリックします。

4. 「入力ページ・パラメータ」セクションで、「追加」アイコンをクリックします。

5. 評価時に、渡す入力ページ・パラメータがある場所、たとえば、#{pageFlowScope.EmployeeID}を指定するEL式を使用して、from-valueを入力します。

   図16-1のタスク・フローは、ビュー・アクティビティが取得できる入力パラメータ定義値を設定できます。パラメータ値を取得するために、ADFバインド・タスク・フロー入力パラメータ定義に対して指定された「値」に一致するビュー・アクティビティについてfrom-valueを指定できます。

6. 評価時に、ビュー・アクティビティに関連付けられたページが入力ページ・パラメータの値を取得できる場所、たとえば、#{pageFlowScope.EmployeeNo}を指定するEL式を使用して、to-valueを入力します。

   to-valueは、ビュー・アクティビティ入力ページ・パラメータの2番目の部分です。ビューに関連付けられたページが、ビュー・パラメータの値を取得できる場所を指定します。

16.3 ADFバインド・タスク・フローへパラメータを渡す方法

コール先のADFバインド・タスク・フローは、入力パラメータを受け入れて、終了時にコール元に戻り値を渡すことができます。詳細は、16.5項「戻り値の指定」を参照してください。

注意: データ・コントロールは、タスク・フロー間でパラメータとして明示的に渡すのではなく、単にコール先のバインド・タスク・フローに対してdata-control-scopeオプションを指定して共有できます。詳細は、16.4項「データ・コントロール・インスタンスの共有」を参照してください。

バインド・タスク・フローに入力パラメータを渡すには、次のものを1つ以上指定する必要があります。

• タスク・フロー・コール・アクティビティの入力パラメータ。コール元のタスク・フローがパラメータ値を格納する場所を指定します。

• コール先のバインド・タスク・フローの入力パラメータ定義。コール先のバインド・タスク・フローがパラメータ値を取得できる場所を指定します。

タスク・フロー・コール・アクティビティではなくURLを使用してバインド・タスク・フローをコールする場合は、URL自体にパラメータと値を渡します。詳細は、15.6.4項「URLを使用したバインド・タスク・フローのコール方法」を参照してください。

各オプションに指定された入力パラメータnameは、入力パラメータ値をコール先のバインド・タスク・フローに再度マップして戻すため同一になります。それぞれの「value」は、コール元で値が取得される場所とコール先のタスク・フロー間のマッピングに対応します。

入力パラメータの値を指定しない場合、値はデフォルトで#{pageFlowScope.parmname}に設定されます。parmnameはパラメータ名です。

コール先のバインド・タスク・フローの入力パラメータ定義に対して、入力パラメータが必要かどうかを指定できます。必要な入力パラメータを受け取らない場合は、エラーが発生します(これらのエラーには設計時および実行時にフラグが立てられます)。必要ではないと識別された入力パラメータ定義は、タスク・フロー・コール・アクティビティ作成時は無視できます。

デフォルトでは、すべてのオブジェクトは参照渡しされます。タスク・フロー・コール・アクティビティ入力パラメータは、個々の値ではなく、マネージドBeanオブジェクトが渡される場合にのみ、参照渡しできます。デフォルトでは、プリミティブ・タイプ(int、long、booleanなど)は値渡しされます。

「値渡し」チェック・ボックスは、プリミティブではなくオブジェクトにのみ適用され、参照渡しのデフォルト設定を上書きするために使用されます。ただし、これらの2つを併用すると、パラメータが相互に参照する場合に予期しない動作につながる可能性があります。タスク・フロー・コール・アクティビティの入力パラメータAが値渡しで、タスク・フロー・コール・アクティビティの入力パラメータBが参照渡しの場合、BにAへの参照が含まれていると、AとBで2つの異なるインスタンスが生じる可能性があります。

例16-1は、バインド・タスク・フローに対して指定された入力パラメータ定義を示しています。

例16-1 入力パラメータ定義

<task-flow-definition id="sourceTaskflow">
.
.
.
   <input-parameter-definition>
      <name>inputParameter1</name>
      <value>#{pageFlowScope.parmValue1}</value>
      <class>java.lang.String</class>
   </input-parameter-definition>
.
.
.
</task-flow-definition>

例16-2は、タスク・フロー・コール・アクティビティに対して指定された入力パラメータ・メタデータを示しており、例16-1のバインド・タスク・フローがコールされています。

例16-2 タスク・フロー・コール・アクティビティの入力パラメータ

<task-flow-call id="taskFlowCall1">
.
.
.
    <input-parameter>
      <name>inputParameter1</name>
      <value>#{pageFlowScope.newCustomer}</value>
      <pass-by-value/>
    </input-parameter> 
.
.
.   
</task-flow-call>

ヒント: ページのパラメータを設定するために、ADFタスク・フローを使用できますが、この他にもパラメータ化されたフォームを「データ・コントロール」パネルからドロップしたり、起動アクションによって起動されたパラメータを取るメソッド付きのフォームを使用する方法があります。最初の方法では、パラメータがページに渡されます。その他の方法では、ページのパラメータが使用されます。ページにパラメータが必要な場合は、タスク・フロー・パラメータを使用するかスコープ変数を設定して渡す必要があります。

次の手順は、タスク・フロー・コール・アクティビティを使用してソース・タスク・フローからターゲット・バインド・タスク・フローに入力パラメータを渡す方法を説明しています。ソース・タスク・フローにある任意のアクティビティからパラメータ値を渡すことができますが、この手順で渡されるパラメータには、ソース・タスク・フロー内のページにある入力テキスト・フィールドの値が含まれます。

作業を始める前に、次のようにします。

• コール元およびコール先のタスク・フローを作成します(詳細は、14.2項「タスク・フローの作成」を参照してください)。コール元は、バインド・タスク・フローでもバインドなしタスク・フローでもかまいません。コール先のタスク・フローは、バインド・タスク・フローである必要があります。

• コール元のタスク・フローで、図16-2のようなアクティビティを追加します。コール元のタスク・フロー上のビューに関連付けられたページには、入力テキスト・フィールドとボタンが含まれています。エンド・ユーザーがJSFページのボタンをクリックすると、タスク・フロー・コール・アクティビティに制御が渡されます。

図16-2 コール元のタスク・フロー

ADFバインド・タスク・フローに入力パラメータを渡す手順:

1. JSFページの入力テキスト・コンポーネントを選択します。

2. 「プロパティ・インスペクタ」で、入力テキスト・コンポーネントの「value」を入力します。

   EL式として、たとえば#{pageFlowScope.inputValue}などの値を指定できます。

3. アプリケーション・ナビゲータで、コール先のタスク・フローの名前をダブルクリックしてそのダイアグラムを開きます。

4. コール先のタスク・フローの「概要」タブをクリックします。

5. 「パラメータ」をクリックして、「入力パラメータの定義」ノードを展開します。

6. 「入力パラメータの定義」の隣の「追加」アイコンをクリックします。

7. 「名前」フィールドで、inputParm1などのパラメータ名を入力します。

8. 「値」フィールドで、パラメータ値を格納および参照するEL式、たとえば#{pageFlowScope.inputValue}を入力します。

9. エディタで、コール元のタスク・フローのダイアグラムを開きます。

10. アプリケーション・ナビゲータで、コール元のタスク・フローにあるタスク・フロー・コール・アクティビティの最上部に、コール先のADFバインド・タスク・フローをドラッグ・アンド・ドロップします。

    ダイアグラムでタスク・フロー・コール・アクティビティの最上部にバインド・タスク・フローをドロップすると、バインド・タスク・フローを参照するタスク・フローが自動的に作成されます。図16-3に示すように、タスク・フロー参照にはバインド・タスク・フローのIDとドキュメント名が含まれます。ドキュメント名は、IDを含むXMLソース・ファイルを示します。

    図16-3 「プロパティ・インスペクタ」の「タスク・フロー参照」

    
    

11. タスク・フロー・コール・アクティビティの「プロパティ・インスペクタ」で、「パラメータ」をクリックして、「入力パラメータ」セクションを展開します。

12. 入力パラメータを識別するnameを入力します。

    入力パラメータを定義済のタスク・フロー・コール・アクティビティの上にバインド・タスク・フローをドロップしたため、nameはすでに指定されています。同じ入力パラメータ名を維持する必要があります。

13. パラメータ値(#{pageFlowScope.parm1}など)を入力します。

    タスク・フロー・コール・アクティビティの入力・パラメータの値は、コール元のタスク・フローがパラメータ値を格納する場所を指定します。

    コール先のタスク・フローの入力パラメータ定義の値は、値が渡された後にコール先のバインド・タスク・フローの内で使用するために値が取得される場所を指定します。

14. 実行時、コール先のタスク・フローは入力パラメータを使用できます。コール先のタスク・フローの入力パラメータ定義でvalueとしてpageFlowScopeを指定したため、コール先のADFバインド・タスク・フローのどこでもパラメータ値を使用できます。たとえば、コール先のバインド・タスク・フローのビュー・アクティビティにパラメータ値を渡すことができます。詳細は、15.2.2.2項「アクティビティ間の遷移時の処理」を参照してください。

16.4 データ・コントロール・インスタンスの共有

データ・コントロール・インスタンスはタスク・フロー間で共有できます。データ・コントロールの詳細は、12.2項「ADFデータ・コントロールを使用したアプリケーション・モジュールの公開」を参照してください。コール先のバインド・タスク・フローは、そのコール元のタスク・フローによって所有されるデータ・コントロールの値を参照および変更できます。これにより、コール先のタスク・フローはその親と同じデータ・コントロール・インスタンスを共有できます。どちらのタスク・フローも同じ場所(データ・コントロール・フレーム)を調べて、データ・コントロール・インスタンスを取得します。

Fusion Order Demoアプリケーションでは、たとえばADFページの商品表の行を表示するための値を使用できます。ページのボタンをクリックすると、ADFリージョン内のショッピング・カート・フォームが更新されます。フォームは、表の選択された値に基づいた商品名で更新されます。

データ・コントロール・フレームは、データ・コントロール・インスタンスを含むタスク・フローに関連付けられているコンテナです。バインド・タスク・フローのトランザクションは、データ・コントロール・フレーム内のデータ・コントロール・インスタンスに対して作用します。新しいDataControlFrameは、入力されたタスク・フローごとに作成されます。その結果、各ADFタスク・フローは、使用するデータ・コントロールについて独自の一意のインスタンスを保持します。

データ・コントロール・インスタンスをコール元のタスク・フローとコール先のタスク・フローの間で共有するかどうかを指定するには、コール先のタスク・フローでdata-control-scopeの値をsharedまたはisolatedに設定します。デフォルト値はsharedです。

コール元とコール先の両方のバインド・タスク・フローに対してsharedデータ・コントロール・スコープが指定されている場合は、コール元タスク・フローをコールする側のデータ・コントロール・フレームが使用されます。例16-3の場合は、Bounded Task Flow Aのデータ・コントロール・フレームがBおよびCでも使用されます。コール元とコール先の両方のバインド・タスク・フローでisolatedデータ・コントロール・スコープが指定されている場合は、それぞれで独自のデータ・コントロール・フレームが使用されます。

例16-3

Bounded Task Flow A - isolated
  Bounded Task Flow B - shared
    Bounded Task Flow C - shared

注意: URLを使用してコールされるdata-control-scopeがsharedに設定されたADFバインド・タスク・フローは、コール元のタスク・フローとはデータ・コントロール・インスタンスを共有できません。コール先のバインド・タスク・フローでdata-control-scopeとしてsharedが指定されている場合、ADF Controllerは例外をスローします。

バインド・タスク・フローのコール元では、任意の深さでそのコール元のデータ・コントロール・インスタンスを共有できます。たとえば、タスク・フローAは、コール先のバインド・タスク・フローBとデータ・コントロール・インスタンスを共有できます。コール先のバインド・タスク・フローCは、同じデータ・コントロール・インスタンスを共有できます。

ADFリージョン内で使用される共有データ・コントロール・スコープを指定するADFバインド・タスク・フローは、親ビュー・ポートにあるタスク・フローのデータ・コントロール・インスタンスを共有します。詳細は、17.1.3.2項「ビュー・ポートおよびADFリージョン」を参照してください。

新しいデータ・コントロール・フレームが、各RootViewPortのコール・スタックのADFバインドなしタスク・フロー用に作成されます。各ブラウザ・ウィンドウは、同じHTTPセッション内では残りのブラウザ・ウィンドウから分離されます。ブラウザ・ウィンドウはデータ・コントロール・インスタンスを共有しません。ただし、エンド・ユーザーが[Ctrl]キーを押しながら[N]キーを押して新規のブラウザ・ウィンドウを開く場合、2つのウィンドウはサーバー側の状態が同じであり、データ・コントロール・インスタンスを共有します。

パフォーマンス上の理由から、データ・コントロールは必要になるまでインスタンス化されません。

作業を始める前に、次のようにします。

• コール元およびコール先のタスク・フローを作成します。

タスク・フロー間でデータ・コントロールを共有する手順:

1. コール先のタスク・フローのプロパティ・インスペクタで、「動作」を選択します。

2. data-control-scopeリストで、sharedを選択します。

   コール先のタスク・フローは、そのコール元とすべてのデータ・コントロール・インスタンスを共有します。

   
   

   注意: data-control-scopeを設定すると、バインド・タスク・フローのtransactionオプションを調べてそのオプション間で対話があるかどうかも確認が必要な場合があります。詳細は、16.4.1項「トランザクションの管理について」を参照してください。

   
   

   上にあるすべてのバインド・タスク・フローに依存させないようにするには、コール元のバインド・タスク・フローでdata-control-scopeをisolatedに設定する必要があります。デフォルトでは、すべてのバインド・タスク・フローのdata-control-scopeがsharedに設定されています。

16.4.1 トランザクションの管理について

データ・コントロール・インスタンスは、同時に複数のトランザクションにわたって共有できません。タスク・フローがトランザクションの管理を行う場合は、data-control-scopeオプションに選択する値が、バインド・タスク・フローのtransactionオプション設定に影響を与えることがあります。表16-1で、これらのオプションの対話について説明します。

表16-1 トランザクションとdata-control-scopeオプション設定の対話

transactionオプション	data-control-scope isolatedオプション	data-control-scope sharedオプション
requires-existing-transaction	無効です。	まだトランザクションを開いていない場合は、例外がスローされます。 既存のトランザクションがコミットされることはありません。
requires-transaction	常に新しいトランザクションを開始します。	まだトランザクションを開いていない場合は、新しいトランザクションを開始します。
new-transaction	常に新しいトランザクションを開始します。	まだトランザクションを開いていない場合は、新しいトランザクションを開始します。すでに開いている場合は、例外がスローされます。
<デフォルト>(なし)	開いているトランザクションなしで新しいデータ・コントロール・フレームが作成されます。	該当なし

16.5 戻り値の指定

図16-4に示すように、タスク・フロー・リターン・アクティビティにより、ADFバインド・タスク・フローはコール元のタスク・フローに戻ります。コール先のバインド・タスク・フローは、コール元のタスク・フローに戻り値を渡すことができます。

図16-4 コール元のタスク・フローに戻るADFバインド・タスク・フロー

図16-5に示すように、コール元のタスク・フローに値が戻されます。

図16-5 バインド・タスクをコールするADFバインドなしタスク・フロー

値を戻すには、次のものを指定する必要があります。

• コール先のバインド・タスク・フローの戻り値定義。コール先のバインド・タスク・フローの終了時に戻り値が取得される場所を指定します。

• コール元のタスク・フローのタスク・フロー・コール・アクティビティの戻り値。コール元のタスク・フローが戻り値を検出できる場所を指定します。

バインド・タスク・フローのコール元は、コール元に戻されるタスク・フロー・コール・アクティビティの戻り値を識別しないことにより、戻り値定義の値を無視することもできます。

タスク・フロー・コール・アクティビティの戻り値は、参照渡しで戻されます。ADFバインド・タスク・フロー内部で参照しているものがないため、値渡しおよびコピー作成の必要がありません。

次の手順を開始する前に、次のようにします。

• コール元のタスク・フロー(バインドもバインドなしも可)およびターゲットのバインド・タスク・フローを作成します。

コール先のADFバインド・タスク・フローの戻り値を指定する手順:

1. 概要エディタで、コール先となるADFバインド・タスク・フローを開きます。

2. 「パラメータ」をクリックして、「戻り値の定義」セクションを展開します。

3. 「戻り値の定義」の隣の「追加」アイコンをクリックします。

4. 「名前」フィールドで、Return1などの戻り値を識別する名前を入力します。

5. 「値」フィールドで、#{pageFlowScope.ReturnValueDefinition}など、コール先のバインド・タスク・フローの終了時に戻り値が取得される場所を指定するEL式を入力します。

6. タスク・フロー概要エディタで、コール元のADFタスク・フローを開きます。

7. コンポーネント・パレットで、ADFタスク・フロー・リストからコール元のADFタスク・フローのダイアグラムにタスク・フロー・コール・アクティビティをドラッグ・アンド・ドロップします。

8. タスク・フロー・ダイアグラムで、タスク・フロー・コール・アクティビティを選択します。

9. 「プロパティ・インスペクタ」で、「パラメータ」をクリックし、「戻り値」セクションを展開します。

10. nameフィールドで、Return1などの戻り値を識別する名前を入力します。

    戻り値の名前は、コール先のバインド・タスク・フローの戻り値定義の名前と一致する必要があります。

    
    

    ヒント: タスク・フロー・コール・アクティビティの上にコールする予定のバインド・タスク・フローをドロップする場合、nameフィールドはすでに指定されています。したがって、戻り値の「名前」フィールドは、コール先のバインド・タスク・フローの戻り値定義のnameと自動的に一致します。

    
    

11. 「value」フィールドで、コール元のタスク・フローが戻り値を検出できる場所を指定するEL式、たとえば#{pageFlowScope.ReturnValue}を入力します。

16.6 ELバインディング式の指定

タスク・フロー・コール・アクティビティを使用して、ADFリージョンまたはADF動的リージョンとしてバインド・タスク・フローが実装された場合、標準のEL式構文を使用してパラメータ値を指定できます。たとえば、#{bindings.bindingId.inputValue}または#{bindings.bindingId}、単純に#{inputValue}構文を使用してパラメータを指定できます。

例16-4に、ADFリージョンのタスク・フロー・バインディングの例を示します。

例16-4 ADFリージョンのtaskFlowバインディング

<taskFlow id="Department1" taskFlowId="/WEB-INF/Department.xml#Department"
              xmlns="http://xmlns.oracle.com/adf/Controller/binding"
              Refresh="ifNeeded">
    <parameters>
        <parameter id="DepartmentId" value="#{bindings.DepartmentId.inputValue}"
                   xmlns="http://xmlns.oracle.com/adfm/uimodel"/>
     </parameters>
</taskFlow>

パラメータ値バインディングEL式にinputValueを付加すると、パラメータには、実際のバインディング・オブジェクトではなくバインディングの値が割り当てられるようになります。

inputValue #{bindings.bindingId}を付加せずに例16-4の構文を使用すると、(バインディングの値ではなく)バインディング・オブジェクトが渡されます。したがって、バインディングは誤ったコンテキスト(そのページのコンテキストではなく、タスク・フロー・コール、ADFリージョンまたはADF動的リージョンのコンテキスト)内で評価されることになり、最終的には、フレーム内に誤ったデータ・コントロール・コンテキストを設定して複数のデータ・コントロール・インスタンスが作成されます。