14 問合せコンポーネントの使用方法

この章では、queryおよびquickQuery検索パネル・コンポーネントの使用方法を説明します。

この章では、次の項目について説明します。

• 14.1項「問合せコンポーネントについて」

• 14.2項「問合せデータ・モデルの作成」

• 14.3項「quickQueryコンポーネントの使用方法」

• 14.4項「queryコンポーネントの使用方法」

14.1 問合せコンポーネントについて

queryおよびquickQueryコンポーネントは、データ・セットの検索に使用されます。queryコンポーネントには、一連の包括的な検索基準およびコントロールが用意されており、quickQueryコンポーネントは、単一基準での検索に使用できます。

queryコンポーネントでは、次の機能がサポートされています。

• 複数の検索基準に対する選択および検索

• 基準アイテムの動的な追加および削除

• 単一基準に関連付けられている検索演算子の選択

• すべてに一致またはいずれかに一致論理積の選択

• 基本または拡張モードでの表示

• 保存済検索の作成

• 保存済検索のパーソナライズ

queryコンポーネントの拡張モードを使用すると、デフォルトで、ユーザーは現在表示されている検索に基準アイテムを追加および削除できるようになります。ただし、基本モードで特定の機能を非表示(および拡張モードでのみ表示)にできる独自のQueryModelクラスを実装できます。たとえば、拡張モードでのみ演算子を表示することや、拡張モードでは基本モードより多くの基準を表示することができます。

通常、問合せの結果は表またはツリー表に表示され、queryコンポーネントのresultComponentId属性を使用して識別されます。ただし、その他の出力コンポーネントに結果を表示することもできます。結果を表示するように構成されているコンポーネントは、検索が実行されると自動的にレンダリングされます。

図14-1に、検索条件が3つある拡張モードのqueryコンポーネントを示します。

図14-1 検索条件が3つあるqueryコンポーネント

基準がすでに決定されており、ユーザーがそこから選択できるシード済検索を作成することも、ユーザーが基準を追加してそれらの検索を保存できるようにすることも可能です。たとえば、例14-1に従業員のシード済検索を示します。ユーザーは、検索が実行される基準に値を入力できます。また、オペランド(次より大きい、次と等しい、次より小さい)や、論理積(ANDまたはOR問合せを作成する、すべてに一致またはいずれかに一致)も選択できます。ユーザーは「フィールドの追加」ドロップダウン・リストをクリックして1つ以上の基準を追加し、その検索を保存できます。アプリケーションが永続性を使用するように構成されている場合は、それらの検索基準を選択されたオペランドと論理積とともに保存し、指定された検索名を使用して再アクセスできます(永続性の詳細は、第32章「JSFページでのユーザー・カスタマイズの許可」を参照してください)。

quickQueryコンポーネントは、queryコンポーネントを簡略化したバージョンです。ユーザーは、ドロップダウン・リストから選択して、任意の検索可能属性の検索を実行できます。図14-2に、水平レイアウトのquickQueryコンポーネントを示します。

図14-2 水平レイアウトのquickQueryコンポーネント

queryおよびquickQueryコンポーネントのどちらでも、検索の定義および実行にQueryModelクラスが使用されます。ユーザーが実行できるようにする特定の各検索に、関連するQueryModelクラスを作成します。

ヒント: 独自のQueryModel実装を作成するかわりに、必要な機能を提供するADFビジネス・コンポーネントを使用できます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「ADFによるデータバインドされた検索フォームの作成」を参照してください。

QueryModelクラスは、一連の検索基準を定義するQueryDescriptorオブジェクトを管理します。QueryModelクラスでは、QueryDescriptorオブジェクトの作成、削除および更新が行われます。QueryModelクラスでは、シード済検索およびユーザーがパーソナライズした検索の両方の保存済検索も取得されます。詳細は、ADF FacesのJavadocを参照してください。

一連の検索基準アイテムのそれぞれにQueryDescriptorクラスを作成する必要があります。QueryDescriptorクラスでは、各シード済検索の作成に必要な基準および論理積へのアクセスが行われます。また、エンド・ユーザーのアクションに応じた、基準の動的な追加、削除、または追加と削除も実行されます。QueryDescriptorクラスにも、モードや自動実行などの様々なUIヒントがあります。詳細は、ADF FacesのJavadocを参照してください。1つのQueryModelクラスで、複数のQueryDescriptorオブジェクトを管理できます。

ユーザーが新しい保存済検索を作成すると、その保存済検索用に新しいQueryDescriptorオブジェクトが作成されます。ユーザーは、削除、選択、リセットおよび更新など、保存検索で様々な操作を実行できます。検索が実行または変更されると、適切なQueryModelメソッドがコールされて正しいQueryDescriptorオブジェクトが戻されるのみでなく、リクエスト値の適用フェーズ中にQueryOperationEventイベントがブロードキャストされます。このイベントは、JSFライフサイクルのアプリケーションの起動フェーズ中に、QueryOperationListenerハンドラにより使用されます。QueryOperationEventイベントでは、QueryDescriptorオブジェクトが引数として使用され、リスナーに渡されます。ADF Facesには、デフォルトでそのリスナーが実装されています。リスナーで実行される内容の詳細は、表14-2を参照してください。

たとえば、保存済検索の更新は、QueryModelのupdate()メソッドをコールすることで完了します。QueryOperationEventイベントがキューイングされ、更新操作に関連するモデル情報の変更処理を実行するQueryOperationListenerハンドラによって使用されます。

