| Oracle® Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド 11g リリース2(11.1.2.3.0) B69399-02 |
|
 前 |
 次 |
| Oracle® Fusion Middleware Oracle Application Development Framework Fusion開発者ガイド 11g リリース2(11.1.2.3.0) B69399-02 |
|
前 |
次 |
この章では、ADF Faces変更永続性フレームワークを使用して、ユーザーが実行時にカスタマイズ可能なJSFページを作成する方法について説明します。
この章の内容は次のとおりです。
特定のADF Facesコンポーネントには、特定のユーザーのために保存できる属性があります。たとえば、panelBoxコンポーネントのdisclosed属性の値を、現在のセッションの間、特定のユーザーのために保存できます。StoreFrontモジュール・アプリケーションのmyOrdersページには、オーダー情報を示す4つのpanelBoxコンポーネントがあります。デフォルトでは、これらは図40-1に示すように開いています。
図40-2のように、1つのボックスを折りたたむとします。
このアプリケーションはユーザー・カスタマイズを許可するように構成されているため、ユーザーのセッション中にユーザーがこのページに戻ると、支払情報ボックスは折りたたまれたままです。これらの変更内容をユーザーのセッションに永続させるには、プロジェクトに対してユーザー・カスタマイズを有効にするだけで済みます。
|
注意: ユーザー・セッションは、ユーザーがアプリケーションにログインすると開始され、ユーザーがアプリケーションを終了すると終了します。アプリケーションの使用中、ユーザーはアプリケーションの境界を越えて(ピア・アプリケーションなどに)移動し、そこでアプリケーションを終了する場合がありますが、ユーザー・セッションはその時点で終了します。 |
表40-1に、ユーザー・カスタマイズを許可するようにアプリケーションを構成した後に、ADF Facesアプリケーションによって永続される属性値の変更を示します。
表40-1 暗黙的に永続する属性値
| コンポーネント | 属性 | 実行時の効果 |
|---|---|---|
|
|
|
ユーザーは、ヘッダーのアイコンを使用してコンテンツを表示または非表示にできます。ユーザーの直近のアクションに基づいて、詳細コンテンツが表示または非表示になります。 |
|
|
|
複数の |
|
|
|
ユーザーはパネルのサイズを変更でき、そのサイズは保持されます。 |
|
|
|
ユーザーはスプリッタのいずれかの面を閉じることができます。閉じられた状態は、ユーザーによる最終の構成として保持されます。 |
|
|
|
パネルのスプリッタの位置が、ユーザーによって最後に移動された位置のままになります。 |
|
|
|
エディタは、ユーザーが最後に選択したモード(WYSIWYGまたはソース)で表示されます。 |
|
|
|
現在の表示でアクティブとみなされる日は、アクティブな日のままになります。 |
|
|
|
現在アクティビティを表示しているビュー(日、週、月またはリスト)が保持されます。 |
|
|
|
ユーザーは |
|
|
|
ユーザーは |
|
|
|
ユーザーが |
|
|
|
ユーザーが |
|
|
|
ADF Faces列は、ユーザーが実行時に並べ替えることができます。 |
|
|
|
ADF Facesの列は、スクロールされないように固定できます。列の |
|
|
|
列のコンテンツを折り返すかどうかを指定します。ユーザーがこの属性値を変更できるようにするコードを作成する必要があります。たとえば、ユーザーが値を |
|
|
|
選択された列は、ユーザーが最後に選択した列に基づきます。 |
|
|
|
ユーザーの直近のアクションに基づいて、列が表示または非表示になります。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。たとえば、ユーザーが値を |
|
|
|
列の幅が、ユーザーが最後に設定したサイズのままになります。 |
|
|
|
ADF Facesの表には、ユーザーが属性値で表の行をフィルタ処理できるコンポーネントを含めることができます。フィルタを使用するよう構成されている表では、ユーザーの直近のアクションに基づいて、フィルタは表示または非表示になります。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。たとえば、ユーザーが値を |
|
|
|
グラフの時間軸上に表示されるデータの時間範囲は、すべてのデータ視覚化グラフ・コンポーネントに指定できます。デフォルトでは、すべてのデータが表示されます。時間範囲は、最後または最初のデータ・ポイントからの相対的時間範囲、または明示的時間範囲にも設定できます。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。たとえば、グラフの時間範囲を選択するためのドロップダウン・リストを作成できます。 |
|
|
|
データ視覚化プロジェクトの凡例、リソース使用率およびスケジュール・ガント・チャート・コンポーネントは、情報パネル内で表示されるかされないかのいずれかです。ユーザーがこの属性値を変更できるように(汎用を表示するための非表示および表示のボタン)コードを記述することが必要になります。 |
|
|
|
データ視覚化階層ビューア・コンポーネントでは、上から下への垂直、ツリー、円、放射など、9つの階層レイアウト・オプションをサポートしています。ユーザーは、マップ・コントロール・パネルでレイアウトを変更でき、最後に選択されたレイアウトが保持されます。 |
|
|
|
このデータ視覚化地理マップ・コンポーネント属性では、マップの初期ズーム・レベルを指定します。ズーム・レベルは、ベース・マップの一部としてマップ・キャッシュ・インスタンスで定義されます。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。 |
|
|
|
このデータ視覚化地理マップ・コンポーネント属性では、startingXおよびstartingYによって定義されるマップの中心位置や、点テーマのすべての点を含む、マップの全座標のsrid(空間参照ID)を指定します。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。 |
|
|
|
このデータ視覚化地理マップ・コンポーネント属性では、マップの中心位置のXおよびY座標を指定します。座標のsridはsrid属性で指定します。srid属性が指定されていない場合、その値はマップの中心位置の経度であると想定されます。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。 |
|
|
|
パネルのスプリッタの位置が、ユーザーによって最後に移動された位置のままになります。 |
|
|
|
プロジェクト、リソース使用率およびスケジュールのガント・チャートのデータ視覚化コンポーネントでは、ガント・チャートの主時間軸および副時間軸の指定にこのファセットを使用します。タイム・スケール( |
|
|
|
データ視覚化の面、棒、コンボ、折れ線、散布およびバブルの各グラフ・コンポーネントでは、この子タグ属性を使用して、タイム・セレクタの開始および終了日付を明示的に指定します。この属性では、値バインディングのみがサポートされています。ユーザーがこの属性値を変更できるようにするコードを記述する必要があります。 |
MDSリポジトリを使用して表40-1にリストした属性の値をセッション間で永続できるように、アプリケーションを構成できます。たとえば、StoreFrontモジュールでMDSリポジトリへの永続化が許可されている場合、図40-2に示すように支払情報ボックスを折りたたむことができ、次回アプリケーションを開いたときに折りたたまれた状態になります。
|
注意: リポジトリへの永続化を有効にするには、事前に『Oracle Fusion Middleware管理者ガイド』に説明されているすべてのMDS構成手順を実行する必要があります。 |
ADF Facesで使用できる自動永続性のほかに、次のタイプの変更に対する独自のカスタム・ユーザー・カスタマイズ機能を作成できます。
属性値の変更
ファセットの追加または削除
子コンポーネントの追加または削除
子コンポーネントの並替え
子コンポーネントの別の親への移動
これらのタイプのカスタム・ユーザー・カスタマイズを作成する場合、永続性を処理するAPIを呼び出すコードを追加する必要があります(たとえば、イベント・ハンドラで)。
アプリケーションで変更永続性フレームワークを使用できるようにするには、まずアプリケーションでユーザー・カスタマイズを許可できるようにする必要があります。このプロセスには、変更内容をセッションまたはMDSリポジトリのどちらに永続させるかの決定が含まれます。
変更内容をセッションに永続させる場合、デフォルトでは、表40-1に示すすべての値がユーザーのセッションに保存されます。ただし、リポジトリに永続させる場合は、これらの属性値のうちどれをリポジトリに永続させるかを明示的に構成する必要があります。これらのすべての属性値を永続させるのではなく、コンポーネントの特定属性値の変更のみが永続されるように、またはコンポーネントの特定インスタンスのみが変更を永続させるように、変更を制限できます。
|
注意:
|
変更内容をMDSリポジトリに永続させるアプリケーションをデプロイする際には、アプリケーションのEARアセンブリにメタデータ・アーカイブ(MAR)プロファイルを作成する必要があります。詳細は、41.3.2項「デプロイメント・プロファイルの作成方法」を参照してください。
ユーザー・カスタマイズを使用し始める前に、他の機能を理解することが役立つ場合があります。次に、関連する他の機能へのリンクを示します。
MDSアーキテクチャとメタデータ・リポジトリ(データベース・ベースおよびファイル・ベース)およびアーカイブ(EAR、MAR)の詳細は、『Oracle Fusion Middleware管理者ガイド』のMDSリポジトリの管理に関する項を参照してください。
MDSフレームワークを使用すると、顧客がカスタマイズしてからデプロイできる、カスタマイズ可能なアプリケーションを作成できます。詳細は、第39章「MDSによるアプリケーションのカスタマイズ」を参照してください。
アプリケーションでユーザー・カスタマイズを許可できるようにするには(一部のADF Facesコンポーネントが提供するデフォルトの変更に対して、またはユーザーが作成するカスタム機能に対して)、変更永続性フレームワークを使用するようにアプリケーションを構成し、変更内容を永続させる場所(セッションまたはMDSリポジトリ)を決定する必要があります。
|
注意: 変更内容をMDSリポジトリに永続させる場合は、変更永続性を使用するようにADF Facesアプリケーションを構成する前に、『Oracle Fusion Middleware管理者ガイド』に説明されているすべてのMDS構成手順を実行する必要があります。 |
アプリケーションで変更永続性フレームワークを使用できるようにするには、web.xmlファイルとadf-config.xmlファイルを編集します。
作業を始める前に、次のようにします。
実行時ユーザー・カスタマイズの機能に関する知識が役立つ場合があります。詳細は、40.2項「Fusion Webアプリケーションの実行時ユーザー・カスタマイズの有効化」を参照してください。
アプリケーションに追加できる追加のカスタマイズ機能を理解することも役立つ場合があります。詳細は、40.1.2項「実行時ユーザー・カスタマイズの追加機能」を参照してください。
Studio開発者ロールを使用してJDeveloperを起動し、実行時ユーザー・カスタマイズを有効化するアプリケーションを開く(または作成する)必要があります。
ユーザー・カスタマイズを有効にする手順:
アプリケーションでWebプロジェクトをダブルクリックします。
「プロジェクト・プロパティ」ダイアログで、「ADFビュー」ノードを選択します。
「ADFビュー」ページで「ユーザー・カスタマイズの有効化」チェックボックスを選択します。変更内容をセッションにのみ永続させる場合は、「セッションの継続時間」ラジオ・ボタンを選択します。変更内容をMDSリポジトリに永続させる場合は、「MDSを使用したセッション間」を選択します。
リポジトリに永続させる場合は、各コンポーネント・タグおよびリポジトリに永続させる関連する属性値を宣言する必要があります(セッションにのみ永続させる場合は、すべての値が永続されます)。
このタスクを実現する手順については、40.3項「ユーザー・カスタマイズの構成」を参照してください。この構成の完了後に、コンポーネント・インスタンスごとに設定をオーバーライドできます。手順については、40.4項「個々のJSFページでのユーザー・カスタマイズの制御」を参照してください。
変更内容をセッションにのみ保存するよう選択すると、JDeveloperによりCHANGE_PERSISTENCEコンテキスト・パラメータがweb.xmlファイルに追加され、値がsessionに設定されます。このコンテキスト・パラメータでは、永続性の処理に使用されるChangeManagerクラスが登録されます。かわりに、変更内容をMDSリポジトリに保存するよう選択すると、例40-1に示すように値はoracle.adf.view.rich.change.FilteredPersistenceChangeManagerに設定されます。
例40-1 変更永続性に使用されるweb.xmlのコンテキスト・パラメータ
<context-param>
<param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
<param-value>
oracle.adf.view.rich.change.FilteredPersistenceChangeManager
</param-value>
</context-param>
|
ヒント:
|
リポジトリへの永続化を選択すると、JDeveloperにより次の処理も行われます。
次のJARがクラス・パスに追加されます(ない場合)。
javatools-nodep.jar
facesconfigmodel.jar
taglib.jar
別のコンテキスト・パラメータをweb.xmlに追加して、MDSJSPProviderHelperクラスを登録し、MDSカスタマイズ・ドキュメントとベースJSPドキュメントのマージを処理します(例40-2を参照)。
ADF Faces Change Managerランタイム11ライブラリをプロジェクトに追加します。
adf-config.xmlディスクリプタ・ファイルで、persistent-change-manager要素をMDSDocumentChangeManagerに設定します。これは、変更内容の永続化に使用するクラスです。例40-3に、MDSリポジトリに永続させるための構成を示します。
JSF JSPページをXMLドキュメントとして作成します。詳細は、40.4項「個々のJSFページでのユーザー・カスタマイズの制御」を参照してください。
また、変更内容をMDSリポジトリに保存し、Faceletをアプリケーションに含めることを選択した場合、JDeveloperによって、faceletCacheコンテキスト・パラメータがweb.xmlファイルに追加されます。このパラメータの値は、例40-4に示すように、oracle.adfinternal.view.faces.facelets.rich.MDSFaceletCacheに設定されます。
例40-4 Faceletキャッシングに使用されるweb.xmlのコンテキスト・パラメータ
<context-param> <param-name>com.sun.faces.faceletCache</param-name> <param-value>oracle.adfinternal.view.faces.facelets.rich.MDSFaceletCache</param-value> </context-param>
Faceletキャッシュはアプリケーションのパフォーマンスを向上し、キャッシュ容量はサーバーのMDSで構成できます。詳細は、『Oracle Fusion Middleware管理者ガイド』を参照してください。
変更内容をMDSリポジトリに永続させる場合、デフォルトでセッションに永続させる属性値のうち(表40-1を参照)、リポジトリにも永続させる属性値を決定する必要があります。または、永続させない変更を構成することもできます。
|
ヒント: 多くの場合、構成はシステム管理者が |
たとえば、列のwidth属性の値はリポジトリに永続させないが、列の他のデフォルト属性の変更はすべて永続させるとします。この場合、永続させる他のデフォルトの列値を明示的に設定し、またwidth属性を永続させないようにアプリケーションを明示的に構成する必要があります。
これらの値は、adf-config.xmlファイルの概要エディタを使用して設定(または設定解除)します。図40-3に、columnコンポーネントの特定の属性値のみを永続させる概要エディタを示します。
設定後、ページ上の特定コンポーネントの永続性をオーバーライドできます。たとえば、1つの表の列に対してのみ、width属性の変更を許可しないとします。アプリケーションの他の表では、その属性の変更を永続させます。この場合、width属性の変更をグローバルに永続させるように列を構成し、その後その1つの表に対して、JSPページで直接グローバル構成をオーバーライドします。詳細は、40.4項「個々のJSFページでのユーザー・カスタマイズの制御」を参照してください。
デフォルトでは、いずれかのタイプの変更永続性(セッションまたはリポジトリへの)を使用するようにアプリケーションを構成する際、表40-1に示すすべての属性の値が、常にユーザーのセッションに永続化されます。変更内容をリポジトリに永続させるように構成した場合は、値をそのリポジトリに永続させる属性を宣言する必要があります。永続させない値がある場合は、それらの値も構成する必要があります。
作業を始める前に、次のようにします。
実行時ユーザー・カスタマイズが永続される方法に関する知識が役立つ場合があります。詳細は、40.3項「ユーザー・カスタマイズの構成」を参照してください。
アプリケーションに追加できる追加のカスタマイズ機能を理解することも役立つ場合があります。詳細は、40.1.2項「実行時ユーザー・カスタマイズの追加機能」を参照してください。
Studio開発者ロールを使用してJDeveloperを起動し、実行時ユーザー・カスタマイズを有効化するアプリケーションを開く(または作成する)必要があります。
属性値のリポジトリへの永続性を宣言する手順:
アプリケーション・ナビゲータで、「アプリケーション・リソース」ペインを開き、「ディスクリプタ」ノードと「ADF META_INF」ノードを開き、adf-config.xmlをダブルクリックします。
概要エディタで「表示」ナビゲーション・タブをクリックします。
「タグ」表で、変更内容をリポジトリに永続させる(または永続させない)コンポーネントを選択します。
コンポーネントが表に表示されない場合は、「追加」アイコンをクリックし、コンポーネントを選択して追加します。
|
注意:
なんらかの理由で永続性が失敗した場合、(たとえば、いずれかのフィルタ・ルールが失敗した場合またはMDSリポジトリ・エラーがある場合)、値はセッション・スコープ内にのみ保存されます。 |
「タグ属性」表に、選択したコンポーネントの、値を永続できるすべての属性が表示されます。値を永続させるすべての属性で、「変更の永続化」を選択します。値を永続させない場合は、選択解除します。
|
注意: カスタム・ユーザー・カスタマイズを実装する場合は(40.5項「カスタム・ユーザー・カスタマイズの実装」を参照)、 |
adf-config.xmlファイルでコンポーネント・タグと永続させる属性値を選択すると、JDeveloperによってコンポーネントのタグ・ライブラリ情報と永続させる属性が入力されます。例40-5に、panelBoxコンポーネントのdisclosed属性の値を永続させるエントリを示します。
アプリケーションでユーザー・カスタマイズを使用できるようにしたら、ページ上の特定コンポーネントのユーザー・カスタマイズを制御できます。
デフォルトでは、このフレームワークはすべてのコンポーネント・インスタンスの変更内容を、adf-config.xmlファイルの構成に基づいて永続させます。persistおよびdontPersist属性を使用して、コンポーネント・インスタンスごとに何を永続させるかおよび何を永続させないかを明示的に設定することで、このデフォルト動作をオーバーライドできます。
|
注意:
なんらかの理由で永続性が失敗した場合、(たとえば、いずれかのフィルタ・ルールが失敗した場合またはMDSリポジトリ・エラーがある場合)、値はセッション・スコープ内にのみ保存されます。 |
persistおよびdontPersist属性をサポートするコンポーネントを次に示します。
panelBox
showDetail
showDetailHeader
showDetailItem
column
tree
treeTable
panelSplitter
calendar
dvt:projectGantt
dvt:resourceUtilizationGantt
dvt:schedulingGantt
dvt:ganttLegend
dvt:hierarchyViewer
dvt:timeAxis
persist属性およびdontPersist属性を使用して、コンポーネントにグローバルに設定されているすべての永続性構成をオーバーライドできます。
|
ヒント: 多くの場合、構成はシステム管理者が |
作業を始める前に、次のようにします。
実行時ユーザー・カスタマイズが個別ページで制限される方法に関する知識が役立つ場合があります。詳細は、40.4項「個々のJSFページでのユーザー・カスタマイズの制御」を参照してください。
アプリケーションに追加できる追加のカスタマイズ機能を理解することも役立つ場合があります。詳細は、40.1.2項「実行時ユーザー・カスタマイズの追加機能」を参照してください。
Studio開発者ロールを使用してJDeveloperを起動し、アプリケーションを開き、ユーザー・カスタマイズの動作を変更するページを開きます。
JSFページでユーザー・カスタマイズを実装する手順:
必要に応じて、コンポーネント(変更内容を永続させるコンポーネントを含む)をページに追加します。
コンポーネントの永続可能なすべての属性を永続させる場合:
プロパティ・インスペクタで、「詳細」セクションを展開します。
「永続」フィールドのドロップダウン・リストをクリックして、「すべて使用可能」を選択します。
属性を永続させない場合は、永続させないフィールドに対して手順2を繰り返します。
コンポーネントの複数の属性を永続できるが、それらすべては永続させない場合:
「永続」フィールドの右にあるドロップダウン・メニューをクリックし、「編集」を選択して「プロパティの編集」ダイアログを開きます。
永続させる属性を「選択可能」から「選択済」に移動します。
属性値を永続させない場合は、永続させないフィールドに対して手順4を繰り返します。
|
注意:
または |
変更内容をセッションに永続させるようアプリケーションを構成している場合、セッション中に行われた変更はすべてデータ構造内のセッション変数に記録されます。これは、ビューIDとコンポーネントのID属性値によって索引付けされます。後続のビューの作成またはビューのリストア・フェーズでページがリクエストされるたびに、すべての変更内容が追加されたときと同じ順序で適用されます。つまり、セッションの間に登録された変更は、同じセッションの後続のリクエストでのみ適用されます。
変更内容をMDSリポジトリに永続させるようにアプリケーションを構成している場合、ビューの背後のJSPドキュメントに対してMDSで保持するDocument Object Modelを変異させることで、セッション中に行われた変更が記録されます。ADFコントローラによって登録されたJSFフェーズ・リスナーが、適切なライフサイクル・フェーズでMDSセッションに対するコミットをトリガーすることで、変更ドキュメントがMDSストアに永続されます。ページがリクエストされるたびに、格納された変更をベース・ドキュメントにマージした後、フラット化されたドキュメントを提供するMDS JSPプロバイダから、OracleのJSPエンジンでJSPドキュメントが検索されます。MDSでは、コンポーネントのID属性の一意の値に対して変更が記録されます。
|
ヒント: ページの部分送信に応えて変更が適用される場合( |
さらに、登録WebLogic ServerでJDeveloperからアプリケーションを実行する場合は、MDSによりメタデータ・カスタマイズを永続させるためのローカル・ファイルベースのリポジトリが作成されます。逆に、アプリケーションがテスト環境または本番環境にデプロイされる場合、カスタマイズは構成済のMDSリポジトリに永続されます。MDSリポジトリの構成の詳細は、『Oracle Fusion Middleware管理者ガイド』を参照してください。アプリケーションのデプロイの詳細は、41.4項「アプリケーションのデプロイ」を参照してください。
変更内容がテンプレートまたはリージョンのコンポーネントに永続される際の処理方法は、変更がセッションに永続されるか、MDSリポジトリに永続されるかによって異なります。セッション永続性では、指定されたセッションのviewIdに対して変更内容が記録およびリストアされます。その結果、リージョンまたはページ・テンプレートに属するコンポーネントで変更が適用される場合、その変更は、リージョンまたはテンプレートを使用するページの範囲でのみ適用可能です。リージョンまたはテンプレートを使用するページすべてには適用されません。たとえば、pageOne.jspxとpageTwo.jspxがあり、両方にregion.jsffで定義されているリージョンが含まれ、これにはshowDetailコンポーネントが含まれるとします。pageOne.jspxがレンダリングされ、showDetailコンポーネントのdisclosed属性が変更されると、暗黙的に属性の変更が記録され、pageOne.jspxにのみ適用されます。ユーザーがpageTwo.jspxに移動すると、属性の変更は適用されません。
変更内容をMDSリポジトリに永続させる場合、JSPページ・パスとカスタマイズ・クラスで設定されたカスタマイズ名/値構成設定の組合せによって識別されたドキュメントのカスタマイズが、MDSにより記録されリストアされます(詳細は、39.2.1.1項「カスタマイズ・クラス」を参照)。この結果、レンダリングされた特定ページについて、MDSによりリージョンまたはテンプレート内のコンポーネントに変更が適用される際、ソース・ページと同じカスタマイズ名および値を持つ、リージョンまたはテンプレートを使用するページすべてに変更を適用できます。
前述の例で、showDetailコンポーネントがmyShowDetailのIDを使用するとします。pageOne.jspxがレンダリングされ、showDetailコンポーネントのdisclosed属性が変更されると、属性の変更はregion.jsffに記録されます(これを使用するページではなく)。この変更は、IDが同じであるかぎり、リージョンを含むページがレンダリングされるときに適用されます。
特定のADF Facesコンポーネントに組み込まれているユーザー・カスタマイズ機能のほかに、独自のカスタム・ユーザー・カスタマイズ機能を作成できます。変更永続性フレームワークは、次のタイプのユーザー・カスタマイズをサポートします。
属性値の変更
ファセットの追加または削除
子コンポーネントの追加または削除
子コンポーネントの並替え
子コンポーネントの別の親への移動
カスタム・ユーザー・カスタマイズを作成するには、ユーザー・カスタマイズのタイプごとにカスタマイズ・クラスを作成し、作成したクラスを使用するようにアプリケーションを構成する必要があります。アプリケーションのカスタマイズ・レイヤーも設定する必要があります。これらの手順の詳細は、39.2項「カスタマイズ可能なアプリケーションの開発」を参照してください。
これらの前提条件を満たしたら、セッションまたはMDSリポジトリへの変更の永続化を処理するADF Facesクラスでメソッドを呼び出すロジックを追加します。変更を処理するには、いずれかのADF Faces専用コンポーネント変更クラスのAPIを使用するコードを作成します。多くの場合、このコードを、永続させるコンポーネントが配置されているページに関連付けられているマネージドBean上のイベント・ハンドラ・メソッドに追加します。コンポーネントのすべてのインスタンスで同じ変更内容を永続させる場合、コンポーネントが表示されるページごとにこのコードを追加する必要があります。
カスタム・コンポーネントを作成する場合は、コードをカスタム・コンポーネント・クラスに直接追加することで、コンポーネントにユーザー・カスタマイズを実装できます。この場合、コードをそのコンポーネント・クラスにのみ追加する必要があります(コンポーネントのインスタンスごとに1回ではなく)。詳細は、40.6項「カスタム・コンポーネントでの暗黙的な変更永続性の作成」を参照してください。
カスタム・ユーザー・カスタマイズを作成するために必要な作業について理解するには、変更永続性とMDSフレームワークについて十分に理解していることが必要です。変更内容をMDSリポジトリに永続させる場合、変更永続性フレームワークがMDSフレームワークと連携して機能します。カスタマイズを保存する場所および方法は、MDSリポジトリ、カスタマイズ・レイヤー、カスタマイズ・クラスの設定によって異なります。MDSフレームワークとリポジトリ、およびその使用方法の詳細は、第39章「MDSによるアプリケーションのカスタマイズ」を参照してください。
変更永続性フレームワークでは、Apache MyFaces Trinidadからの基になる変更マネージャ・クラス(org.apache.myfaces.trinidad.changeパッケージ)といくつかのADF Faces固有のクラス(oracle.adf.view.rich.changeパッケージ)を使用します。登録済のChangeManagerクラスのインスタンスには、RequestContextオブジェクトからアクセスできます。リクエストで変更が作成および追加されときに、これらを収集して永続させます。SessionChangeManagerクラスはセッション内でのみ永続性を処理するChangeManagerの実装で、MDSDocumentChangeManagerクラスはMDSリポジトリのみに永続させる実装です。FilteredPersistenceChangeManagerクラスは、登録済の永続性変更マネージャを使用してフィルタ・ルールをリポジトリに渡す変更を格納するChangeManagerの実装です。FilteredPersistenceChangeManagerが使用されている場合、リポジトリに永続されない変更はセッションに永続されます。
コンポーネントの変更を記述するために、追加のクラスが使用されます。これらのAPIを使用して、ADF Facesフレームワークで提供される暗黙的な値変更以外のコンポーネントへの変更の永続化を処理します(表40-1を参照)。ComponentChangeは、ファセットや子コンポーネントの追加または削除など、JSFコンポーネント階層で行われる固有の変更を実装するための、すべてのクラスのベース・クラスです。これらの変更は、後続のビューの作成時に、変更が追加された順序で自動的に適用されます。ComponentChangeクラスを拡張し、DocumentChangeインタフェースを実装するクラスは、変更内容を直接MDSリポジトリに永続できます。DocumentChangeインタフェースを実装しないクラスは、変更内容をセッションにのみ永続できます。
表40-2に、特定のカスタマイズを処理する専用クラスを示します。「リポジトリ」列に「可」と表示されている場合、そのクラスはDocumentChangeインタフェースを実装し、変更内容をMDSリポジトリに永続できます。
表40-2 変更永続性の処理に使用するクラス
| クラス名 | リポジトリ | 説明 |
|---|---|---|
|
AddComplexChildDocumentChange |
可 可 |
ドキュメント・マークアップを使用して、子コンポーネントまたは複雑な子( |
|
|
可 |
複雑な子( |
|
ComplexAttributeComponent |
不可 可 |
属性の値を変更します。 |
|
ComplexAttributeDocumentChange |
可 可 |
ファセット属性の値を変更します。 |
|
|
可 |
子をあるコンテナから別のコンテナへ移動します。 |
|
|
可 |
子コンポーネントを削除します。 |
|
RemoveComplexChildAttribute RemoveComplexChildAttribute |
可
|
複雑な子( |
|
|
不可 |
ドキュメント・マークアップを使用して子コンポーネントをファセットに追加します。この変更の適用時に、マークアップがドキュメントに追加されます。 |
|
|
可 |
子コンポーネントをファセットに追加します。この変更の適用時に、子コンポーネントに対応するDOM要素がドキュメントに追加されます。ファセットが存在しない場合は作成されます。ファセットが存在する場合は、そのコンテンツがすべて削除され、新たにコンテンツが追加されます。 |
|
|
可 |
ファセットを削除します。 |
|
|
可 |
コンポーネントの子を並べ替えます。 |
ChangeManagerクラスとは別に、DocumentChangeFactoryインタフェースを実装してChangeManagerクラスに登録する必要がある場合があります。DocumentChangeFactoryの実装でComponentChangeに相当するDocumentChangeを提供できる場合、ChangeManagerはこれを使用してDocumentChangeをリポジトリに永続させます。
作成する明示的な変更を処理するコードを追加し、JSFページ上のコンポーネントを構成してカスタマイズを処理する必要があります。また、デフォルトのユーザー・カスタマイズと同様に、カスタムの変更をadf-config.xmlファイルに登録する必要があります。
|
注意: 変更内容を複数の形式で表すことができる場合、最も優先順位の高い形式で記録する必要があります。たとえば、次のように入力します。
|
カスタム・ユーザー・カスタマイズを作成する手順:
コンポーネントを含むページのマネージドBeanを作成します。
変更に使用されるコンポーネントのイベント・ハンドラ・メソッドに、コードを追加します。このコードは、変更を含むコンポーネントを取得する必要があります。その後、このコンポーネントと適切なAPIを使用して、変更内容を作成し、記録して、永続させます。
例40-6に、MDSリポジトリに永続させる変更のための、コマンド・ボタンのアクション・イベント・ハンドラのコードを示します。ユーザーがボタンをクリックすると、ソース・グラフィック・ファイルが変更されます。イベント・ハンドラ・メソッドはコンポーネントにアクセスして、グラフィックのソース属性を変更します。その後、addAttributeChangeプライベート・メソッドを呼び出します。このメソッドは、まずコンポーネントAPIを使用して変更内容を記録し、次にAttributeComponentChangeクラスを使用して新しいソース属性値を設定します。
例40-6 マネージドBeanでのイベント・ハンドラからの変更のリポジトリへの永続化
public void modifyObjectImage(ActionEvent event) {
UIComponent uic = event.getComponent().findComponent("oi1");
String source = "/images/mediumAd.gif";
uic.getAttributes().put("source", source);
_addAttributeChange(uic, "source", source);
}
.
.
.
private static void _addAttributeChange(UIComponent uic, String attribName,
Object attribValue) {
FacesContext fc = FacesContext.getCurrentInstance();
ChangeManager cm =
RequestContext.getCurrentInstance().getChangeManager();
ComponentChange cc =
new AttributeComponentChange(attribName, attribValue);
cm.addComponentChange(fc, uic, cc);
}
|
注意: 変更内容を永続させる場合、コンポーネントの変更を明示的に記録するほかに(例40-6で さらに、制限された変更永続性設定に関係なく、コンポーネントが常にリポジトリに永続されることがわかっている場合、かわりに |
ChangeManagerクラスでは、AttributeComponentChangeからAttributeDocumentChangeへの自動変換がサポートされ、これにより、リポジトリへの永続が可能になります。ただし、別のタイプの変更を変換する必要があり、DocumentChangeクラスを実装しない専用の変更マネージャ・クラスを使用する場合は、コンポーネント変更をドキュメント変更に変換するDocumentFactoryカスタム実装を作成する必要があります。
|
注意:
JSPXドキュメントで表すことのできる属性値のみ、
|
DocumentFactoryカスタム実装を作成した場合、beanで次のメソッドを使用して、適切な変更マネージャ・クラスに登録する必要があります。
public static void registerDocumentFactory(String targetClassName,
String converterClassName)
targetClassNameはComponentChangeクラスの名前で、converterClassNameはターゲットのComponentChangeをDocumentChangeに変換できるDocumentChangeFactory拡張の名前です。これらのクラスのnameのセマンティックスは、java.lang.ClassクラスのgetName()のものと同じです。
コンポーネント変更の作成に使用するクラスでコンポーネントのサブツリーを持つ子が追加され、変更をリポジトリに永続させる場合、変更を表すDocumentFragmentを作成する必要があります。
例40-7に、AddComponentDocumentChange専用クラスを使用してDocumentChangeオブジェクトを作成し、DocumentFragmentを使用して変更を表す方法を示します。
例40-7 ComponentChangオブジェクトのDocumentChangeオブジェクトへの変換
public void appendChildToDocument(ActionEvent event)
{
UIComponent eventSource = event.getComponent();
UIComponent uic = eventSource.findComponent("pg1");
// only allow the image to be added once
if (_findChildById(uic,"oi3") != null)
return;
FacesContext fc = FacesContext.getCurrentInstance();
DocumentFragment imageFragment = _createDocumentFragment(_IMAGE_MARK_UP);
DocumentChange change = new AddChildDocumentChange(imageFragment);
ChangeManager apm = RequestContext.getCurrentInstance().getChangeManager();
apm.addDocumentChange(fc, uic, change);
}
private static final String _IMAGE_MARK_UP =
"<af:objectImage id='oi3' height='100' width='120' " +
"source='http://www.somewhere.com/someimage.jpg' " +
"xmlns:af='http://xmlns.oracle.com/adf/faces'/>";
private static DocumentFragment _createDocumentFragment(
String markUp)
{
// prepend XML declaration
markUp = "<?xml version = '1.0' encoding = 'ISO-8859-1'?>" + markUp;
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
factory.setNamespaceAware(true);
factory.setValidating(false);
DocumentBuilder builder;
try
{
builder = factory.newDocumentBuilder();
}
catch (ParserConfigurationException pce)
{
_LOG.log(Level.WARNING, "Unable to get XML Parser:", pce);
return null;
}
try
{
// use a version explicitly with ISO-8859-1 instead
byte[] markupBytes = markUp.getBytes();
Document newDoc = builder.parse(new ByteArrayInputStream(markupBytes));
DocumentFragment fragment = newDoc.createDocumentFragment();
// add the document's root element to the fragment
fragment.appendChild(newDoc.getDocumentElement());
return fragment;
}
catch (SAXException se)
{
_LOG.log(Level.WARNING, "Unable to parse markup:" + markUp, se);
return null;
}
catch (IOException ioe)
{
_LOG.log(Level.WARNING, "IO Problem with markup:" + markUp, ioe);
return null;
}
}
40.3項「ユーザー・カスタマイズの構成」の説明に従ってadf-config.xmlファイルにユーザー・カスタマイズを登録します。カスタム変更がAttributeDocumentChange以外のタイプの場合、adf-config.xmlファイルを手動で編集して、すべての変更がコンポーネントに許可されていることを示す必要があります(例40-8を参照)。
カスタム・コンポーネントを作成する際、アプリケーションで変更永続性が使用可能な場合に、そのコンポーネントの特定の属性値を永続させるように指定できます。カスタム・コンポーネントでの暗黙的な変更の設定は、既存のコンポーネントでの明示的な変更永続性の設定と似ています。実際の永続化を実行するコードを追加しますが、そのコードをマネージドbeanに置くかわりに、コンポーネント・クラスで直接そのコードを処理することができます。イベントを使用してコンポーネントの属性値とサーバーが同期されている場合、ブロードキャスト・メソッドを使用して変更を永続させることができます。永続させる属性値がイベントを使用しない場合、レンダラとコンポーネント・クラスにコードを追加する必要があります。
属性値がイベントを使用する場合、コンポーネント・クラスにコードを追加する必要があります。
イベントを使用する属性値に暗黙的な変更永続性を設定する手順:
カスタム・コンポーネント・クラスjavaファイルを開きます。
ブロードキャスト・メソッドに、専用クラスを使用して新規ComponentChangeオブジェクトを作成し、ChangeManagerを呼び出して変更を追加するコードを追加します。
例40-9に、UIXShowDetailクラスに追加された、disclosed属性の変更を永続させるコードを示します。この場合、AttributeComponentChangeクラスが使用されます。
例40-9 コンポーネント・クラスからの変更の永続化
public class UIXShowDetail extends UIXComponentBase
{
...
public void broadcast(FacesEvent event) throws AbortProcessingException
{
super.broadcast(event);
...
if (event instanceof DisclosureEvent)
{
boolean isDisclosed = ((DisclosureEvent) event).isExpanded();
setDisclosed(isDisclosed);
//Record a Change for 'disclosed' attribute
AttributeComponentChange aa =
new AttributeComponentChange('disclosed', isDisclosed ? Boolean.TRUE : Boolean.FALSE);
AdfFacesContext adfContext = AdfFacesContext.getCurrentInstance();
adfContext.getChangeManager().addComponentChange(getFacesContext(), this, aa);
...
}
}
...
属性がイベントを使用しない場合、コードをコンポーネントのレンダラ・クラスに配置する必要があります。
他の属性値に暗黙的な変更永続性を設定する手順:
カスタム・コンポーネントのレンダラ・クラスjavaファイルを開きます。
ClientMetadataインスタンスをとるfindTypeConstantsメソッドを使用し、addPersistedPropertyメソッドを使用して特定のプロパティを永続とマークします。例40-10に、ADF Faces PanelSplitterコンポーネントで使用されるレンダラ・クラスのコード・スニペットを示します。ここでは、splitterPosition属性値を暗黙的に永続させます。
例40-10 変更内容を暗黙的に永続させるコンポーネント・レンダラ・クラスのメソッド
// Code snippet from PanelSplitterRenderer.java
protected void findTypeConstants(
FacesBean.Type type,
ClientMetadata metadata)
{
super.findTypeConstants(type, metadata);
metadata.addRequiredProperty(
_orientationKey = type.findKey("orientation"));
metadata.addRequiredProperty(
_positionedFromEndKey = type.findKey("positionedFromEnd"));
metadata.addRequiredProperty(
_disabledKey = type.findKey("disabled"));
metadata.addRequiredProperty(
_splitterPositionKey = type.findKey("splitterPosition"));
metadata.addPersistedProperty(_splitterPositionKey);
}
JavaScriptコンポーネント・ピア・クラスで、setProperty関数を使用して永続させる属性値を定義します。この関数は、属性名(前の手順でレンダラで定義した)、値およびtrueを使用して呼び出す必要があります。これにより、属性の値が設定されます。例40-11に、スプリッタの位置を設定するpanelSplitterクラスのコード・スニペットを示します。
