| Oracle® Fusion Middleware Oracle WebCenter PortalおよびOracle JDeveloperでのポータルの開発 11gリリース1 (11.1.1.8.3) E49666-03 |
|
 前 |
 次 |
| Oracle® Fusion Middleware Oracle WebCenter PortalおよびOracle JDeveloperでのポータルの開発 11gリリース1 (11.1.1.8.3) E49666-03 |
|
前 |
次 |
この章では、ファンクション・プロバイダについて紹介します。また、データの統合とデータ統合アーキテクチャにおけるその重要な役割について説明し、JDeveloperで作成および実行できる基本的な例を示します。この章を読むと、ファンクション・プロバイダの実装方法の基礎が理解できます。
この章には次の項が含まれます。
データ・プロバイダがデータ・ソースに接続してデータを取得するのに対し、ファンクション・プロバイダは、シナリオのコンテキスト内のデータを操作します。WebCenter Portalでは、多くのデフォルトのファンクション・プロバイダが用意されており、リスト・オブジェクト、日付オブジェクト、SQLデータなどを操作するためのプロバイダなどがあります。また、カスタム・ファンクション・プロバイダを実装して、特定のユース・ケースに対処できます。
WebCenter Portalには、一連のデフォルトのファンクション・プロバイダが用意されており、一般的に必要とされる特定のタスクを実行します。WebCenter Portalでは、ファンクション・プロバイダが用意されており、リストや日付の作成および操作などの、一般的な操作に対処します。さらに、デフォルトのファンクション・プロバイダには、SQLデータ・プロバイダやRESTデータ・プロバイダなど、特定のデータ・プロバイダが返すデータに対処するものがあります。
一部のユース・ケースでは、一連の標準のファンクション・プロバイダでは不十分な場合があります。その場合、独自のカスタム・ファンクション・プロバイダを作成してデプロイすることも選択できます。たとえば、カスタム・データ・プロバイダから返された、特定のデータセットを操作する必要がある場合、そのデータを処理するために、カスタム・ファンクション・プロバイダを作成する必要がある場合があります。第68.4項「単純なカスタム・ファンクション・プロバイダの実装」を参照してください。
デフォルト・ファンクション・プロバイダおよびカスタム・ファンクション・プロバイダのリストを検出する1つの方法は、図68-1に示すように、「シナリオ式ビルダー」ダイアログを表示することです。
Executeシナリオ・ノードを作成します。
「Execute」ノードを右クリックし、「式の設定」を選択します。
例については、第68.6項「シナリオ内のファンクション・プロバイダのコール」を参照してください。
ファンクション・プロバイダを使用すると、データに対する操作を行うことが可能になります。たとえば、図68-1は「シナリオ式ビルダー」ダイアログを示しています。コレクション・ファンクション・プロバイダが選択されています。ドロップダウン・リストを使用して、データのコレクションを処理するファンクション・プロバイダのメソッドを選択できます。コレクション・ファンクション・プロバイダは、様々なデフォルト・ファンクション・プロバイダの中の1つです。
ファンクション・プロバイダの選択後は、パラメータが存在する場合は、その値を入力する必要があります。ファンクション・プロバイダへのパラメータ値の入力は、「式ビルダー」ダイアログ内で式言語文を編集して行います。このダイアログでは、コンテキスト・サービス同様、現在のシナリオ・コンテキストでも使用可能な、すべての変数のリストも提供されます。これらは、現在のアプリケーションのスコープ内に存在する変数です。
|
注意: ファンクション・プロバイダは、条件文やReturn文などの、式ビルダーを使用するシナリオ・エディタ内の他の文のコンテキストで表示されます。ただし、各文に関連付けられた式ビルダーのユーザー・インタフェースは、同一です。 |
使用可能なファンクション・プロバイダを検出するもう1つの方法は、RESTリクエストを実行してレスポンスを表示することが可能なツールで、RESTのレスポンスを表示することです。
ブラウザで、次のURLを入力します。ここでホストおよびポートは、WCPSサーバーが稼働しているホスト名とポート名です。例:
http://example.com:8891/wcps/api/conductor/resourceIndex
ネームスペースのURIを検索し、そのURLをブラウザで入力します。例:
http://example.com:8891/wcps/api/conductor/namespaces
アプリケーションのfunctionProvidersのURIを検索し、そのURLをブラウザで入力します。projectionの値をsummaryに設定します。例:
http://mexample.com:8891/wcps/api/conductor/namespaces/MyApplication/functionProviders?projection=summary
このURLは、サーバーにデプロイされたすべてのファンクション・プロバイダを含む、RESTレスポンスを返します。この方法は、新しいファンクション・プロバイダの構成をテストするため実行する、手軽なテストでもあります。
この項では、単純なカスタム・ファンクション・プロバイダの実装方法、構成方法およびシナリオ内での起動方法について説明します。これは非常に基本的な例ではありますが、カスタム・プロバイダの開発および構成の多くの重要な側面について説明しています。
JDeveloperでのファンクション・プロバイダの開発を始める前に、適切に設定が行われていることを確認します。いくつかの構成は、使用する環境で構成を行うか、確認する必要があります。詳細は、第2.5項「パーソナライズのためのJDeveloperの設定」を参照してください。
一般的なガイダンスとして、図68-2に、カスタム・ファンクション・プロバイダの実装用の、サンプルのプロジェクト構造を示します。ファンクション・プロバイダの開発は、Javaの開発をサポートする、あらゆるタイプのJDeveloperプロジェクトで可能です。JDeveloperでのJavaクラスの作成の詳細は、JDeveloperオンライン・ヘルプを参照してください。
|
注意: この例では、プロバイダはJDeveloperのFusion Webアプリケーションの状態で作成されています。ファンクション・プロバイダは、WebCenter Portalアプリケーションや、Javaの機能が組み込まれた、他の任意のタイプのJDeveloperアプリケーションの状態で作成することも可能です。 |
すべてのファンクション・プロバイダは、IFunctionProviderインタフェースの実装です。データ・プロバイダ同様、ファンクション・プロバイダでも、Java注釈を使用するとメソッドとパラメータがシナリオ・エディタのユーザー・インタフェースに表示されるようになります。
例68-1に、ファンクション・プロバイダの例を示します。これは、数字に書式を設定するメソッドを提供します。以降の項では、クラスの先頭やメソッドおよびパラメータの前後に現れる必須のJava注釈を含む、クラスの要素を詳細に確認します。
|
ヒント: 一般的なクラスの作成手順では、「ファイル」メニューから「新規」を選択して、新規Javaクラスの作成を選択します。コードの例をファイルにコピーして保存します。「Javaクラスの作成」ダイアログで、パッケージ |
|
注意: ファンクション・プロバイダは、単純にJavaコンポーネントなので、いずれのサーバー・サイドJavaコンポーネントでも適用されるような例外処理のベスト・プラクティスを適用できます。 |
例68-1 ファンクション・プロバイダの例
package model;
import oracle.wcps.conductor.annotation.FunctionProvider;
import oracle.wcps.conductor.provider.IFunctionProvider;
import oracle.wcps.conductor.annotation.PublicFunction;
import oracle.wcps.conductor.annotation.PublicParameter;
import java.text.DecimalFormat;
import java.lang.NumberFormatException;
import oracle.wcps.conductor.exception.ConductorRuntimeException;
@FunctionProvider
(
prefix="number",
resourceBundle="resources.Providers",
nameBundleKey="function.provider.name",
descriptionBundleKey="function.provider.description"
)
public class FormatNumberProvider implements IFunctionProvider {
@PublicFunction
(
functionName="format",
descriptionBundleKey="format.description"
)
public static String getNumber(@PublicParameter(parameterName="pattern",
descriptionBundleKey="pattern.description") String pattern,
@PublicParameter(parameterName="number", descriptionBundleKey="number.description") String number) {
Double dd;
dd = new Double("1.0");
try {
dd = new Double(number);
} catch (NumberFormatException e){
return ("You must enter a valid number.");
}
DecimalFormat df = new DecimalFormat(pattern);
return number = df.format(dd);
}
}
図68-3に、Javaソース・ファイルの例であるFormatNumProvider.javaの、JDeveloperのアプリケーション・ナビゲータでの表示を示します。このファイルは、modelというパッケージ内にあります。
|
ヒント: 読者が作成したソース・ファイルの構成とは異なる可能性がありますが、少なくとも図68-3は、ファンクション・プロバイダの完全なプロジェクト構造を示しています。この一般的なプロジェクト構造のパターンが、ベスト・プラクティスです。 |
ファンクション・プロバイダは、任意のオブジェクトを返すことが可能です。最善の方法として、戻りオブジェクトはマーシャリング可能で、JAXB標準に準拠するようにしてください。この条件に従った戻りオブジェクトは、データ・プロバイダの入力など、シナリオ内の任意の場所で使用できます。
各ファンクション・プロバイダ・クラスには、クラス定義の直前に、次のようなJava注釈スタンザが必要です。
@FunctionProvider ( prefix="number", resourceBundle="resources.Providers", nameBundleKey="function.provider.name", descriptionBundleKey="function.provider.description" )
接頭辞要素には名前を指定します。この名前はシナリオ・エディタのユーザー・インタフェースに表示され、ファンクション・プロバイダを選択できるようになります。たとえば、このファンクション・プロバイダがシナリオで参照されている場合、メソッドは式言語式を使用して次のようにコールされます。${number:getNumber(format, number)"}
|
注意: 接頭辞名および変数には、ハイフンまたは空白を含めないでください。ハイフンまたは空白が接頭辞名または変数内に存在する場合、式言語式では参照できません。 |
resourceBundle要素は、ファンクション・プロバイダのクラス・パスに存在する、リソース・ファイルを参照します。その他の注釈は、リソース・ファイル内の文字列を識別するため使用される、リソース・バンドル・キーです。リソース・ファイルは、主としてローカライゼーションをサポートします。
次の項で説明するように、ファンクション・プロバイダのメソッドおよびメソッドのパラメータの前後には注釈も必要です。注釈を使用するには、次のクラスをインポートする必要があることに注意します。
import oracle.wcps.conductor.annotation.PublicFunction; import oracle.wcps.conductor.annotation.PublicParameter;
メソッドおよびそのパラメータには、例68-0に示すパターンに従って注釈を付ける必要があります。functionNameの値は、ユーザー・インタフェースに表示されます。descriptionBundleKeyに値を指定すると、クラスの先頭で指定されているリソース・ファイルに説明を記述できます。メソッドのパラメータの注釈でも、同様のパターンが適用されます。
|
ヒント: Java Bean形式のget構文を使用してメソッドを作成した場合は、便利なドット表記法を使用してELによりオブジェクト属性にアクセスできます。たとえば、プロバイダにfooという属性とgetFoo()というメソッドがある場合、次のような文を使用して、シナリオ内でELでドット表記法を使用して属性にアクセスできます。${myReturnObject.foo()} |
例68-2 メソッドおよびパラメータ用のJava注釈
@PublicFunction
(
functionName="format",
descriptionBundleKey="format.description"
)
public static String getNumber(@PublicParameter(parameterName="pattern",
descriptionBundleKey="pattern.description") String pattern,
@PublicParameter(parameterName="number", descriptionBundleKey="number.description") String number) {
Double dd;
dd = new Double("1.0");
try {
dd = new Double(number);
} catch (NumberFormatException e){
return ("You must enter a valid number.");
}
DecimalFormat df = new DecimalFormat(pattern);
return number = df.format(dd);
}
}
新しいファンクション・プロバイダ・クラスを作成した後は、コンパイルして、適切にデプロイする必要があります。これらの作業を正常に完了すると、プロバイダがシナリオ・エディタの式ビルダー・ユーザー・インタフェースに表示されます。この項では、必要な手順について説明します。
|
注意: ファンクション・プロバイダのデプロイは、大部分が手作業による手順のため、注意を要します。これらの手順には、慎重に従う必要があります。いかなる時点の単純な入力ミスでも、プロバイダをデプロイできなくなります。 |
手順を要約すると、次のものを格納したJARファイルをデプロイする必要があります。
コンパイル済のファンクション・プロバイダ・クラス
リソース・プロパティ・ファイル(クラスと同一のディレクトリ内に存在する必要があります)
ファンクション・プロバイダのクラス名が記述されている構成ファイル
その後、JARファイルを手動でサーバーにコピーし、サーバーを再起動する必要があります。
ファンクション・プロバイダはJavaで作成されており、デプロイする前にコンパイルする必要があります。
図68-4に示すように、アプリケーション・ナビゲータで、ソース・コードが含まれるプロジェクトを右クリックし、「メイク」または「再ビルド」のいずれかのオプションを選択します。
ファンクション・プロバイダ・クラスのファイルに配置されたJava注釈は、リソース・プロパティ・ファイルを指します。このファイルは存在する必要があり、かつ必要なキーおよび値を格納している必要があります。このファイルを作成する基本手順は、次のとおりです。
Javaファイルが含まれるプロジェクトを右クリックし、「新規」を選択します。
「新規ギャラリ」ダイアログで、「一般」を選択します。
Javaパッケージを作成します。この例では、パッケージはresourcesという名前です。
パッケージ内にプロパティ・ファイルを作成します。この例では、このファイルはProviders.propertiesという名前です。
図68-5に、resourcesパッケージ内にあるProviders.propertiesというプロパティ・ファイルを示します。
たとえば、NumberFormatProviderクラスの注釈(例68-1のリスティングを参照)では、次のリソース・キーが示されていました。最初の注釈format.descriptionには、プロバイダの目的を記述します。その他では、各入力パラメータについて記述します。
format.description=Format a number. pattern.description=A number format pattern like #.##. number.description=The number to format.
ファンクション・プロバイダのデプロイを準備する最後の手順は、プロバイダの完全なクラス名が記述された、単純な構成ファイルを作成することです。
アプリケーション・ナビゲータで、「アプリケーション・ソース」フォルダ内に、META-INFという新しいフォルダを作成します。
META-INFフォルダ内に、servicesというフォルダを作成します。
servicesフォルダ内に、oracle.wcps.conductor.provider.IFunctionProviderというファイルを作成します。厳密にこの名前を使用する必要があります。図68-6を参照してください。
oracle.wcps.conductor.provider.IFunctionProviderファイルを開き、デプロイ対象の各ファンクション・プロバイダの完全なクラス名を入力します。
例:
model.FormatNumProvider
この項は、ユーザーがJDeveloperでのJARファイルの作成に不慣れな場合、JARファイル構造(デプロイメント・プロファイル)の設定方法を説明し、必要な要素がすべて含まれるようにするものです。
アプリケーション・ナビゲータで、プロジェクト(この例では、Portalというプロジェクト)を右クリックし、「プロジェクト・プロパティ」を選択します。
「プロジェクト・プロパティ」ダイアログで「デプロイ」を選択します。
「新規」をクリックします。
「アーカイブ・タイプ」として「JARファイル」を選択し、JARの名前を入力します。
「OK」をクリックします。
「JARオプション」ダイアログで、「コントリビュータ」を選択します。
図68-7に示すように、「プロジェクトの出力ディレクトリ」、「プロジェクトのソースパス」および「プロジェクトの依存性」が選択されていることを確認します。
「フィルタ」を選択します。
「ファイル」タブで、JARに追加するファイルのみを選択します。図68-8に示すように、JARにはMETA-INF/servicesディレクトリの内容、Javaクラスおよびリソース・フォルダを含める必要があります。
「OK」をクリックしてから、「プロジェクト・プロパティ」ダイアログの「OK」をクリックします。
プロジェクトを保存します。
JARデプロイメント・プロファイルを設定したら、プロジェクトからのJARファイルの生成は準備完了です。
アプリケーション・ナビゲータで、プロジェクト(この場合、Portalプロジェクト)を右クリックし、「デプロイ」を選択します。
デプロイするJARファイルを選択します。これは、第68.5.4項「JARファイル構造の設定」でファイルに指定した名前です。
「デプロイメント・アクション」ダイアログで、「JARファイルにデプロイ」を選択して「終了」をクリックします。
JARファイルがプロジェクト・ディレクトリに配置されます。このファイルは、ファイル・システムの<Workspace_Directory>/Portal/deployで確認できます。たとえば、MyProvidersというワークスペースの場合、JARはC:\JDeveloper\mywork\MyProviders\Portal\deployにあります。
JARファイルは、サーバーにコピーする必要があります。
前の手順で作成したJARファイルをコピーします。前述したとおり、ファイルは<Workspace_Directory\Portal\deployに配置されています。
JARファイルを、サーバーの次の場所に貼り付けます。
DOMAIN_HOME/conductor-extensions-library/WEB-INF/lib
たとえば、統合WebLogic Server環境では次の場所になります。
C:\JDeveloper\system11.1.7.40.63.82\DefaultDomain\conductor-extensions-library\WEB-INF\lib
また、管理対象サーバー環境では次の場所になります。
ORACLE_HOME/oracle/user_projects/applications/wc_domain/conductor-extensions-library/WEB-INF/lib
サーバーを再起動します。
デプロイのテストは、UIにカスタム・データ・プロバイダが表示されることを確認するか、REST APIを使用して検索できることを確認するだけです。詳細は、第68.3項「ファンクション・プロバイダの検出」を参照してください。
デプロイしたファンクション・プロバイダが見つからない場合は、行った手順を見直して、構成ファイルやリソース・ファイルに誤字があるような、明らかな誤りがないことを注意深く確認します。第68.5.4項「JARファイル構造の設定」の説明に従って、JARファイルが適切に作成されていることを確認します。また、JARファイルが適切なドメインにコピーされていることを確認します。
再確認の必要がある一般的なミスには、次のものがあります。
META-INF/servicesの内容を、JARファイルに含める必要があります。
JARファイルはDOMAIN_HOME/conductor-extensions/WEB-INF/libフォルダにコピーする必要があります。ファイルのコピー後は、サーバーを再起動する必要があります。
シナリオ・エディタを使用すると、変数に対して操作を行うことが可能なかぎり、変数の設定、return文の作成、データ・プロバイダへの入力パラメータの作成、条件分岐文の設定などの、いずれの場合でもファンクション・プロバイダをコールできます。
ファンクション・プロバイダは、常に「式ビルダー」ダイアログ内からコールします。このダイアログを使用すると、ファンクション・プロバイダの選択と、実行対象の特定のメソッドの選択が可能です。プロバイダが入力パラメータを取る場合、パラメータを式言語(EL)文で指定する必要があります。EL文は、メソッドの選択の際に自動的に生成されるので、その後は適切な変数の選択または入力のみを行います。
たとえば、ファンクション・プロバイダの例、NumberFormatProvider (例68-1にリストされている)を見てみます。
プロバイダのクラスには、prefixという注釈があります。この例では、この注釈にnumberが設定されています。「式ビルダー」ダイアログでは、ファンクション・プロバイダのドロップダウン・リストにnumberというプロバイダが表示されているのがわかります。図68-9では、「関数」ドロップダウン・リストでnumberというファンクション・プロバイダが選択されています。numberの下は、プロバイダにあるメソッドのリストです。この例では、formatという1つのメソッドのみが含まれています。formatはメソッドのfunctionName注釈で指定されていたものです。
|
注意: 接頭辞名および変数には、ハイフンまたは空白を含めないでください。ハイフンまたは空白が接頭辞名または変数内に存在する場合、式言語式では参照できません。 |
ダイアログの「式」フィールドには、EL文が自動的に入力され、ファンクション・プロバイダに変数を渡すことが可能になります。式は次のとおりです。
${number:format(format,myNumber)}
式を解析すると、次のとおりです。
numbers: ファンクション・プロバイダのクラス注釈で指定された、ファンクション・プロバイダの名前です。
format: メソッドの注釈で指定された、メソッドの名前です。
pattern: メソッドの注釈で指定された、最初のパラメータの名前です。この場合、「説明」に表示されているように、パラメータの型は文字列です。ファンクション・パラメータの実装でわかるように、この文字列は、数字の書式設定方法を表すパターンです。このパラメータは、JavaクラスのDecimalNumberが元になっています。詳細は、このクラスのJavadocを参照してください。
number: メソッドの注釈で指定された、2番目のパラメータの名前です。この場合も、パラメータの型は文字列です。単に文字列として表された数字です。
シナリオ・エディタおよび式ビルダーの使用の詳細は、第66章の「JDeveloperでのパーソナライズされたシナリオの作成」を参照してください。