QueryOperationEventイベントを生成する問合せ操作のアクションは、次のとおりです。

• 検索の保存

• 保存済検索の削除

• 基本モードおよび拡張モードの切替え

• 保存済検索のリセット

• 別の保存済検索の選択

• 保存済検索の更新

• 依存基準がある基準の値の更新

AttributeCriterionクラスのhasDependentCriterionメソッドは、基準に依存関係があるかどうかを確認するためにコールできます。デフォルトでは、このメソッドはfalseを返しますが、基準に依存基準がある場合はtrueを返します。その基準の値が変更されると、QueryOperationEventがJSFライフサイクルのモデル値の更新フェーズ用にキューイングされます。モデルには、モデルのルート基準に入力された値に基づき、依存基準の値を更新するためのリスナーが必要です。

14.1.1 問合せコンポーネントのユースケースと例

問合せコンポーネントは、アプリケーションのニーズに対応するために様々なモードで使用できます。シード済検索で構成し、カスタマイズおよびパーソナライズ機能を提供できます。問合せコンポーネントは、エンタープライズ検索機能の実装に使用できる機能豊富なコンポーネントです。

問合せおよびクイック問合せコンポーネントを使用して、複雑なトランザクション検索フォームを作成できます。問合せコンポーネントはモデルドリブンであり、多くの機能および表示オプションを提供します。クイック問合せコンポーネントはフットプリントが小さく、1つの属性での標準検索を提供します。問合せコンポーネントはフットプリントがより大きくなりますが、複数条件の検索とその他の検索機能を提供します。

14.1.2 問合せコンポーネントの追加機能

問合せコンポーネントを実装する前に、他のADF Faces機能を理解することが役立つ場合があります。また、ページに問合せまたはクイック問合せコンポーネントを追加した後で、検証やアクセシビリティなどの機能を追加することが必要になる場合があります。問合せコンポーネントで使用できる他の機能へのリンクを次に示します。

• すべての問合せコンポーネントには、プロパティ値を設定または取得するために使用できるJavaScriptクライアントAPIがあります。詳細は、ADF Faces JavaScript APIドキュメントを参照してください。

• ヒントとメッセージを表示でき、問合せコンポーネントにオンライン・ヘルプを関連付けることができます。詳細は、第19章「ヒント、メッセージおよびヘルプの表示」を参照してください。

• スキンを使用してコンポーネントの外観を変更できます。詳細は、第28章「スタイルおよびスキンを使用した外観のカスタマイズ」を参照してください。

• 問合せコンポーネントをアクセス可能にできます。詳細は、第30章「アクセス可能なADF Facesページの開発」を参照してください。

• 文字列を値として受け取る属性に値を入力するかわりに、プロパティ・ファイルを使用できます。これらのファイルにより、これらの文字列の翻訳を管理できます。詳細は、第29章「ページの国際化およびローカライズ」を参照してください。

• アプリケーションでFusionテクノロジ・スタックを使用する場合は、ADFビジネス・コンポーネントがどのように構成されているかに基づいて、検索フォームを作成できます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド』の「データバインドされた検索フォームの作成」の章を参照してください。アプリケーションでEnterprise JavaBeansを使用する場合は、同じことを行うことができます。詳細は、『Oracle Fusion Middleware Oracle Application Development Framework Java EE開発者ガイド』のデータバインドされた基本的なページの作成に関する項を参照してください。

14.2 問合せデータ・モデルの作成

queryコンポーネントを使用するには、まずQueryModelクラスを作成する必要があります。

ヒント: quickQueryコンポーネントは、QueryModelクラスを実装せずに使用できます。ただし、マネージドBeanにいくつかのロジックを追加する必要があります。詳細は、14.3.2項「モデルなしでのquickQueryコンポーネントの使用方法」を参照してください。

図14-3に、QueryModelクラスのクラス図を示します。

図14-3QueryModelのクラス図

問合せコンポーネントには、UIXQueryコンポーネントに対するrefresh()メソッドがあります。このメソッドは、モデル定義が変更され、問合せコンポーネントをリフレッシュする必要がある場合(つまり、すべての子が削除されて再作成された場合など)にコールする必要があります。新しい基準をQueryDescriptorに追加したか既存の基準を削除したときに、基礎となるモデルがコンポーネントのサブツリーで予期されるのとは異なる基準オブジェクトのコレクションを返す場合は、このメソッドをコールする必要があります。QueryOperationListener、QueryListenerおよびActionListenerは、すべてこのメソッドをコールする必要があります。問合せコンポーネント自体は、アプリケーションの起動フェーズの最後にフラッシュされます。このメソッドは、レスポンスのレンダリング・フェーズ中に呼び出された場合は実行されません。

実装で完了する必要のある内容をさらにわかりやすくするため、表14-1および表14-2で、図14-4に示されているUIコンポーネントの機能を、対応するインタフェースにマップしています。

図14-4 問合せコンポーネントおよび関連するポップアップ・ダイアログ

表14-1に、queryコンポーネントにレンダリングされたUIアーティファクト、関連するクラス、クラス・プロパティ、およびアーティファクトが使用するメソッドを示します。

表14-1 問合せのUIアーティファクトおよび関連するモデル・クラスの操作とプロパティ

	UIアーティファクト	使用されるクラスのプロパティ/メソッド	コメント
1	「検索」パネル	QueryDescriptorインスタンスは、パネルに表示される項目を作成します。	保存済検索に基づきます。
2	表示アイコン		検索パネルを開閉します。
3	「一致」タイプ・ラジオ・ボタン	ConjunctionCriterionクラスのgetConjunction()メソッドを介して使用できます。	問合せが実行されると、検索フィールド間に使用するデフォルトの論理積が表示されます。デフォルトが設定されていて、それがすべての検索フィールドで同一の場合、選択された状態で表示されます。検索フィールドが、フィールド間に異なる論理積を使用するように構成されている場合、UIで値は選択されません。 たとえば、All連結タイプがすべての検索フィールド間に使用されている場合は、Allが選択された状態で表示されます。AllとAnyが混在している場合は、ラジオ・ボタンは何も選択されずに表示されます。 conjunctionReadOnlyプロパティがtrueに設定されている場合、一致タイプは読取り専用になります。displayMode属性がsimpleに設定されている場合には、レンダリングされません。
4	検索フィールドのグループ	QueryDescriptorオブジェクトの検索フィールドのコレクションはConjunctionCriterionオブジェクトで表され、QueryDescriptorクラスのメソッドgetConjunctionCriterion()により戻されます。getCriterionList()メソッドは、List<Criterion>リストを戻します。	現在の選択された検索に関連付けられた1つ以上の検索フィールドが表示されます。
5	検索フィールド	AttributeCriterionクラスは、検索フィールド・インスタンスに固有の情報を指定します。AttributeCriterionオブジェクトは、ConjunctionCriterionクラスのgetCriterionList()メソッドにより戻されるList<Criterion>リストの項目です(4を参照)。 AttributeDescriptorクラスは、検索フィールドに関連する静的な情報を提供します。これは、AttributeCriterionクラスのメソッドgetAttribute()を介して使用できます。 AttributeDescriptorクラスのgetConverter()メソッドをオーバーライドして、javax.faces.convert.Converterタイプのコンバータ・オブジェクトを返すことができます。定義されている場合、属性値はこのコンバータ・インスタンスを使用して変換されます。デフォルトの戻り値はnullです。 AttributeCriterionクラスのhasDependentCriterionメソッドは、基準に依存関係がある場合にtrueを返します。基準に依存関係がある場合、依存する基準フィールドはこの基準の値が変更されたときにリフレッシュされます。デフォルトでは、このメソッドはfalseを返します。	各検索フィールドには、ラベル、演算子、1つ以上の値コンポーネント(入力テキスト・コンポーネントなど)およびオプションの削除アイコンが含まれます。これらのレンダリングに必要な情報は、(保存済検索の)検索フィールドのインスタンスに固有の情報か、どの保存済検索に含まれているかに関係なく汎用的で不変な情報です。 たとえば、従業員ビジネス・オブジェクトに検索フィールドEmployee NameおよびSalaryが含まれるとします。 ユーザーは、Low Salaried EmployeeおよびHigh Salaried Employeesという名前の2つの異なる検索を構成できます。どちらの検索にも、EmployeeおよびSalary属性に基づいて2つの検索フィールドが含まれます。どちらの保存済検索もEmployeeオブジェクトの同じ属性に基づいていますが、Salary検索フィールドは、Low Salaried Employees検索の場合にはデフォルトの演算子が「次より小さい」で値が「50000.00」になるように構成されており、High Salaried Employees検索の場合にはデフォルトの演算子が「次より大きい」で値が「100000.00」になるように構成されています。UIで保存済検索を選択すると、その検索に適切な演算子と値が表示されます。 ユーザーが選択した検索に関係なく、Salaryの検索フィールドには数値コンポーネントがレンダリングされ、ラベルにはSalaryが表示されている必要があります。
6	「保存済の検索」ドロップダウン	システム検索およびユーザーの保存済検索は、QueryModelクラスのメソッドgetSystemQueries()およびgetUserQueries()を介して使用できます。	使用可能なシステム検索およびユーザーの保存済検索のリストが表示されます。 saveQueryModeプロパティがdefaultに設定されている場合は、「パーソナライズ」オプションも追加されます。このオプションを選択すると、ユーザーが保存済検索をパーソナライズできる「パーソナライズ」ダイアログが開かれます。ユーザーは、既存の保存済検索を複製または更新できます。

表14-2に、様々なUIアーティファクトの動作と、その動作を実行するために起動される関連するメソッドを示します。

表14-2 UIアーティファクトの動作および関連するメソッド

	UIアーティファクト	起動されるクラス・メソッド	生成されるイベント	コメント
7	「削除」アイコン	アプリケーションの起動フェーズ中に、コマンド・コンポーネントに登録されている内部のActionListenerハンドラにより、QueryDescriptorクラスのメソッドremoveCriterion()が自動的にコールされます。	ActionEvent	現在のQueryDescriptorオブジェクトから検索フィールドが削除されます。
8	「検索」ボタン	JSFライフサイクルのリクエスト値の適用フェーズ中にQueryEventイベントがキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。 モデル値の更新フェーズ中に、選択された演算子および検索フィールドに入力された値が、演算子および値コンポーネントに追加されたEL式を使用するモデルに自動的に更新されます(詳細は、14.4.1項「queryコンポーネントの追加方法」を参照してください)。これらの式により、AttributeCriterionクラスでget/setOperator()、get/setOperators()およびgetValues()メソッドがそれぞれ起動されます。 アプリケーションの起動フェーズ中に、queryコンポーネントに登録されているQueryListenerが起動され、検索が実行されます。 このリスナーを実装する必要があります。	QueryEvent	常にフッターにレンダリングされます(displayMode属性がsimpleに設定されている場合、フッターのコンテンツはレンダリングされません)。 選択演算子と選択された「一致」ラジオ、および各検索フィールドに入力された値を使用して問合せが実行されます(選択が行われない場合はデフォルトが使用されます)。
9	「リセット」ボタン	JSFライフサイクルのリクエスト値の適用フェーズ中にQueryOperationEventイベントがQueryOperationEvent. Operation.RESET操作タイプでキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。 アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドreset()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。QueryDescriptorオブジェクトを元の状態にリセットするには、このメソッドをオーバーライドする必要があります。	QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation Listenerハンドラ)。	検索フィールドが、前に保存されていた状態にリセットされます。
10	「保存」ボタン	JSFライフサイクルのリクエスト値の適用フェーズ中にQueryOperationEventイベントがQueryOperationEvent. Operation.SAVE操作タイプでキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。 アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドcreate()がコールされます。create()メソッドへのコール後に、update()メソッドがコールされ、新しい保存済検索に(ダイアログ内でユーザーにより選択された)ヒントが保存されます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。渡される引数に基づいて新しいオブジェクトを作成するには、このメソッドをオーバーライドする必要があります。	QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation Listenerハンドラ)。	ユーザーにより追加された新しい検索フィールドも含め、現在の保存済検索の設定に基づいて新しい保存済検索が作成されます。
11	「フィールドの追加」ドロップダウン・リスト	アプリケーションの起動フェーズ中に、コマンド・コンポーネントに登録されている内部のActionListenerハンドラにより、QueryDescriptorクラスのメソッドaddCriterion()が自動的にコールされます。AttributeDescriptorオブジェクト(名前引数で識別される)に基づいて新しいAttributeCriterionオブジェクトを作成するには、このメソッドをオーバーライドする必要があります。	ActionEvent	既存の保存済検索に、検索フィールドとして属性が追加されます。
12	モード(「基本」または「拡張」)ボタン	JSFライフサイクルのリクエスト値の適用フェーズ中にQueryOperationEventイベントがQueryOperationEvent. Operation.MODE_CHANGE操作タイプでキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。 アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドchangeMode()がコールされます。	QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation Listenerハンドラ)。	モード・ボタンをクリックすると、モードが切り替わります。
13	「削除」ボタン	アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドdelete()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。QueryDescriptorオブジェクトを削除するには、このメソッドをオーバーライドする必要があります。	ActionEvent	現在使用中でなければ、選択された保存済検索が削除されます。
14	「適用」ボタン	JSFライフサイクルのリクエスト値の適用フェーズ中にQueryOperationEventイベントがQueryOperationEvent. Operation.UPDATE操作タイプでキューイングされ、アプリケーションの起動フェーズでブロードキャストされます。 アプリケーションの起動フェーズ中に、QueryModelクラスのメソッドupdate()がコールされます。これは、queryコンポーネントに登録されている内部のQueryOperationListenerハンドラにより自動的に行われます。渡される引数を使用してQueryDescriptorオブジェクトを更新するには、このメソッドをオーバーライドする必要があります。	QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation Listener)。	選択された保存済検索に行われた変更が適用されます。
15	「OK」ボタン	「適用」ボタンと同じです。	QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation Listenerハンドラ)。	選択された保存済検索に行われた変更が適用され、その後ダイアログが終了されます。
16	「取消」ボタン	このアクションにはメソッドが定義されていません。	QueryOperationEvent(次にモデル・メソッドをコールするqueryコンポーネントに登録されている内部のQueryOperation Listenerハンドラ)。	ダイアログ内で行われた編集が取り消されます。

14.2.1 問合せデータ・モデルの作成方法

操作を開始する前に:

問合せデータ・モデルに関する知識が役立つ場合があります。詳細は、14.2項「問合せデータ・モデルの作成」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、14.1.2項「問合せコンポーネントの追加機能」を参照してください。

問合せモデル・クラスを作成する手順:

1. 図14-3に示す各インタフェース・クラスの実装を作成します。QueryModelクラスを1つ実装してから、システムの各シード済検索用の適切な基準(演算子および値)が指定されたQueryDescriptorクラスを実装します。問合せに対する様々なモデル・クラスの実装の例は、ADF Facesのサンプル・アプリケーションのoracle.adfdemo.view.query.richパッケージにあるクラスを参照してください。

   
   

   注意: 問合せに構成(AttributeCriterion/ConjunctionCriterionを含むConjunctionCriterion 1...nなど)が使用されている場合、この関係が抽象インタフェースによって強制されることはありません。実装で、アソシエーションに構成を使用するかどうか、およびそれらのオブジェクトのライフサイクルをどのように管理するかを決定する必要があります。

   
   

2. QueryEventイベント(queryコンポーネントのボタンにより参照される)をリスニングするマネージドBeanに、QueryListenerハンドラ・メソッドを作成します。このリスナーにより、QueryModelの適切なAPIが起動され、問合せが実行されます。例14-1に、検索基準のString表現を構成する基本のQueryListener実装のリスナー・メソッドを示します。このStringは、検索結果として表示されます。

   例14-1 QueryListenerハンドラ・メソッド

     public void processQuery(QueryEvent event)
     {
       DemoQueryDescriptor descriptor = (DemoQueryDescriptor) event.getDescriptor();
       String sqlString = descriptor.getSavedSearchDef().toString();
       setSqlString(sqlString);
     }
   

14.3 quickQueryコンポーネントの使用方法

quickQueryコンポーネントには、検索する属性をユーザーが選択できるドロップダウン・リストが1つ含まれています。使用できる検索可能属性は、モデルの実装またはマネージドBeanから導出されます。ユーザーは、選択した属性またはすべての属性を検索できます。

quickQueryコンポーネントは、queryコンポーネントを使用した、より複雑な検索の開始点として使用できます。たとえば、ユーザーはある属性に対してクイック問合せ検索を実行し、成功した場合により複雑な検索に進むことができます。quickQueryコンポーネントは、ユーザーがquickQueryコンポーネントからqueryコンポーネントに切り替えられるようにするマネージドBeanのメソッドにバインドできるコマンド・コンポーネントをendファセットに配置できるようにすることで、これをサポートします。

quickQueryコンポーネントはドロップダウン・リストに検索可能な基準をレンダリングし、実行時に選択された基準のタイプに応じて、quickQueryコンポーネントは属性タイプに基づいて別の基準フィールドをレンダリングします。たとえば、属性タイプがNumberの場合、inputNumberSpinboxコンポーネントがレンダリングされます。問合せに完全なモデルを実装しているかぎり、これらのコンポーネントを追加する必要はありません。マネージドBeanにロジックが設定されていて、完全なモデルが必要ない場合は、手動でquickQueryコンポーネント・アーティファクトを作成します。詳細は、14.3.2項「モデルなしでのquickQueryコンポーネントの使用方法」を参照してください。

14.3.1 モデルを使用したquickQueryコンポーネントの追加方法

前提作業

formおよびsubformに関する知識が役立つ場合があります。詳細は、14.3項「quickQueryコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、14.1.2項「問合せコンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

QueryModelクラスおよび関連クラスを作成します。詳細は、14.2項「問合せデータ・モデルの作成」を参照してください。

quickQueryコンポーネントを追加する手順:

1. コンポーネント・パレットで、「共通」パネルから「クイック問合せ」をドラッグしてページにドロップします。

2. プロパティ・インスペクタの「共通」セクションを開き、次の属性を設定します。

   • id: コンポーネントの一意のIDを入力します。

   • layout: 図14-2に示すように、基準と値が隣接した状態でコンポーネントを水平に表示するか、図14-5に示すように垂直に表示するかを指定します。

     図14-5 垂直に表示するよう設定されたquickQueryコンポーネント

     
     

   • model: 14.2項「問合せデータ・モデルの作成」で作成した、QueryModelクラスを実装するクラスに評価されるEL式を入力します。

   • value: 14.2項「問合せデータ・モデルの作成」で作成した、QueryDescriptorクラスを実装するクラスに評価されるEL式を入力します。

3. 「動作」セクションを開き、次の属性を設定します。

   • conjunctionReadOnly: ユーザーが「いずれかに一致」または「すべてに一致」ラジオ・ボタンを設定できるようにするかどうかを指定します。falseに設定すると、ユーザーは論理積を設定できます。trueに設定すると、ラジオ・ボタンはレンダリングされません。

   • queryListener: 14.2項「問合せデータ・モデルの作成」で作成したQueryListenerハンドラに評価されるEL式を入力します。

4. ページに表(または検索結果を表示するその他のコンポーネント)をドラッグ・アンド・ドロップします。結果コンポーネントのPartialTriggersをquickQueryコンポーネントのIDに設定します。このコンポーネントの値は、フィルタ処理された結果を含むCollectionModelオブジェクトに解決されます。

5. ユーザーが「拡張」リンクをクリックしてquickQueryコンポーネントを完全なqueryコンポーネントに切り替えられるようにする場合は、quickQueryコンポーネントのEndファセットにコマンド・コンポーネントを追加し、quickQueryコンポーネントを非表示にしてqueryコンポーネントを表示するロジックを実装します。

14.3.2 モデルなしでのquickQueryコンポーネントの使用方法

たとえば、すべての問合せロジックが検索を実行して結果を返すQueryListenerハンドラなどの単純なマネージドBeanに存在する場合は、モデルなしでquickQueryコンポーネントを使用できます。完全なquickQueryコンポーネントの作成に必要なコンポーネントを手動で追加およびバインドする必要があります。

始める前に:

formおよびsubformに関する知識が役立つ場合があります。詳細は、14.3項「quickQueryコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、14.1.2項「問合せコンポーネントの追加機能」を参照してください。

quickQueryコンポーネントを追加する手順:

1. マネージドBeanに、ユーザーが検索できる属性を表示するselectOneChoiceコンポーネントのvalueChangeListenerハンドラを作成します。valueChangeListenerハンドラは、検索する属性の選択を処理します。

2. マネージドBeanに、検索を実行するQueryListenerハンドラを作成します。このハンドルでは、問合せを実行するコンポーネントおよび値の取得に、検索基準値の入力に使用される入力コンポーネントのIDが使用されます。

3. コンポーネント・パレットで、「共通」パネルから「クイック問合せ」をドラッグしてページにドロップします。

4. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

   • id: コンポーネントの一意のIDを入力します。

   • layout: 図14-2に示すように、基準と値が隣接した状態でコンポーネントを水平に表示するか、図14-5に示すように垂直に表示するかを指定します。

5. 「動作」セクションを開いて、QueryListener属性を、手順2で作成したQueryListenerハンドラに解決されるEL式に設定します。

6. コンポーネント・パレットで、「共通コンポーネント」パネルから「選択肢を1つ選択」をドラッグしてquickQueryコンポーネントのcriteriaItemsファセットにドロップします。ダイアログで、ユーザーが検索できる属性のリストに評価されるEL式を入力するか、静的なリストを入力するかを選択します。ダイアログのヘルプを参照するには、[F1]を押すか「ヘルプ」をクリックします。

7. 構造ウィンドウでcriteriaItemsファセットのselectOneChoiceコンポーネントを選択し、次の属性を設定します。

   • simple: コンポーネントのラベルを表示しない場合はtrueに設定します。

   • valueChangeListener: 手順1で作成したリスナーに評価されるEL式を入力します。

   • autoSubmit: trueに設定します。

8. コンポーネント・パレットから、必要に応じて選択リスト項目を追加します。selectOneChoiceおよびselectItemsコンポーネントの使用方法の詳細は、11.6項「選択コンポーネントの使用方法」を参照してください。

9. コンポーネント・パレットで、「共通コンポーネント」パネルからinputTextコンポーネントをquickQueryコンポーネントに直接の子としてドラッグします。次の属性を設定します。

   • simple: ラベルを表示しない場合はtrueに設定します。

   • value: ユーザーが入力する値を含むプロパティに評価されるEL式を入力します。

     
     

     ヒント: inputTextコンポーネントを追加しない場合は、実行時に、無効化されたinputTextコンポーネントおよび無効化された実行アイコンがレンダリングされます。

     
     

10. ユーザーが「拡張」リンクをクリックしてquickQueryコンポーネントを完全なqueryコンポーネントに切り替えられるようにする場合は、quickQueryコンポーネントのEndファセットにコマンド・コンポーネントを追加し、quickQueryコンポーネントを非表示にしてqueryコンポーネントを表示するロジックを実装します。

11. コンポーネント・パレットで、「共通コンポーネント」パネルからtable(または検索結果を表示する他のコンポーネント)をページにドラッグします。結果コンポーネントのPartialTriggersをquickQueryコンポーネントのIDに設定します。このコンポーネントの値は、フィルタ処理された結果を含むCollectionModelオブジェクトに解決されます。

14.3.3 実行時の処理: フレームワークによりquickQueryコンポーネントがレンダリングされて検索が実行される仕組み

quickQueryコンポーネントがQueryDescriptorオブジェクトにバインドされている場合、selectOneChoiceおよびinputTextコンポーネントは、実行時にページがレンダリングされる際に自動的に追加されます。ただし、独自のコンポーネントを追加することもできます。検索可能属性を表示するコンポーネントとinputTextコンポーネントの両方を追加する場合、コンポーネントから名前/値ペアを取得するにはQueryListenerハンドラが必要です。

検索可能属性の表示に独自のコンポーネントのみを使用する場合(およびデフォルトの入力テキスト・コンポーネントを使用する場合)は、フレームワークにより入力テキスト・コンポーネントが表示されます。問合せを実行するには、QueryListenerハンドラが、ドロップダウン・リストから属性名を、QueryDescriptor.getCurrentCriterion()メソッドから値を取得するように設定する必要があります。

検索可能属性値の収集に独自のコンポーネントのみを使用する場合(および属性名の指定にデフォルトのselectOneChoiceコンポーネントを使用する場合)は、フレームワークによりselectOneChoiceコンポーネントが表示されます。QueryListenerハンドラが、QueryDescriptor.getCurrentCriterion()メソッドから属性名を、コンポーネントから値を取得するように設定する必要があります。

QuickQueryコンポーネントのvalue属性をQueryDescriptorオブジェクトにバインドせず、両方のコンポーネントを使用することを選択した場合、「移動」ボタンがクリックされると、フレームワークによりQueryDescriptorオブジェクトのないQueryEventイベントがキューイングされます。その後、指定されたQueryListenerハンドラにより、名前へのアクセスにchangeValueListenerハンドラが使用され、値へのアクセスに入力コンポーネントが使用されて問合せが実行されます。selectOneChoiceコンポーネントから属性名を取得し、inputTextコンポーネントから属性値を取得して問合せを実行するには、QueryListenerハンドラを実装する必要があります。

14.4 queryコンポーネントの使用方法

queryコンポーネントは、フル機能検索に使用されます。基本および拡張モードがあり、ユーザーはボタンをクリックすることで切替えできます。

基本モード問合せの機能は次のとおりです。

• 選択可能な検索条件演算子のドロップダウン・リスト

• ANDまたはOR(すべて一致または一部一致)とともに使用する選択可能なWHERE句

• 保存済(シード済)検索

• パーソナライズされた保存済検索

拡張モードの問合せフォームにも、検索可能属性のリストから選択することで、ユーザーが動的に検索条件を追加できる機能があります。ユーザーは、追加された任意の条件を後から削除できます。

ユーザーは、演算子のドロップダウン・リストから選択して、検索用に問合せを作成できます。入力フィールドは、値リスト(LOV)、数値スピナー、日付チューザ、あるいはその他の入力コンポーネントとして構成されます。

リストの複数項目の選択をサポートするには、モデルでviewCriteriaItemにコントロール・ヒントを表示し、基礎となる属性を、対応する表示オブジェクト内のLOVとして定義する必要があります。ヒントは、複数選択またはin演算子機能を有効または無効にするために使用されます。複数選択が有効になっている場合に、EqualsまたはDoes not equal演算子を選択すると、検索基準フィールドがselectManyChoiceコンポーネントとしてレンダリングされます。ユーザーは、リストから複数の項目を選択できます。

検索基準フィールドのコンポーネントは、基礎となる属性のデータ型、選択されている演算子、および複数選択が有効になっているかどうかによって異なります。たとえば、Contains演算子が選択されているString型の属性の検索フィールドは、表14-3に示されているように、inputTextコンポーネントとしてレンダリングされます。

演算子がEqualsまたはDoes not equalであり、複数選択が有効になっていない場合、コンポーネントは、モデルの「デフォルトのリスト・タイプ」ヒントで指定されているコンポーネントにデフォルトで設定されます。

表14-3 String型の検索基準フィールドのレンダリング済コンポーネント

演算子	コンポーネント	複数選択が有効な場合のコンポーネント
Starts with	af:inputText	af:inputText
Ends with	af:inputText	af:inputText
Equals	デフォルトのリスト・タイプ・ヒント	af:selectManyChoice
Does not equal	デフォルトのリスト・タイプ・ヒント	af:selectManyChoice
Contains	af:inputText	af:inputText
Does not contain	af:inputText	af:inputText
Is blank	なし	なし
Is not blank	なし	なし

基礎となる属性がNumberデータ型の場合にレンダリングされるコンポーネントを、表14-4に示します。

表14-4 Number型の検索基準フィールドのレンダリング済コンポーネント

演算子	コンポーネント	複数選択が有効な場合のコンポーネント
Equals	デフォルトのリスト・タイプ・ヒント	af:selectManyChoice
Does not equal	デフォルトのリスト・タイプ・ヒント	af:selectManyChoice
Less than	af:inputNumberSpinBox	af:inputNumberSpinBox
次より小さいか等しい	af:inputNumberSpinBox	af:inputNumberSpinBox
Greater than	af:inputNumberSpinBox	af:inputNumberSpinBox
次より大きいか等しい	af:inputNumberSpinBox	af:inputNumberSpinBox
Between	af:inputNumberSpinBox	af:inputNumberSpinBox
Not between	af:inputNumberSpinBox	af:inputNumberSpinBox
Is blank	なし	なし
Is not blank	なし	なし

基礎となる属性がDateデータ型の場合にレンダリングされるコンポーネントを表14-5に示します。

表14-5 Date型の検索基準フィールドのレンダリング済コンポーネント

演算子	コンポーネント	複数選択が有効な場合のコンポーネント
Equals	デフォルトのリスト・タイプ・ヒント	af:selectManyChoice
Does not equal	デフォルトのリスト・タイプ・ヒント	af:selectManyChoice
Before	af:inputDate	af:inputDate
After	af:inputDate	af:inputDate
On or before	af:inputDate	af:inputDate
On or after	af:inputDate	af:inputDate
Between	af:inputDate (2)	af:inputDate (2)
Not between	af:inputDate (2)	af:inputDate (2)
Is blank	なし	なし
Is not blank	なし	なし

検索基準の基礎となる属性がLOVとして定義されている場合、オートコンプリート機能を有効にするには、AttributeCriterionクラスのgetModelListメソッドから返されるListOfValuesモデル・インスタンスで、そのisAutoCompleteEnabledメソッドに対してtrueを返す必要があります。LOVの詳細は、第13章「値リスト・コンポーネントの使用方法」を参照してください。

autoSubmitがtrueに設定されている場合、検索基準での値の変更は、すぐにモデルにプッシュされます。queryコンポーネントは、依存基準がある場合のみ、その基準リストを自動的にフラッシュします。基準インスタンスに依存基準がなく、autoSubmitがtrueに設定されている場合、queryコンポーネントは部分的にのみリフレッシュされます。

「すべてに一致」または「いずれかに一致」ラジオ・ボタン・グループで、問合せをさらに変更できます。「すべてに一致」を選択すると、基本的にAND関数になります。問合せでは、選択した条件にすべて一致する行のみが返されます。「いずれかに一致」を選択すると、OR関数になります。問合せでは、基準アイテムのいずれか1つに一致するすべての行が返されます。

すべての検索基準の値(null値を含む)を入力して「すべてに一致」または「いずれかに一致」ラジオ・ボタンを選択した後、ユーザーは「検索」ボタンをクリックして問合せを開始できます。問合せ結果は、出力コンポーネントに表示できます。通常、出力コンポーネントは表またはツリー表ですが、resultComponentId属性に指定することで、af:forms、af:outputTextおよび図形など、その他の表示コンポーネントを結果コンポーネントとして関連付けることができます。

「基本」または「拡張」ボタンが有効化および表示されている場合、ユーザーは2つのモードを切り替えられます。各モードでは、そのモードに定義された検索条件のみが表示されます。検索条件フィールドは、基本のみ、拡張のみ、または両方のモードで表示されるように定義できます。

拡張モードでは、コントロール・パネルにも、検索可能属性のポップアップ・リストを表示する「フィールドの追加」ボタンが含まれます。ユーザーがこれらの属性のいずれかを選択すると、動的に生成された検索条件の入力フィールドおよびドロップダウンの演算子のリストが表示されます。すべての検索条件入力フィールドおよび新しく追加されたフィールドの位置は、モデル実装により決定されます。

この新しく作成された検索条件フィールドでも、隣に削除アイコンが表示されます。ユーザーは、後からこのアイコンをクリックして、追加したフィールドを削除できます。初めから定義されていた検索条件フィールドは、削除アイコンがないため、ユーザーが削除することはできません。図14-6に、「Salary」という名前の動的に追加された検索基準フィールドがある拡張モードのqueryコンポーネントを示します。フィールドの隣にある削除アイコン(X)に注目してください。

図14-6 動的に追加された検索規準のある拡張モードの問合せ

ユーザーは、「保存」ボタンをクリックして、入力された検索条件およびモードを保存することもできます。ポップアップ・ダイアログでは、ユーザーは保存済検索に名前を付け、チェック・ボックスを選択してヒントを指定できます。セッションを超えて保存済検索を使用可能にする場合は、永続データ・ストアが必要です。永続性の詳細は、第32章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

シード済検索は、基本的に、アプリケーション開発者によって作成された保存済検索です。コンポーネントを初期化すると、ユーザーは、そのqueryコンポーネントに関連付けられているシード済検索を選択できるようになります。

ユーザーが作成した保存済検索およびシード済システム検索は、「保存済の検索」ドロップダウン・リストに表示されます。シード済検索とユーザーの保存済検索は、仕切線によって区切られます。

保存済検索およびシード済検索を今後の使用に備えてパーソナライズすることもできます。保存済検索のパーソナライズには、永続データ・ストア機能が必要です。永続性の詳細は、第32章「JSFページでのユーザー・カスタマイズの許可」を参照してください。

前述のデフォルトの表示の他に、コンパクト・モードまたは簡易モードで表示するようにqueryコンポーネントを構成することもできます。コンパクト・モードにはヘッダーや境界がなく、「保存済の検索」ドロップダウン・リストが開くアイコンまたは閉じるアイコンの隣に移動します。図14-7に、コンパクト・モードに設定されている、図14-6と同じqueryコンポーネントを示します。

図14-7 コンパクト・モードのqueryコンポーネント

簡易モードでは、ヘッダーおよびフッターがなく、通常その領域に表示されるボタンもないコンポーネントが表示されます。図14-8に、簡易モードに設定された同じqueryコンポーネントを示します。

図14-8 簡易モードのqueryコンポーネント

queryコンポーネントでは、問合せにコマンド・ボタンなどの追加コンポーネントを追加できるtoolbarおよびfooterファセットがサポートされています。たとえば、quickQueryおよびqueryコンポーネントを切り替えるコマンド・コンポーネントを作成し、それらをtoolbarファセットのツールバーに配置できます。

queryコンポーネントはそのサブコンポーネント(入力フィールド、選択リスト、ボタンなど)のレンダリングを行うため、inlineStyleは問合せとともに使用できません。inlineStyleを使用すると、予期しない表示動作が発生することがあります。

14.4.1 queryコンポーネントの追加方法

始める前に:

formおよびsubformに関する知識が役立つ場合があります。詳細は、14.4項「queryコンポーネントの使用方法」を参照してください。

他のADF Faces機能を使用して追加できる機能について理解することが役立つ場合もあります。詳細は、14.1.2項「問合せコンポーネントの追加機能」を参照してください。

次のタスクを完了する必要があります。

QueryModelクラスおよび関連クラスを作成します。詳細は、14.2項「問合せデータ・モデルの作成」を参照してください。

queryコンポーネントを追加する手順:

1. コンポーネント・パレットで、「共通コンポーネント」パネルから「問合せ」をドラッグしてページにドロップします。

2. プロパティ・インスペクタで、「共通」セクションを開いて次の属性を設定します。

   • id: コンポーネントの一意のIDを設定します。

   • model: 14.2項「問合せデータ・モデルの作成」で作成した、QueryModelクラスに解決されるEL式を入力します。

   • value: 14.2項「問合せデータ・モデルの作成」で作成した、QueryDescriptorクラスに解決されるEL式を入力します。

3. 「外観」セクションを開き、次の属性を設定します。

   • displayMode: コンポーネントをデフォルト・モード、簡易モードまたはコンパクト・モードのいずれで表示するかを指定します。

   • saveQueryMode: 実行時に保存済検索を表示および使用するかどうかを指定します。ユーザーがすべての保存済検索を表示および編集できるようにする場合は、defaultに設定します。ユーザーは保存済検索を表示および選択できるが、更新できないようにする場合は、readOnlyに設定します。保存済検索を表示しない場合は、hiddenに設定します。

   • modeButtonPosition: ユーザーがモードを基本から拡張に切り替えられるボタンをツールバーに表示するか(デフォルト)、footerファセットに表示するかを指定します。

   • modeChangeVisible: 基本または拡張の切替えボタンを非表示にする場合は、falseに設定します。

4. 「動作」セクションを開き、次の設定を行います。

   • conjunctionReadOnly: 検索がすべての基準に一致(問合せではAND関数を使用)するか、いずれかの基準に一致(問合せではOR関数を使用)するかの決定に、ユーザーがラジオ・ボタンを選択できるようにする場合は、falseに設定します。trueに設定すると、ラジオ・ボタンはレンダリングされません。

   • queryListener:: 14.2項「問合せデータ・モデルの作成」で作成した、QueryListenerハンドラに評価されるEL式を入力します。

5. 「その他」セクションを開き、次の設定を行います。

   • CriterionFeatures: matchCaseDisplayedに設定すると、すべての文字列ベース検索基準で大文字と小文字を区別することが要求されます。requiredDisplayedに設定すると、すべての基準が表示されることが要求されます。

6. コンポーネント・パレットで、「共通コンポーネント」パネルからtable(または検索結果を表示する他のコンポーネント)をページにドラッグします。表にIDを設定します。このコンポーネントの値は、フィルタ処理された結果を含むCollectionModelオブジェクトに解決されます。

7. 構造ウィンドウで、queryコンポーネントを選択し、resultComponentIDを表のIDに設定します。