16 アプリケーション・モジュールによるADF RESTful Webサービスの作成

この章では、ADFアプリケーション・モジュールのビュー・オブジェクト・インスタンスに基づいてADF RESTリソースを作成し、Fusion WebアプリケーションでこれらのリソースをADF RESTful Webサービスとして使用できるようにする方法を説明します。

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

• RESTful WebサービスおよびADFビジネス・コンポーネントについて

• アプリケーション・モジュールを使用したADF RESTリソースの作成

• ADF RESTリソース表現のカスタマイズ

• ADF RESTリソースのバージョニング

• ADF RESTランタイム・フレームワークのバージョニング

• ADF RESTリソースへのクライアント・アクセスの付与

• ADF RESTリソースのデプロイ

• 統合WebLogic Serverを使用したADF RESTリソースのテスト

RESTful WebサービスおよびADFビジネス・コンポーネントについて

ADFビジネス・コンポーネントのビュー・オブジェクト・インスタンスは、RESTを使用してWebサービスとして公開できます。クライアント開発者は、ADF RESTランタイムで有効になっているREST APIを介してこれらのリソースとやり取りします。

REpresentational State Transfer (REST)は、WebサービスがそれらのURLによって識別されるリソースとして表示されるステートレス・クライアント/サーバー・アーキテクチャをサポートします。GETやPOSTなどのHTTPリクエスト・メソッドは、HTTP URLによって表現されるリソースに対して実行する必要がある、作成、読取り、更新および削除(CRUD)アクションを記述するために、Webサービス・クライアント・リクエスト・メッセージで開発者が使用できる動詞です。RESTでは、HTTP、URL、URI、XML、HTMLなどの規格の使用やリソース・タイプおよびMIMEタイプを規定しています。そのため、RESTは規格ではなく、Webサービスのアーキテクチャ・スタイルの提案となります。

RESTの設計制約に準拠するWebサービスはRESTfulと呼ばれます。このタイプのWebサービスでは、HTTPクライアントとHTTPサーバーがURLによって識別されるリソース情報を交換できます。リクエストおよびレスポンスには、特定の形式でリソースの表現が含まれ、これにより、実際のリソースの状態が定義されます。

Fusion Webアプリケーションにおいては、RESTful Webサービスによって操作されるADF RESTリソースは、ADFビジネス・コンポーネント・モデル・プロジェクトのデータ・モデルで公開されるビュー・オブジェクト・インスタンスが基礎となっています。ADFモデル・プロジェクトで作業するADFビジネス・コンポーネント開発者は、基礎となるビュー・オブジェクトから公開する属性のセット、CRUD操作を使用可能にするアクションおよび結果として生成されたリソースを保存するビュー・リンク関係を決定できます。

ノート:

ADF RESTリソースとして公開する目的でビュー・オブジェクトを作成する場合、ビュー・オブジェクトの作成・ウィザードで「問合せ」ページのDeclarativeオプションを使用して、宣言SQLモード・オプションが有効なビュー・オブジェクトを作成します。設計時に宣言SQLモードで作成されたビュー・オブジェクトは、ADF RESTフレームワーク実行時最適化をサポートし、リソース・コレクションは、URL問合せパラメータfieldsで作成されたクライアント・リクエストを使用して効果的にフィルタ処理されます。

ADFビジネス・コンポーネント開発者による設計時の選択内容は、RESTリソース定義XMLファイルで取得されます。Webサービス・クライアントの開発者は、ADF RESTランタイムで有効化されているREST APIによってこれらのリソース定義と対話できます。これにより、使用するサービス・クライアントはCRUD操作を起動して、RESTリソースおよびADFビジネス・オブジェクトと対話できます。データは、親子関係はそのままで、リソースの基礎となるビュー・オブジェクト・インスタンスによって形成されます。

ADFビジネス・コンポーネント・プロジェクトでの最初のRESTリソースを作成するとき、JDeveloperによって、ADF RESTサーブレットを登録する個別のRESTful Webサービス・プロジェクトも生成されます。図16-1に、JDeveloperによって生成されるweb.xmlファイルを示します。このプロジェクトを使用してRESTful Webサービスを実行およびデプロイします。

図16-1 RESTful Webサービス・プロジェクトを表示する「アプリケーション」ウィンドウ

「図16-1 RESTful Webサービス・プロジェクトを表示する「アプリケーション」ウィンドウ」の説明

ADF RESTリソースのセキュリティは、Fusion Webアプリケーションを保護する方法に類似したRESTful Webサービスで適用されます。JDeveloperで、ADFセキュリティの構成ウィザードを実行して、ADFモデル・プロジェクトにセキュリティを適用します。ウィザードを実行した後、デプロイされたRESTful WebサービスのRESTリソースはデフォルトで保護されているため、このサービスの操作に対してアクセス権を付与することが必要になります。

JDeveloperでセキュリティをテストするには、テスト・ユーザーを作成してこれらのユーザーにリソースへのアクセス権限を付与します。次に、これらのアクセス権を付与するセキュリティ・ポリシーをアプリケーション・レベルからドメイン・レベルのセキュリティ・ポリシー・ストアに移行します。セキュリティ・ポリシー・ストアで、エンタープライズ・ユーザーにアクセス権がプロビジョニングされます。

RESTful Webサービスのユースケースと例

開発チームはADF RESTリソースを公開し、Fusion Webアプリケーションに提供できます。ADF RESTアプリケーション開発者は、次のようなバージョニング機能を使用してサービス・クライアントに公開する機能を管理できます。

• RESTリソースのバージョニングをサポートするために、RESTリソースをアプリケーション固有のリソース・バージョン名(または番号)で登録します。

• RESTリソースに対してデフォルトのADF RESTフレームワーク・バージョンを宣言すると、サービス・クライアントでは、ADF RESTランタイム・フレームワークのバージョン2で提供される拡張問合せ機能など、新機能および拡張機能を実行時に利用できます。リクエストを処理するデフォルトのフレームワーク・バージョンを宣言することで、RESTアプリケーション開発者は準備が整えば特定のADF RESTフレームワークで導入される機能を選択できます。JDeveloperでは、リリース12.2.1.2.0以降、バージョン1、2および3が存在します。12.2.1.4.0以降のリリースには、バージョン1、2、3、4、5、6および7が存在します。

クライアントとサーバーによるリソース情報の交換をサポートするADF RESTフレームワークの固有のランタイム機能には、次のものがあります。

• RESTリソースとの対話は、リソース、アクション実行、およびアクション実行の結果に対して、個別のJSONベース・メディア・タイプ構造によってサポートされています。

• カスタム・ヘッダーを渡して、リクエストの処理に使用するADF RESTランタイム・フレームワークのバージョンを指定します。バージョン・ヘッダーにより、サービス・クライアントではRESTアプリケーションによって定義されたデフォルトのバージョン宣言をオーバーライドできます。JDeveloperでは、リリース12.2.1.2.0以降、バージョン1、2および3が存在します。12.2.1.4.0以降のリリースには、バージョン1、2、3、4、5、6および7が存在します。

• GET、POST、PATCH、DELETEなどの標準HTTPリクエスト・メソッドを使用してRESTリクエストと対話します。

• クライアントでの制限によりRESTリソースとの対話に標準HTTPメソッドを使用できない場合は、POSTリクエスト・メソッドを使用するX-HTTP-Method-Overrideヘッダーを使用してHTTPメソッドを実行します。

• POSTメソッドと、trueに設定したUpsert-Modeヘッダーを組み合せて使用して、ペイロード・コンテンツをRESTリソースとマージします。このアクションによって、作成(レコードが存在しない場合)または更新(レコードが存在する場合)が実装されます。

• RESTリソース・アイテム(特定の従業員など)やRESTリソース・コレクション(すべての従業員のコレクションなど)の特定は、ADFビジネス・コンポーネント・モデル・プロジェクトで定義されているリソース名に基づくREST準拠のURIパス名によってサポートされます。

• RESTリソース(リソース属性および使用可能なアクションなど)の説明の取得は、特定のメディア・タイプとdescribeアクションによってサポートされます。

• ADF RESTフレームワーク・バージョン4以降が有効になっている場合、JSONペイロード形式のエラー・レスポンスと例外の詳細を取得します。フレームワーク・バージョン3以前では、エラー・レスポンスの形式は単純なメッセージ文字列です。

• 正規RESTリソースへのリンクは、更新可能エンティティのスーパーセットを持つリソースが定義されている場合にサポートされます。正規のリンクでは、基礎となるビュー・オブジェクトの代替リンクがサポートされます。

• RESTリソースのフィルタ処理は、クライアントが特定のリソースにアクセスするために指定されたURIの問合せ文字列パラメータによりサポートされています。

• 圧縮および解凍を有効化するために、エンコーディング形式がRESTリソースでサポートされています。

• RESTリソースにより公開されるBLOB属性とCLOB属性のコンテンツのストリーミングは、ADF RESTフレームワークでサポートされています。

• RESTful Webサービス起動時のデータ整合性チェックの実行は、ADF RESTフレームワークでサポートされています。この機能では、データベースのバージョン履歴を使用して、クライアントがリソース自体の更新に応じてHTTPペイロードを管理できるようにします。

• ユーザーに対するRESTリソースへのアクセスの認可は、ADFセキュリティ権限の付与によって有効化されます。

RESTful Webサービスの追加機能

RESTful Webサービスを使用する前に、他のOracle ADF機能を理解しておくと役立つ場合があります。次に、関連するサポート機能へのリンクを示します。

• 推奨される宣言SQLモードでビュー・オブジェクトを作成し、実行時に効果的にリソース・コレクションのフィルタ処理をサポートする方法の詳細は、「宣言SQLモードでのビュー・オブジェクトの使用」を参照してください。

• サービス・クライアントでデータの一貫性チェックがサポートされるようにする場合に、エンティティ・オブジェクトに対して更新識別子属性を有効にする方法の詳細は、「同時更新によるデータの消失を防ぐ方法」を参照してください。

• ADF RESTリソースのファインダを公開する場合に、ビュー・オブジェクトで行検索を作成する方法の詳細は、「行検索の使用」を参照してください。

• ADF RESTリソースのLOVリンクを公開する場合に、LOVの有効なビュー・オブジェクト属性を作成する方法の詳細は、「ビュー・オブジェクト属性の値リスト(LOV)での作業」を参照してください。

• ADF RESTリソースのサブタイプ・ビュー行を公開する多相ビュー・オブジェクトの作成の詳細は、「多相ビュー行関連の作業」を参照してください。

• REST APIを使用したADF RESTリソースへの実行時アクセスを可能にするADF RESTフレームワークの詳細は、「ADF RESTful Webサービスの消費」を参照してください。

• ADF RESTデータ・コントロールを使用したユーザー・インタフェースの設計の詳細は、「ADF RESTful WebサービスからのADF RESTデータ・コントロールの作成」を参照してください。

• 表からのビジネス・コンポーネントの作成ウィザードを使用してADF RESTリソースを作成する方法の詳細は、「ADF REST Webアプリケーションのデータ・モデル・プロジェクトの作成方法」を参照してください。

アプリケーション・モジュールを使用したADF RESTリソースの作成

ADFアプリケーション・モジュールに公開するビュー・オブジェクト・インスタンスを使用して、ADF RESTリソースを作成できます。

アプリケーション・モジュールは、ビュー・オブジェクト・インスタンスとして公開される、一連の関連するビジネス機能としてビジネス・ロジックをカプセル化する、ADFビジネス・コンポーネント・フレームワーク・コンポーネントです。アプリケーション・モジュールのデータ・モデルに出現する1つ以上のビュー・オブジェクト・インスタンスをADF RESTリソースにマップできます。アプリケーション・モジュールの概要エディタを使用して、ADF RESTリソースを作成します。ADFモデル・プロジェクトに追加するRESTリソースは、RESTアーキテクチャ・スタイルに従うWebサービスとして公開される場合があります。

ノート:

ADF RESTリソースとして公開する目的でビュー・オブジェクトを作成する場合、ビュー・オブジェクトの作成・ウィザードで「問合せ」ページのDeclarativeオプションを使用して、宣言SQLモード・オプションが有効なビュー・オブジェクトを作成します。設計時に宣言SQLモードで作成されたビュー・オブジェクトは、ADF RESTフレームワーク実行時最適化をサポートし、リソース・コレクションは、URL問合せパラメータfieldsで作成されたクライアント・リクエストを使用して効果的にフィルタ処理されます。

表からのビジネス・コンポーネントの作成ウィザードを使用してADF RESTリソースを作成する方法

「新規ギャラリ」の「ADFビジネス・コンポーネント」カテゴリでは、JDeveloperはそれぞれのビジネス・コンポーネントを作成するためのウィザードを提供しています。各ウィザードでは、新規コンポーネントのコンポーネント名を指定し、どのパッケージにコンポーネントを配置するかを選択できます。パッケージがまだ存在しない場合、新規コンポーネントがそのパッケージの最初のコンポーネントになります。

表からのビジネス・コンポーネントの作成ウィザードは、様々なビジネス・コンポーネントの生成とRESTリソースの作成を単一のエンドツーエンドのプロセスに組み合せた唯一のウィザードであるため、JDeveloperで特に役立ちます。このウィザードを使用すると、RESTリソースを迅速かつ容易に作成できます。オンラインまたはオフラインのデータベースに基づいてエンティティ・オブジェクトを作成し、その後、エンティティベースのビュー・オブジェクトまたは問合せベースのビュー・オブジェクトのいずれかとデータ・モデルのビュー・インスタンスを含むアプリケーション・モジュールを作成し、さらにADF RESTリソースを作成できます。

始める前に:

様々なADFビジネス・コンポーネントを理解しておくと役立つ場合があります。詳細は、「ADFビジネス・コンポーネントについて」を参照してください。

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

• 「ADF REST Webアプリケーションのデータ・モデル・プロジェクトの作成方法」の説明に従い、ビジネス・コンポーネントを含むデータ・モデル・プロジェクトを作成します。

表からのビジネス・コンポーネント・ウィザードでRESTリソースを1回で作成するには:

1. 「アプリケーション」ウィンドウで、エンティティ・オブジェクトを作成するプロジェクトを右クリックし、「新規」を選択します。
2. 「新規ギャラリ」で、「ビジネス層」を展開し、「ADFビジネス・コンポーネント」を選択してから「表からのビジネス・コンポーネント」を選択し、「OK」をクリックします。

   これがプロジェクトで作成する最初のコンポーネントである場合、「ビジネス・コンポーネント・プロジェクトの初期化」ダイアログが表示され、データベース接続を選択できます。「データベース接続を使用してデータ・モデル・プロジェクトを初期化する方法」の説明に従い、ダイアログを完了します。

3. 表からのビジネス・コンポーネントの作成ウィザードの「エンティティ・オブジェクト」ページで、使用可能なデータベース・オブジェクトを表示するためのデータベース・スキーマをフィルタリングし、エンティティ・オブジェクトを作成するデータベース・オブジェクトを選択します。「次へ」をクリックします。

   デフォルトのパッケージ名を変更する場合は、パッケージ名にrestなどの予約語を使用しないでください。パッケージの命名の詳細は、「パッケージの命名規則に関する必知事項」を参照してください。

4. 「エンティティ・ベースのビュー・オブジェクト」ページで、エンティティ・オブジェクト定義の更新可能なビュー・オブジェクト定義を作成するための使用可能なエンティティ・オブジェクトを選択します。「次へ」をクリックします。

   このウィザードで作成するビュー・オブジェクト定義には、エンティティ・オブジェクトの1回の使用が含まれ、そのオブジェクト内のすべての属性を公開する点に注意してください。

5. 「問合せベースのビュー・オブジェクト」ページで、読取り専用のビュー・オブジェクト定義を作成するための使用可能なデータベース・オブジェクトを選択します。「次へ」をクリックします。
6. 「アプリケーション・モジュール」ページで、「アプリケーション・モジュールへの追加」チェック・ボックスを選択し、他のデフォルト選択はそのままにします。「次へ」をクリックします。
7. 「RESTリソース」ページで、ドロップダウン・リストから既存のリリース・バージョンを選択するか、「新規リリース・バージョンの作成」アイコンをクリックします。使用可能なビュー・オブジェクトの中からいずれかを選択し、ビュー・インスタンスとして追加して、RESTリソースを作成します。「次へ」をクリックします。
8. 必要に応じて、リソース・ペイロードで非表示にする属性を指定し、「属性の設定」ページでリソース・ペイロードを構成することもできます。「次へ」をクリックします。
9. 「サマリー」ページで、ウィザードによってRESTリソースを使用して作成されるビジネス・コンポーネントのリストを確認し、「終了」をクリックします。
10. アプリケーション・モジュールの概要エディタを使用して、追加のADF RESTリソースを作成できます。詳細は、「ビュー・オブジェクト・インスタンスからのADF RESTリソースの作成方法」を参照してください。

ビュー・オブジェクト・インスタンスからのADF RESTリソースの作成方法

ビュー・オブジェクト・インスタンスは、Fusion Webアプリケーションで操作するビジネス・オブジェクトです。ADFアプリケーション・モジュールは、それが定義するデータ・モデルでこれらのビジネス・オブジェクトを公開して、サービス・クライアントが表示および操作できるデータを指定します。モデル・プロジェクトを作成した後、必要に応じて、ADF REST用のアプリケーション・テンプレートを使用し、アプリケーション・モジュールの概要エディタを使用して、追加のADF RESTリソースを作成できます。この場合、アプリケーション・モジュールで定義される任意のビュー・オブジェクト・インスタンスに、ADF RESTリソースが定義されます。

ADF RESTリソースの追加は、アプリケーション・モジュールの概要エディタの「Webサービス」ページに表示されるオプションです。図16-2に、AppModuleアプリケーション・モジュールのビュー・オブジェクト・インスタンスに作成されているRESTリソースがエディタでどのように表示されるかを示します。エディタでは、アプリケーション・モジュールのRESTリソースは割り当てられたリリース固有のバージョン名(この例では、11.0、11.1および11.2)ごとに編成されていることに注意してください。

図16-2 アプリケーション・モジュールに定義されているADF RESTリソース

「図16-2 アプリケーション・モジュールに定義されているADF RESTリソース」の説明

ノート:

ADF RESTリソースを作成する場合は、JDeveloperによってリソースのバージョン・リリース名を指定するように求められます。バージョンは、複数のリリース間でADFモデル・プロジェクトに追加するリソースの現在および後続のバージョンの管理に役立つ英数字識別子です。

ビュー・オブジェクト・インスタンスを選択し、RESTリソースに名前を付けてバージョンを選択すると、RESTリソースの概要エディタでリソースが開きます。概要エディタを使用して、ビュー・オブジェクト・アクセッサ、使用可能な操作をRESTful Webサービスのペイロード・オブジェクトおよびアクションとして公開することによって、RESTリソース表現を編集します。JDeveloperでは、RESTリソース定義ファイルは、割り当てられたリリース・バージョン名によって編成された、ADFアプリケーション・モジュールのサブパッケージとして保存されます。

RESTリソースのカスタマイズの詳細は、「ADF RESTリソース定義の編集方法」を参照してください。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、Webサービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールの作成方法」の説明に従い、RESTリソースで公開するビュー・オブジェクト・インスタンスを含むアプリケーション・モジュールのデータ・モデルを作成します。

• adf-config.xmlファイルでリリース・バージョン識別子を作成し、作成するADF RESTリソースを特定のバージョンに関連付けます。「ADF RESTリソースのバージョニング」の説明に従い、ADFモデル・プロジェクトに追加するADF RESTリソースの現在および後続のバージョンの管理に役立つように、各RESTリソースをリリース・バージョンに関連付ける必要があります。

ADF RESTリソースを作成するには:

1. 「アプリケーション」ウィンドウで、ADF RESTリソースを作成するビュー・インスタンスを含むアプリケーション・モジュールをダブルクリックします。

2. 概要エディタで、「Webサービス」ナビゲーション・タブをクリックして「REST」タブをクリックし、「RESTサービスのサポートの有効化」追加アイコンをクリックします。

   最初のRESTリソースを作成するとき、JDeveloperによって、ADF RESTサーブレットを登録する個別のRESTful Webサービス・プロジェクトも生成されます。

3. 「RESTリソースの作成」ダイアログで、RESTful Webサービスで公開するルート・ビュー・インスタンスを選択します。

   ダイアログに、アプリケーション・モジュールのデータ・モデルで定義されたビュー・インスタンスが表示されます。マスター/ディテール階層のルート・ビュー・インスタンスのみ選択できます。

4. RESTリソース・コレクションの「リソース名」を入力し、ドロップダウン・リストからリリース・バージョンを選択して「OK」をクリックします。

   リソース名は、サービス・クライアントがビュー・インスタンスとの対話に使用する識別子です。たとえば、次の図に示すように、DeptView1ビュー・インスタンスに基づくコレクションに名前を付ける場合、完全なコレクション名を示すために名前にDepartmentsを入力できます。ネーミングの詳細は、「ADF RESTリソースのネーミングに関する必知事項」を参照してください。

   リリース・バージョンは、JDeveloperでリソースの作成を管理するためにadf-config.xmlファイル内に作成する必要がある識別子です。「ADF RESTリソースのバージョニング」で説明するように、バージョンは、サービス・クライアントが特定のRESTリソースの操作を起動するために使用するURLの一部となります。

   図16-3 ADF RESTリソースのリリース・バージョンへの割当て

   
   「図16-3 ADF RESTリソースのリリース・バージョンへの割当て」の説明

5. RESTリソースの概要エディタで、次のいずれかのタスクを実行することによって、リソースとその構造の編集に進むことができます。

   1. ビュー・リンク・アクセッサで定義された子リソースを追加および削除します。詳細は、「ADF RESTリソース定義の編集方法」を参照してください。

   2. 同じ基礎となるビュー・インスタンスで定義されたリソースを追加および削除します。詳細は、「同じビュー・インスタンスに基づくリソースを追加および削除する方法」を参照してください。

   3. 属性を追加および削除します。詳細は、「ADF RESTリソースの属性を非表示にしたり公開したりする方法」を参照してください。

   4. HTTPメソッド、正規のリンク、行検索フィルタ、サブタイプ・ビューの慣用名で定義された標準操作へのアクセスを変更します。詳細は、「ADF RESTリソース表現およびメソッドのカスタマイズ」を参照してください。

6. 「ファイル」、「すべて保存」の順にクリックして、このリソースの選択を保存します。

   「ADFビジネス・コンポーネント・プロジェクトのRESTリソースを作成する場合の処理」で説明するように、JDeveloperでは、概要エディタで行われるRESTリソース選択をリソースのリソース定義ファイルに保存します。

ADFビジネス・コンポーネント・プロジェクトのRESTリソースを作成する場合の処理

JDeveloperによってRESTリソースが生成され、図16-4に示すように、モデル・プロジェクトで編成された「アプリケーション」ウィンドウで、これらのリソースがバージョン・リリース名ごとに表示されます。

また、JDeveloperによって、ADF RESTサーブレットを登録する個別のRESTful Webサービス・プロジェクト(RESTWebService)も生成されます。図16-4に、JDeveloperによって生成されるweb.xmlファイルを示します。このプロジェクトを使用してRESTful Webサービスを実行およびデプロイします。

モデル・プロジェクトに含まれているResourceRegistry.rpxファイルでは、RESTful Webサービスとして公開されるRESTリソースのリストを指定するために、メタデータ注釈を使用しています。

adf-config.xmlファイルは、バージョン・リリース名を作成すると更新されます。このファイルは、「アプリケーション」ウィンドウの「アプリケーション・リソース」パネルで、「ディスクリプタ」および「ADF META-INF」ノードの下に表示されます。ADFビジネス・コンポーネントを初めて作成すると、同じフォルダにconnections.xmlファイルが作成されます。

図16-4 アプリケーション・モジュール・ノードの下に表示されるRESTリソース

ADF RESTリソース定義の編集方法

ADFモデル・プロジェクトにADF RESTリソース定義を追加すると、アプリケーション・モジュールの概要エディタのRESTセクションに、作成したリソースの名前が表示されます。リスト内のリソース名をクリックすることによって、個別のエディタでRESTリソース定義を開くことができます(図16-2を参照)。

RESTリソースの概要エディタに、リソースの構造を編集するためのオプションが表示されます。RESTful Webサービスの観点から、RESTリソース構造によって実行時にRESTコールによって起動される使用可能なデータが決定されます。

設計時に、リソースの基礎となるビュー・オブジェクト階層から、公開する必要があるリソースのみを選択するようにRESTリソース定義を編集できます。RESTリソースを初めて作成するときには、アプリケーション・モジュールのデータ・モデルによって公開される、リソースの基礎となるビュー・オブジェクトを選択する必要があります。この元のビュー・オブジェクトの選択によりRESTリソースのルート・リソースが定義されます。オプションで、追加の子ビュー・オブジェクトを公開できます(存在する場合)。

たとえば、図16-5に示すRESTリソース・エディタの左側には、リソースDepartmentsのデフォルトの構造が表示されています。リソース構造はルート・リソースを表すルート・ノードを持つツリーとして表示されます(この場合はDepartmentsView1)。ツリーのリーフ・ノードは子リソースを表します。この例では、Departmentsリソースは、ルート・リソースDepartmentsView1および様々な子リソース(EmployeesおよびJobHistoryなど)で構成されています。DepartmentsView1、EmployeesおよびJobHistoryのリソースはデータ・モデルのビュー・インスタンスとして関連付けられているため、階層に表示されます。リーフ・ノードの横のチェックボックスを使用して、リソース構造に対して子リソースを追加および削除できます。

図16-5 リソース構造が表示されている概要エディタ

ノート:

RESTリソース・エディタの右側に、「構造」ツリーで行うノード選択に対応する使用可能なオプションが表示されます。

表16-1に、リソース構造ツリーのノードの概要を示します。

表16-1 リソース構造ツリーのノード

ノード	説明	編集オプション
ルート・リソース・ノード:	ルート・リソースの選択の基礎となるビュー・オブジェクト・インスタンスを表します。	ルート・リソースの基礎となるビュー・オブジェクト・インスタンスを変更または削除することはできません。 このノードを選択すると、ルート・リソースでオプションを選択できます。これらのオプションの詳細は、「ADF RESTリソース表現およびメソッドのカスタマイズ」を参照してください。
子リソース・ノード:	ルート・リソースの選択の基礎となるビュー・オブジェクト・インスタンスに対して定義されている、マスター/ディテール関係を定義するためにデータ・モデルで使用されているビュー・リンク・アクセッサを表します。 ノート: 子ノードは、ルート・リソースのビュー・オブジェクト・インスタンスがマスター/ディテール関係に含まれていない場合は表示されません。	子リソースはデフォルトでは無効です。リソース表現で子リソースを公開するには、チェックボックスを選択します。リソース表現から子リソースを削除するには、チェックボックスの選択を解除します。 子リソース・ノードを選択すると、子リソースでオプションを選択できます。これらのオプションの詳細は、「ADF RESTリソース表現およびメソッドのカスタマイズ」を参照してください。

始める前に:

ADF RESTによって、アプリケーション・モジュールがどのようにサポートされ、Webサービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。

ADF RESTリソース構造を編集するには:

1. 「アプリケーション」ウィンドウで、編集するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. 概要エディタで、必要な選択を行います。

   [F1]キーを押すと、概要エディタのJDeveloperヘルプ・センター・トピックが表示されます。

3. 「ファイル」、「すべて保存」の順に選択して、このリソースでの変更を保存します。

   「ADFビジネス・コンポーネント・プロジェクトのRESTリソースを作成する場合の処理」で説明するように、JDeveloperでは、リソースのリソース定義ファイルに変更が保存されます。

ADF RESTリソースでの子リソースの公開方法

アプリケーション・モジュールのデータ・モデルで1つ以上の階層のマスター/ディテール関係を指定する場合は、ADF RESTリソースで子リソースを公開できます。データ・モデルの各マスター/ディテール関係に対して、ADFビジネス・コンポーネント・モデル・プロジェクトでは、関連する親と子のビュー・オブジェクトを指定するビュー・リンク・アクセッサを定義する必要があり、これにより、親、つまりマスター・ビュー・オブジェクト・インスタンス内に、子、つまりディテール・ビュー・オブジェクト・インスタンスをネストします。

実行時に、ネストされたビュー・インスタンスを公開するRESTリソースでは、1回のラウンドトリップで、マスターおよびディテールのコレクションを戻すことをサポートします。このため、マスター/ディテール・データの操作が必要なサービス・クライアントについては、設計時に子リソースを公開することが役立ちます。

JDeveloperのRESTリソースの概要エディタでは、マスター/ディテール関係が、ルート・リソースのリーフ・ノードとして子リソースが表示される、リソース構造ツリーとして表示されます。たとえば、図16-6は、概要エディタでの、次のネストされたリソース構造を持つDepartmentsリソースを示しています。

• DepartmentsView1は、マスター・ビュー・インスタンスとして、ルート・リソースの基礎となります。

• EmployeesはDepartmentsView1の下にネストされたディテール・ビュー・インスタンスであり、ツリー・ノードのチェックボックスが選択され、Departmentsリソースで子リソースが公開されていることを示します。

• JobHistoryは、EmployeesViewの下にネストされた別のディテール・ビュー・インスタンスであり、ツリー・ノードのチェックボックスが選択され、Departmentsリソースで子リソースが公開されていることを示します。

デフォルトでは、選択された基礎となるビュー・インスタンスに基づき、JDeveloperによってRESTリソースが作成されますが、子リソースは含められません。リソース構造ツリーで、デフォルトでは、子リソースは選択されていない状態で表示され、これらのリソースが公開されていないことを示します。このチェックボックスを選択または選択解除することによって、子リソースを公開したり非表示にしたりすることができます。

図16-6 概要エディタで有効な子リソース

「図16-6 概要エディタで有効な子リソース」の説明

ノート:

子リソースはデフォルトでは公開されないため、リソースでこれらを公開するには、概要エディタで選択する必要があります。

始める前に:

ADF RESTがアプリケーション・モジュールをどのようにサポートし、サービス・クライアントのデータ行アクセスやサービス操作の実行をどのように有効化するかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。

ネストされたリソースを公開するには:

1. 「アプリケーション」ウィンドウで、編集するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. RESTリソースの概要エディタで、「構造」ツリーを展開し、ルート・リソースの子リソースのチェックボックスを選択します。

   「構造」ツリーで、デフォルトでは、子リソース・ノードは選択されていない状態で表示され、ネストされたリソースがリソース内で公開されていないことを示します。

   データ・モデルで、ルート・リソースの基礎となるビュー・インスタンスに対してマスター/ディテール階層が定義されていない場合は、「構造」ツリーに子リソース・ノードは表示されません。「構造」ノードの詳細は、表16-1を参照してください。

3. 「構造」ツリーで別の子リソースのチェックボックスを選択すると、そのリソースで、そのネストされたリソースが有効になります。

子リソースのデータベース問合せの最適化に関する必知事項

多対1または1対1の子リソースがネストされたオブジェクトとしてレンダリングされるRESTリクエストでは、リソース・アイテムの数によって、データベース問合せの数が非常に多くなる可能性があります。たとえば、Employeeオブジェクトに対してレンダリングされるDepartment子リソースでは、従業員ごとにデータベース・ラウンドトリップが発生します。ただし、ネストされたオブジェクトのRESTリクエストが実行された場合に、ADF RESTフレームワークが次の追加条件下で子の主キーに関連する多対1または1対1の子関係を検出すると、ビュー・オブジェクトのエンティティ・キャッシュ内の行を検索することによって、子リソースの参照が最適化されます。これらの条件が存在しない場合、行フェッチのデータベース問合せが実行されます。

主キー参照を使用して、一方向ビュー・リンクのフェッチの実行時間を向上させるには、ネストされたエンティティ・ベースのビュー・オブジェクトが次の条件を満たしている必要があります。

• ビュー・オブジェクトに子ビュー・オブジェクトへのエンティティ参照があり、子リソースによって公開されている属性が含まれていること。たとえば、従業員の部門名やマネージャ名などです。

• ビュー・リンクがアソシエーションに基づいていること。

• 反対側のアソシエーション属性が主キーであること。

• アソシエーションにカスタムWHERE句がないこと。

• 反対側のビュー・オブジェクトに、カスタムWHERE句やデータベースのみの適用済ビュー基準がないこと。

同じビュー・インスタンスに基づくリソースを追加および削除する方法

JDeveloperで、RESTリソースの概要エディタを使用して、同じビュー・インスタンスに対して複数のリソースを定義できます。1つのリソース定義がサービス・クライアントのすべてのユースケースをサポートしていない場合は、リソースを追加できます。リソースを追加した後で、目的のユースケースをサポートするために、操作、属性のリストおよびリソース構造の他のアイテムを変更できます。定義する各リソースは、サービス・クライアントに対して一意のリソース・コレクションを表すため、リソース名がその違いを反映している必要があります。

RESTリソースの概要エディタでは、「リソース」ドロップダウンに、追加するリソースのリストが表示されます。たとえば、図16-7では、同じ基礎となるビュー・オブジェクトEmployeesViewについて、概要エディタに、EmployeesリソースおよびEmployeesAllAttrsリソースが表示されています。

図16-7 RESTリソース定義で複数のリソースをサポートするリソース・リスト

「図16-7 RESTリソース定義で複数のリソースをサポートするリソース・リスト」の説明

ノート:

JDeveloperでは、RESTリソースの概要エディタで追加されているリソース定義を削除できます。ただし、空の定義ファイルが「アプリケーション」ウィンドウに表示されます。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、リソースを追加または削除するRESTリソースを作成します。

概要エディタでリソースを追加および削除するには:

1. 「アプリケーション」ウィンドウで、リソースを追加または削除するADF RESTリソースが定義されているリソース定義ファイルをダブルクリックします。

2. RESTリソースの概要エディタで、「リソース」ドロップダウンからリソースを選択し、「リソースの削除」をクリックして、ビュー・オブジェクトに対してすでに定義されているリソースを削除します。

   「リソースの削除」を使用してルート・リソース定義を削除するとリソースは削除されますが、空の定義ファイルが「アプリケーション」ウィンドウに表示されます。

3. RESTリソースの概要エディタで、ビュー・オブジェクトに対して作成するリソースを追加するには、「リソースの追加」をクリックします。

4. 「ビュー・オブジェクト」ダイアログの「リソースの追加」で、選択したルート・ビュー・インスタンスに対して追加するRESTリソース・コレクションの「リソース名」を入力し、「OK」をクリックします。

5. RESTリソースの概要エディタで、「リソース」ドロップダウンから新規リソースを選択し、そのリソース定義を編集します。

   1. ビュー・リンク・アクセッサで定義された子リソースを追加および削除します。詳細は、「ADF RESTリソース定義の編集方法」を参照してください。

   2. 属性を追加および削除します。詳細は、「ADF RESTリソースの属性を非表示にしたり公開したりする方法」を参照してください。

   3. HTTPメソッド、正規のリンク、行検索フィルタ、サブタイプ・ビューの慣用名で定義された標準操作へのアクセスを変更します。詳細は、「ADF RESTリソース表現およびメソッドのカスタマイズ」を参照してください。

カタログ記述からリソースを非表示にする方法

次のコード例に示すように、リソース定義のServiceConfigurationタグ内のVisibility属性を設定することで、最上位レベルのリソースをADF RESTカタログ記述から非表示にできます。

<tree..>
  <ServiceConfiguration Visibility="unlisted"/> 
   ...
</tree>

Visibility属性をunlistedまたはpublicに設定できます。include問合せパラメータを使用して、特定の可視性のリソースの説明を含めることができます。詳細は、「リソースの可視性の宣言に基づいたカタログ記述の取得」を参照してください。

ADF RESTリソースの名前を変更する方法

ADF RESTリソースの開発中、RESTリソースの概要エディタを使用して、リソース定義ファイルでリソースの名前を変更できます。サービス・クライアントでは、必要なRESTリソース・コレクションとの対話にリソース名を使用するため、サービスを本番環境にデプロイする前に、ADF RESTリソースの名前を確定することが重要です。

デプロイ後にADF RESTリソースの名前を変更する必要がある場合は、「ADF RESTリソースのバージョニング方法」で説明するように、リソースの完全な新規バージョンを作成することで、このことを最適に処理できます。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、RESTリソースを作成します。

本番デプロイメントの前にリソースの名前を変更するには:

1. 「アプリケーション」ウィンドウで、名前を変更するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. RESTリソースの概要エディタで、「リソース」ドロップダウンから対象のリソースを選択します。

   リソース定義ファイルで追加のリソースを作成していない場合は、基礎となるビュー・オブジェクトに対して作成された元のリソースがリストに表示されます。

3. 概要エディタの「表現」タブをクリックし、「リソース名」フィールドに新しい名前を入力します。

ADF RESTリソースのネーミングに関する必知事項

RESTリソース名は、サービス・クライアントが、公開されているリソース・コレクションを識別して対話する手段です。通常、RESTリソース名で、利用するクライアントがアクセスするビュー・オブジェクトを識別します。そのため、RESTリソース名は動詞ではなく名詞です。

ADF RESTリソースの属性を非表示にしたり公開したりする方法

JDeveloperで、RESTリソースの概要エディタを使用して、同じビュー・インスタンスに対して複数のリソースを定義できます。1つのリソース定義がサービス・クライアントのすべてのユースケースをサポートしていない場合は、リソースを追加できます。リソースを追加した後で、目的のユースケースをサポートするために、必要に応じて、公開されている属性のリストおよびリソース構造の他のアイテムを変更できます。

RESTリソースの概要エディタでは、「属性」タブに、公開されている属性のリストが表示されます。リストは、ルート・リソースの基礎となるビュー・オブジェクトで定義した、RESTサービス形状の選択によって移入されます。たとえば、図16-8は、EmployeesViewビュー・オブジェクトに対して2つの属性以外をすべて公開するサービス形状定義EmployeesView_ForHRを示しています。

図16-8 RESTサービス形状定義の選択によって公開される属性

「図16-8 RESTサービス形状定義の選択によって公開される属性」の説明

ノート:

公開されている属性のリストはRESTリソースの概要エディタで直接変更しません。かわりに、基礎となるビュー・オブジェクトでサービス形状定義を作成し、対象の「REST形状」定義を現在の「リソース」ドロップダウン選択に適用する必要があります。

サービス・クライアントのユースケースをサポートするには、各ビュー・オブジェクトに対して必要な数のサービス形状定義を定義できます。「アプリケーション」ウィンドウでは、ビュー・オブジェクト・ノードの下のpersdefフォルダに、そのビュー・オブジェクトに対して作成したサービス形状定義が表示されます。たとえば、図16-9では、EmployeesViewビュー・オブジェクトの下に2つのサービス形状定義ファイルEmployeesView_forHR.xmlおよびEmployeesView_ForBenefits.xmlが表示されています。

図16-9 「アプリケーション」ウィンドウでのRESTサービス形状定義ファイル

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、RESTリソースを作成します。

RESTサービス形状定義をRESTリソースに適用するには:

1. 「アプリケーション」ウィンドウで、編集するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. RESTリソースの概要エディタで、「ビュー・オブジェクト」リンクをクリックします。
3. ビュー・オブジェクトの概要エディタで、サービス形状ナビゲーション・タブをクリックします。
4. 「サービス形成」ページで、サービス形成オブジェクトの作成ボタンをクリックし、「サービス形状の作成」ダイアログで、サービス形成定義を一意に識別する接尾辞名を入力します。

   入力する接尾辞はサービス形状定義ファイルの名前を形成します。たとえば、接尾辞ForHRはビュー・オブジェクトEmployeesViewに追加され、図16-10に示すようにサービス形状定義名EmployeesView_ForHRを形成します。

   図16-10 使用可能な属性を定義するビュー・オブジェクトのサービス形状定義

   
   「図16-10 使用可能な属性を定義するビュー・オブジェクトのサービス形状定義」の説明
5. 「サービス形成」ページで、シャトル・ボタンを使用して「非表示」および「選択されたもの」の属性のリストを変更し、ビュー・オブジェクト定義を保存します。

   RESTリソースの概要エディタでサービス形状を変更すると、JDeveloperによりビュー・オブジェクトのサービス形状定義ファイルが更新されます。サービス形状を参照するADF RESTリソースのリソース構造も更新されます。

6. RESTリソースの概要エディタで、「リソース」ドロップダウンから対象のリソースを選択します。
7. 概要エディタの「属性」タブをクリックし、公開する属性のリストを定義する「サービス形成オブジェクト」を選択します。

ADF REST属性のヒントに関する必知事項

JDeveloperでは、概要エディタを使用してADF REST属性のヒントを設定できます。

属性のヒントを設定すると、RESTサービスの記述ペイロードに影響します。これらは、jsonペイロードに属性プロパティとして表示されます。

図16-11 UIヒント・エディタ

図16-11に示したように、ビュー・オブジェクトの概要エディタでは、属性のUIヒントを設定できます。Form TypeプロパティをSummaryに設定すると、includeInCompactView=trueヒントが属性上に表示されます。属性にFrom Typeヒントが設定されていると、その属性を圧縮ビューに含めるよう、メタデータ駆動UIにヒントとして提案されます。

ADF RESTレスポンス・ペイロード・フィールドの制御方法

GETリクエストのレスポンス・ペイロードで返されるフィールドは、?fields URLパラメータを使用することで制限されます。?fields URLパラメータを指定しない場合、レスポンスのサイズが大きくなることがあります。属性のForm TypeヒントをDetailまたはSummaryのいずれかに設定することで、レスポンス・ペイロードで返されるフィールドを制御できます。デフォルト値はDetailです。

属性のForm TypeヒントをSummaryに設定すると、includeInCompactView=trueヒントが属性上に表示されます。「ADF REST属性のヒントに関する必知事項」を参照してください。

prefer HTTPヘッダーを使用すると、レスポンス・ペイロードのすべてのフィールドを戻すか、次のいずれかのreturnオプションを使用して最も一般的なフィールドのみを戻すことができます。

• minimal: 成功したリクエストに最小限のレスポンスのみを返します。このオプションでは、includeInCompactView=trueが設定されているペイロード内の属性のみが返されます。minimalレスポンスは、サーバーの判断によるものです。
• representation: レスポンス内のリソースの現在の状態を、成功したリクエストに返します。このオプションでは、設定されている属性に関係なく、すべてのフィールドが返されます。return=representationが設定されているPOSTまたはPATCHリクエストは、すべてのフィールドを返します。

Content-Type: application/vnd.oracle.adf.resourceitem+json
Prefer: return=representation/minimal

リソースで形状が定義される場合のレスポンス・ペイロードに関する必知事項

RESTリソースに対してコンパクトな形状を定義し、URLで?fieldsを指定しない場合、Form TypeヒントがSummaryに設定されている属性のみがペイロードで返されます。

たとえば、ルートまたは子リソースでRESTサービス形状を定義する場合、?fieldsパラメータを指定しないと、RESTサービス形状のForm Type=summaryをサポートするフィールドのみが返されます。

リソースにEnableCompactview=view構成プロパティが設定されている場合のみ、RESTリソースに対するレスポンス・ペイロードは、リソース・レベルで制御されます。

<tree IterBinding="EmpIter" id="employees" AccessorFolder="Always"> 
    <ServiceConfiguration EnableCompactView="true"/>
<nodeDefinition .../>
</tree>

RESTクライアントは、フィールド・パラメータで+および- 演算子を使用することで、デフォルトのフィールド・セットを展開または縮小できます。

次の例では、デフォルトの形状のすべてのフィールドに加えて、レスポンスでPhoneNumberフィールドを返します。

/employees?fields=+PhoneNumber

次の例では、Eメール・フィールドを除く、デフォルトの形状のすべてのフィールドをレスポンスで返します。

/employees?fields=-Email

Prefer REST HTTPヘッダーを使用して、すべてのフィールド・セットとデフォルト・セットを切り替えます。「ADF RESTレスポンス・ペイロード・フィールドの制御方法」を参照してください。

ADF RESTリソース構造の変更に関する必知事項

図16-12に示すように、リソースを作成してバージョン識別子を割り当てると、RESTリソースの概要エディタの右上隅にバージョンが表示され、編集中のバージョンの識別に役立ちます。

図16-12 バージョンが表示されているRESTリソース・エディタ

開発サイクル中は、リソースをバージョニングする必要なく、ADF RESTリソースに変更を加えることができます。ただし、RESTful Webサービスをデプロイした後、ADF RESTリソースにアクセスするサービス・クライアントでそれらのユースケースが満たされることは、リソース・コレクションの安定性に依存します。

時間の経過に伴い、ユースケースが変化したり、RESTリソースの基礎となるビュー・オブジェクトが変化したりすることによって、すでにデプロイされているリソースのリソース構造を変更することが必要になる場合があります。このとき、既存のADF RESTリソースに対する変更に、デプロイされているRESTサービスとの後方互換性がない場合があり、新しいバージョン識別子およびそのバージョンのADF RESTリソースを作成することが必要になる場合があります。RESTリソースをバージョニングするタイミングの詳細は、「ADF RESTリソースのバージョニングに関する必知事項」を参照してください。

JDeveloperでは、ADF META-INFフォルダにあるadf-config.xmlファイルの概要エディタの「リリース・バージョン」ページでリソースのバージョンを管理できます。ADF RESTリソースの新規バージョンの作成方法の詳細は、「ADF RESTリソースのバージョニング」を参照してください。

ADF RESTリソースおよびLOB属性に関する必知事項

BLOBまたはCLOBタイプ属性を公開するリソースには、実行時にストリーミング・メディアとしてアクセスできます。デフォルトでは、ビュー・オブジェクト属性は、一般的なコンテンツ・タイプapplication/octet-streamを使用してADF RESTランタイムによって処理されます。特定のコンテンツ・タイプをサポートする場合は、LOBタイプ属性のカスタム・プロパティとして特別なプロパティcontentTypeを構成できます。たとえば、PNGイメージ・ファイルを使用する場合は、設計時に次のコンテンツ・タイプを構成できます。

• カスタム・プロパティ: contentType

• 値: image/png

図16-13に示すように、カスタム・プロパティcontentTypeは、ビュー・オブジェクトの概要エディタでPicture属性のビュー・オブジェクト定義に追加されています。

図16-13 LOB属性に対して構成されているカスタム・コンテンツ・タイプ

「図16-13 LOB属性に対して構成されているカスタム・コンテンツ・タイプ」の説明

図16-14に示したように、ビュー・オブジェクトの概要エディタでは、属性のUIヒントを設定できます。Form TypeヒントをSummaryに設定すると、includeInCompactView=trueヒントが属性上に表示されます。属性にForm Typeヒントが設定されていると、属性をコンパクト・ビューに含めるよう、メタデータ駆動UIにヒントとして提案されます。

図16-14 UIヒント・エディタ

「図16-14 UIヒント・エディタ」の説明

ADF RESTリソースのLOVアクセッサに関する必知事項

値リスト(LOV)属性は、そのデータソースを別のビュー・オブジェクトに依存するビュー・オブジェクトの属性です。通常、データソース・ビュー・オブジェクトでは、LOV有効属性に対して使用可能な値の固定リストを指定します。ビュー・オブジェクトでLOV有効属性を明示的に定義すると、ADF RESTランタイムがADF RESTリソースでLOV子リソースとして自動的に公開するLOVビュー・アクセッサが、ADFビジネス・コンポーネントによって定義されます。このため、実行時にリソースでLOV有効属性が検出されると、サービス・クライアントによってLOVビュー・アクセッサが起動され、LOV有効属性のデータソースが取得されて、エンド・ユーザーに選択項目が表示される場合があります。

LOV属性は、エンティティ・オブジェクト属性を参照するLOVビュー・アクセッサに依存しないでください。ビュー・オブジェクト属性に基づくLOVビュー・アクセッサのみがRESTサービスに表示されます。実行時に、エンティティ・オブジェクト属性を参照するLOVビュー・アクセッサによって定義されたLOV属性がリソースに含まれる場合、ADF RESTは、エンティティ・オブジェクトのレベルで定義された属性およびリンクに関して何も認識せず、HTTPエラー・コード500を返します。

ノート:

デフォルトでは、LOVアクセッサ・リソースはリソースで公開され、リソース概要エディタの構造ツリーには表示されません。LOV有効属性の作成の詳細は、「ビュー・オブジェクト属性の値リスト(LOV)での作業」を参照してください。

ADF RESTリソースの必須属性に関する必知事項

必須属性は、問合せで指定する必要があり、指定されない場合、実行時に検証エラーをトリガーするビュー・オブジェクトの属性です。ADF RESTリソースの記述では、プロパティ“mandatory”: trueまたは“mandatory”:falseを使用して、属性が必須かどうかを特定します。リソースの記述の必須プロパティは、設計時に指定されたビュー・オブジェクト属性メタデータに基づきます。属性が必須として設定され、設定が実行時に決定される場合、Groovy式を使用してtrueまたはfalseに評価すると、記述は属性プロパティ・リストで“isMandatoryConditional”:trueを返します。

リソース・コレクション問合せ操作の大/小文字区別に関する必知事項

ADF RESTフレームワークでは、q問合せパラメータを使用して検索結果をフィルタするときに、大/小文字を区別しない検索がサポートされます。大/小文字を区別しない検索を実行する場合は、adf-config.xmlファイルのrestV1QueryCaseSensitiveという名前のフラグをfalseに設定できます。フラグのデフォルト値は、大/小文字を区別する検索を意味するtrueです。

ADF RESTリソース表現のカスタマイズ

JDeveloperでは、ADF RESTリソース定義を編集できます。HTTPアクションの有効化、行検索の公開、ツリーのノードに対する標準的なリソース・リンクの有効化、リソースのサブタイプ・ビュー・オブジェクトの公開、およびリソース・キャッシュ継続時間の構成を行うことができます。

ADF RESTリソースの概要エディタを使用して、ADF RESTリソース定義を編集します。たとえば、リソース構造ツリーで選択することによって、HTTPアクションを有効にし、行検索を公開し、ツリーの各ノードに対する正規のリソース・リンクを有効にできます。

ADFモデル・プロジェクトでRESTリソースに行うカスタマイズは、最終的に、実行時にこれらのリソースと対話するサービス・クライアントの機能に影響します。このため、この項では様々なデザインタイム・カスタマイズについて説明していますが、必要なADF RESTランタイム機能をサポートするサービス・クライアントのユースケースの要件を理解することが重要です。

ADF RESTランタイムの詳細は、「ADF RESTful Webサービスの消費」を参照してください。

ノート:

リソース属性に対して定義されたカスタム・プロパティは、記述に含まれます。ただし、名前がINTERNAL、internalまたは__ (二重のアンダースコア)で開始するカスタム・プロパティは記述から非表示になります。

ADF RESTリソースでの正規リソースの公開方法

ADF RESTリソース表現では、実行時のレスポンスで返される属性が、リソースの基礎となるビュー・オブジェクトによって問い合わされた属性に制限されます。そのため、設計時にビュー・オブジェクト問合せを定義する場合は、サービス・クライアントの特定のユースケースをサポートするために必要な属性のみを公開することが重要になります。ただし、サービス・クライアントが部分的なRESTリソース表現から同じデータの完全表現に移動できるようにするために、正規リソースへのリンクを構成できます。

通常、正規リソースは真のソースとみなされるため、特定のデータソースの完全表現を指定します。正規リソースの例は、managerインスタンスを記述するリソースへのリンクを持つemployeesリソースによって示すことができます。このシナリオ(マネージャ名のみが必要な一般的なユースケース)では、非正規のmanagerリソースに名前属性のみが含まれています。さらに、名前がマネージャの識別には十分でない場合は、非正規リソースがmanagerインスタンスのすべての属性(名前、ID、部門、入社日など)を公開する正規リソースにリンクする場合があります。したがって、正規リソースと非正規リソースは次のような状態で存在します。

• 非正規リソースと正規リソースは、同じデータソースの異なる表現を公開します。

• 非正規リソースはサービス・クライアントのユースケースのサポートに必要なデータソースの表現のみを公開するため、部分表現となります。

• 非正規リソースを定義するときには、その正規の完全表現へのリンクが含められます。

リソースの概要エディタで、リソース構造ツリーの各リソース・ノードに対して、ADFモデル・プロジェクトによって定義されている既存のRESTリソースから正規リソースを選択するか、アプリケーションのconnections.xmlファイルの既存のURL接続によって定義されている外部リソースを選択できます。

RESTリソースの概要エディタで選択できる内部正規リソースは、次の基準を満たす必要があります。

1. ADFモデル・プロジェクトでは、既存の部分的な表現リソースの基礎となる、同じデータソースにアクセスするビュー・オブジェクトを定義する必要があります。ビュー・オブジェクトはエンティティ・ベースまたは非エンティティ・ベースとなります。

2. ビュー・オブジェクトでは、非正規リソースによって問い合わされた使用可能な属性のスーパーセットを問い合わせる必要があります。

3. スーパーセットの表現ビュー・オブジェクトは、アプリケーション・モジュールのデータ・モデルでビュー・インスタンスとして指定する必要があります。

図16-15に、概要エディタのEmployeesViewルート・リソース・ノードの選択および「リソース」ドロップダウンの選択HREmployeesを示します(内部正規リソースEmployeesが有効化されています)。この場合、各基礎となるビュー・オブジェクトによって指定されるデータベース表は、HREmployeesとEmployeesリソースで同じになります。この例では、Employeesは正規リソースで、基礎となるビュー・オブジェクトのすべての属性が含まれる一方、HREmployeesリソースは同じビュー・オブジェクトに基づきますが、特定のユースケースのサポートに必要な属性のみを問い合わせます。

図16-15 概要エディタで有効な正規リソース

ノート:

リソース(resource_partial)が正規(resource_full)として別のリソースを選択できるのは、resource_fullにresource_partialが公開するすべての属性が含まれている場合のみです。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。

• RESTリソースの正規リンクで内部正規リソースが公開されるようにする場合は、データソース(非正規RESTリソースと同じデータソースである必要があります)から使用可能な属性のスーパーセットを問い合わせるビュー・オブジェクト定義を作成して、データ・モデルでそのビュー・オブジェクトを公開し、内部正規リソースのためのリソースを作成します。リソースの作成の詳細は、「ビュー・オブジェクト・インスタンスからのADF RESTリソースの作成方法」を参照してください。

• RESTリソースの正規リンクで外部正規リソースが公開されるようにする場合は、アプリケーション接続ファイル(connections.xml)でURL接続を作成します(JDeveloperのオンライン・ヘルプのURL接続の作成ダイアログに関するトピックを参照)。

正規リソース・リンクを公開するには:

1. 「アプリケーション」ウィンドウで、編集するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. RESTリソースの概要エディタで、「リソース」ドロップダウンから対象のリソースを選択し、「構造」ツリーを展開して、正規リソース・リンクを定義するノードを選択します。

   リソース・ツリーの各リソース・ノードに対して正規リンクを定義できます。「構造」ノードの詳細は、表16-1を参照してください。

3. 「構造」ツリーで選択したリソース・ノードの場合、概要エディタの「表現」タブをクリックし、「正規のリンク」を選択します。

   現在のリソース・アクセッサ・ノードの選択に対して正規リソースを公開しない場合は、「正規のリンク」を選択解除します。

4. 「正規のリンク」セクションで、正規リソースが「内部」か「外部」かを選択し、ドロップダウン・リストから対象のリソースを選択してリソースの正規バージョンを示します。

   内部リソースのドロップダウン・リストは、現在のリソースに追加したリソースによって移入されます。これらは、アプリケーション内部のリソースであり、現在のリソースと同じデータソースに基づく必要があります。

   外部リソースのドロップダウン・リストは、アプリケーションに対して定義し、アプリケーション接続ファイル(connections.xml)で登録したURL接続によって移入されます。

LOV属性を使用したADF RESTリソースの作成操作のサポート方法

値リスト(LOV)を要求するリソース操作にリスト移入の行コンテキストがなくても、それらの操作がADF RESTリソースでサポートされるようにするには、LOVリソースを作成する必要があります。たとえば、サービス・クライアントがRESTリソースでリソース・アイテムの作成操作を呼び出し、LOVリストに使用する行コンテキストがないとします。この場合、LOVリソースが子リソースとして存在していないため、作成しようとしているリソース・アイテムとは別にサービス・クライアントから実行時にアクセスする必要があります。

ノート:

サービス・クライアントが既存のリソース・アイテムにアクセスする場合は、LOV対応属性を持つリソースをサポートするための設計時変更は不要です。設計時にLOVリソースを作成する必要があるのは、サービス・クライアントが新しいリソース・アイテムを作成し、そのリソース・アイテムがLOV対応属性に基づく場合のみです。既存のリソース・アイテムの場合は、リソース・アイテムがリソース・コレクション内の行コンテキストを提供するため、ADF RESTランタイムが自動的にLOVリンクを子リソースとして生成します。LOV子リソースの詳細は、「ADF RESTリソースのLOVアクセッサに関する必知事項」を参照してください。

JDeveloperでは、ビュー・オブジェクトの概要エディタを使用して、「属性」ページで個々の属性のLOV定義を作成します。これと同じページを使用して静的LOVリソースを定義します。たとえば図16-16は、Employeesリソースの基礎となるビュー・オブジェクトの概要エディタに表示されているEmployeesViewビュー・オブジェクトとLOV対応属性JobIdを示しています。静的LOVリソースはそれがサポートとしている特定のADF RESTリソースによって特定され、この場合はv2 (Jobsリソースの内部バージョン識別子)です。静的LOVリソースの下にあるのが、ビュー・オブジェクトのLOV対応属性によって使用されるLOV定義です。

図16-16 静的LOVリソースがRESTリソースの作成操作をサポート

「図16-16 静的LOVリソースがRESTリソースの作成操作をサポート」の説明

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従って、ビュー・オブジェクトの属性のLOVを有効化します。

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従って、作成操作を公開するLOV対応属性を持つビュー・オブジェクトのRESTリソースを作成します。

注意:

ビュー・オブジェクトでLOVリソースを定義するときには、LOV対応属性のLOV定義で必要となる属性が、ビュー・オブジェクトのサービス形状定義によって非表示にされないようにしてください。必要なLOV属性は、LOVデータ・ソースにマップされる属性やLOV表示属性などです。サービス形状およびADF RESTリソースの詳細は、「ADF RESTリソースの属性を非表示にしたり公開したりする方法」を参照してください。

ADF RESTリソースに使用する静的LOVリソースを定義するには:

1. 「アプリケーション」ウィンドウで、編集するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. RESTリソースの概要エディタで、「ビュー・オブジェクト」リンクをクリックします。
3. ビュー・オブジェクトの概要エディタで、「属性」ナビゲーション・タブをクリックします。
4. 「属性」ページでLOVセクションを展開し、「LOVリソースを属性に作成」ボタンをクリックします。
5. LOVリソースの作成ダイアログで「リリース・バージョン」識別子を選択し、LOV対応属性を公開するADF RESTリソースの「リソース名」を選択して、リソース構造ツリーから定義リソースを選択します。

   「リソース名」リストのデータはモデル・プロジェクト内のADF RESTリソース定義によって移入されます。選択したRESTリソースのビュー・オブジェクト定義は、LOV属性データ・ソースを定義しているビュー・オブジェクトと同じである必要があります。たとえばEmployeesリソースを作成していて、EmployeesViewビュー・オブジェクトがLOV属性JobsIdを定義しているとします。LOVリソースの作成エディタで、図16-17のとおり、ADF RESTリソースJobsを選択し、Jobsリソースのリソース構造ツリーからルート・リソースJobsView1を選択します。

   図16-17 REST作成操作のための静的LOVリソースの作成

   
6. 「OK」をクリックし、LOVリソース定義を保存します。

ADF RESTリソースで行検索キーを有効化する方法

サービス・クライアントがリソースの主キー(ほとんどの場合は数値)を使用してリソースの問合せができないようにする場合は、ビジネス・コンポーネント開発者は、名前によって一意に識別できる値を持つビュー・オブジェクト属性に基づく行検索キーを指定する行検索を作成できます。この例の1つとして、電子メール属性の最初の文字による従業員の検索があります。

行検索がADF RESTリソースで名前が付けられているビュー・オブジェクトで明示的に定義されている場合は、ADF RESTリソースの概要エディタで、リソース・コレクションをフィルタ処理する行検索を有効にするオプションを使用できます。行検索はデフォルトでは有効化されていません。名前による行検索キーを選択し、これをリソース構造の現在のノード選択に適用する必要があります。

JDeveloperのADF RESTリソースの概要エディタでは、「Rowfinderキー」ドロップダウンに使用可能な行検索のリストが表示されます。リストは、リソース構造ツリーにおけるノード選択の基礎となるビュー・オブジェクト定義で定義されている行検索によって移入されます。たとえば、図16-18は、Employeesが行検索EmpByEmailFinderを含むビュー・インスタンスを定義するノードであるEmpByEmailFinder行検索キーを示しています。

図16-18 ADF RESTリソースのルートで有効な行検索キー

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。

• 「アプリケーション・モジュールの作成方法」の説明に従い、RESTリソースで公開するビュー・オブジェクト・インスタンスを含むアプリケーション・モジュールのデータ・モデルを作成します。

• 「行検索の使用」の説明に従い、RESTリソースで公開するビュー・インスタンスで行検索を作成します。

行検索フィルタを公開するには:

1. 「アプリケーション」ウィンドウで、編集するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. RESTリソースの概要エディタで、「リソース」ドロップダウンから対象のリソースを選択し、「構造」ツリーを展開して、行検索を公開するリソース・ノードを選択します。

   データ・モデルで、ルート・リソースの基礎となるビュー・インスタンスに対してマスター/ディテール階層が定義されていない場合は、「構造」ツリーにビュー・リンク・アクセッサ・ノードは表示されません。「構造」ノードの詳細は、表16-1を参照してください。

3. 概要エディタの「表現」タブをクリックし、「Rowfinderキー」で、現在の「構造」ツリー選択に対する行検索を選択します。

   「Rowfinderキー」ドロップダウンは、リソースで正規のリンクが有効化され、かつ正規リソース自体で行検索キーが有効化されている場合は、無効として表示されることがあります。「ADF RESTリソース・リクエストの行検索に関する必知事項」で説明するように、ADF RESTリソースについてエディタで行検索キー・フィールドが無効になり、部分リソースに行検索キーが自動的に反映されます。

4. オプションで、行検索選択で現在のノード選択を示す正規リソースがフィルタ処理されるようにする場合は、「正規のリンク」をクリックします。

   正規のリンクを有効にする場合は、正規リソースに対して内部または外部のソースを選択することも必要となります。

5. 「構造」ツリーで別のノードを選択して、別の行検索を公開します。

行検索のLOVリソースの構成に関する必知事項

サービス・クライアントがLOVリソースを使用してリソースを問合せできるようにする場合、ビジネス・コンポーネント開発者は、名前によって一意に識別できる検索値を持つビュー・オブジェクト属性に基づいて検索キーを指定する検索を作成できます。標準リソースとLOVリソース間のリンクは、リソースの記述を使用して構成されます。LOVリソースを使用するには、LOV定義があるリソースを構成する必要があります。ネストされたリソースは、ツリー構造に従った一部のカスケードLOVを表すために公開されます。

たとえば、LOV_CityおよびLOV_Stateという名前のStateおよびCityのLOVがあるとします。LOV_Cityは、Stateですでに選択されている値をフィルタ処理します。Citiesという名前のリソースがあり、その国のすべての都市(city)がStateでグループ化されているとします。LOV_Cityは、すでに選択されているState値でCitiesリソースをフィルタ処理する必要があります。このために、パラメータStateを指定できる値ByStateFinderを使用する検索でCitiesビュー・オブジェクトを定義する必要があります。LOV URLは/Cities?finder=ByStateFinder;stateVar={State}となり、StateはマスターLOVを持つアドレス・オブジェクトのState属性を指します。

次のビュー・オブジェクト定義は、cityおよびstateの例に対するLOVソースを提供するビュー・オブジェクトのメタデータを示しています。

<ViewAttribute
  Name="City"
  IsNotNull="true"
  PrecisionRule="true"
  EntityAttrName="CityName"
  EntityUsage="Address"
  AliasName="CITYNAME"
  LOVName="LOV_City">
  <Properties>
    <SchemaBasedProperties>
      <LOVResource name="Cities" finder="ByStateFinder"/>
    </SchemaBasedProperties>
  </Properties>
</ViewAttribute>
<ViewAttribute
  Name="State"
  IsNotNull="true"
  PrecisionRule="true"
  EntityAttrName="StateCode"
  EntityUsage="Address"
  AliasName="STATECODE"
  LOVName="LOV_State">
  <Properties>
    <SchemaBasedProperties>
      <LOVResource name="States"/>
    </SchemaBasedProperties>
  </Properties>
</ViewAttribute>

前述の例では、カスケードLOVは検索クラスを持つLOVによって処理されています。

カスタム・プロパティLOVResourceは、LOVリソースがそのデータに使用するソースを識別することに注意してください。プロパティ名LOVResourceは、ADF RESTフレームワーク・バージョン5以降に固有であり、パラメータ化された行検索URLの使用方法を区別して、LOVリスト・リストを前のフレームワーク・バージョンに関連付けられた使用方法(LOVリストURLが行検索を使用しない)から取得します。LOVソース属性のビュー・オブジェクト・メタデータは、プロパティ名ResourceLOVを使用して、フレームワーク・バージョン1から4を識別します。

これら2つの使用方法に関連付けられているリソースの記述も異なります。フレームワーク・バージョン5が有効になっている通常のビュー・オブジェクト・バック・リソースに関連付けられた静的LOVリソースと(LOVResourceとして識別された属性メタデータ・プロパティ)、フレームワーク・バージョン4が有効になっている同じリソースの記述(ResourceLOVとして識別された属性メタデータ・プロパティ)を比較します。

バージョン5が有効になっている記述を次に示します。LOVResourceは通常のリソース(Address)のlov要素セクションに追加され、childRefForCreateプロパティはitem - links要素セクションに表示されるURL名を識別します。

{
  "Resources" : {
    "Address" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
        }, {
          "name" : "City",
          "type" : "string",
          "updatable" : true,
          "mandatory" : true,
          "queryable" : true,
          "precision" : 32,
          "controlType" : "choice",
          "maxLength" : "32",
          "lov" : {
            "childRef" : "CityLOV",
            "childRefForCreate" : "CityLOVForCreate",
            "attributeMap": [ {
              "source" : "CityName",
              "target" : "City"
            }],
            "displayAttributes" : [ "CityName" ],
          }
        }, {
          "name" : "State",
          "type" : "string",
          "updatable" : true,
          "mandatory" : true,
          "queryable" : true,
          "precision" : 2,
          "controlType" : "choice",
          "maxLength" : "2",
          "lov" : {
            "childRef" : "StateLOV",
            "childRefForCreate" : "StateLOVForCreate",
            "attributeMap": [ {
              "source" : "StateCode",
              "target" : "State"
            }],
            "displayAttributes" : [ "StateCode" ],
          }
        }, {
      ...
      },
      "item" : {
        "links" : [ {
          ...
        }, {
          "rel": "lov",
          "href": "http://server/demo/rest/11.0/Address/{id}/lov/CityLOV",
          "name": "CityLOV",
          "kind": "collection"},
        }, {
          "rel" : "lov",
          "href" : "http://server/demo/rest/11.0/Cities?finder=ByStateFinder%3BstateVar%3D{State}",
          "name" : "CityLOVForCreate",
          "kind" : "collection"
        }, {
        }, {
          "rel": "lov",
          "href": "http://server/demo/rest/11.0/Address/{id}/lov/StateLOV",
          "name": "StateLOV",
          "kind": "collection"},
        }, {
          "rel" : "lov",
          "href" : "http://server/demo/rest/11.0/States",
          "name" : "StateLOVForCreate",
          "kind" : "collection"
        }, {
...

バージョン4が有効になっている記述を次に示します。ResourceLOVは通常のリソース(Address)のlov要素セクションに追加され、lovResourcePath配列はlinks要素セクションに表示されるURL名を識別します。

{
  "Resources" : {
    "Address" : {
      "discrColumnType" : false,
      "attributes" : [ {
       ...
        }, {
          "name" : "City",
          "type" : "string",
          "updatable" : true,
          "mandatory" : true,
          "queryable" : true,
          "precision" : 10,
          "controlType" : "choice",
          "maxLength" : "10",
          "lov" : {
            "childRef" : "CitiesLOV",
            "attributeMap" : [ {
              "source" : "CityName",
              "target" : "City"
            } ],
            "displayAttributes" : [ "CityName" ],
            "lovResourcePath" : [ {
                  "resource" : "Cities",
                  "filter" : "?finder=FilterByState%3BVStateName%3D{State}"
            } ]
          }
        }, {
      ...
      },
      "links" : [ {
        ...
          "rel" : "lov",
          "href" : "http://server/demo/rest/11.0/Cities",
          "name" : "Cities",
          "kind" : "collection"
        }, {
...

ADF RESTリソース・リクエストでの行検索に関する必知事項

実行時、行検索キーが有効化されているADF RESTリソースには、サービス・クライアントで行検索キー属性によってアクセスする必要があります。行検索は、行検索キー属性のみを使用して、行検索が有効なリソースについて、コレクションまたはインスタンスを戻すことをサポートします。このため、エンド・ユーザーに対してデータベースの主キー値の知識を要求することなく、サービス・クライアントがRESTリソースにアクセスできます。たとえば、Employeesリソース・コレクションの特定の従業員を取得する次の2つのGETリクエストを比較します。

行検索なし:

http://localhost:7101/RESTSample_App/rest/11.1/Employees/101

行検索あり:

http://localhost:7101/RESTSample_App/rest/11.1/Employees/NSMITH

行検索キーが定義されていない最初のURLでは、従業員のリソース・アイテムの特定に従業員のIDが必要です。2つ目のURLでは、リソース・パスに行検索キー値(従業員の電子メール・アドレス)を使用します。行検索キーが設計時にリソースで有効化されていると、サービス・クライアントは、ADF RESTランタイムによってリクエスト・ペイロード内に生成されたリンクを使用して、行検索キー値でリソースにアクセスできます。

オプションで、ADF RESTリソースで定義した正規リソースに行検索を適用できます。行検索キーを含む正規リソースが、行検索キーが有効化されているADF RESTリソースで定義されている場合は、両側が同じキー構造によって定義されている必要があります。キー属性は、同じ型で、同じ順序である必要があります。行検索キーを含む正規リソースを作成した後、正規のリンクを含む部分リソースを作成すると、ADF RESTリソースの概要エディタで行検索キー・フィールドが無効になり、部分リソースに行検索キーが自動的に反映されます。正規リソースの詳細は、「ADF RESTリソースでの正規リソースの公開方法」を参照してください。

ADF RESTリソースでサブタイプ・ビュー・オブジェクトを公開する方法

サブタイプ・ビュー・オブジェクトは、継承階層のベース・ビュー・オブジェクトを拡張するビュー・オブジェクトです。サブタイプ・ビュー・オブジェクトは、ベース・ビュー・オブジェクトから属性のそのリストを継承し、サブタイプに固有の独自の属性を提供します。このようなサブタイプ・ビュー・オブジェクトは多相ビュー・オブジェクトと呼ばれます。実行時、多相ビュー・オブジェクトによって、ベース・ビュー・オブジェクトの属性および定義サブタイプ・ビュー・オブジェクトの属性で構成されるサブタイプ・ビュー行が定義されます。

サブタイプ・ビュー行を問い合わせるには、サブタイプ・ビュー・オブジェクトで特定のタイプを判別する識別子属性を指定する必要があります。たとえば、識別子属性JobIdを含むEmployeesViewベース・ビュー・オブジェクトは、使用可能なジョブ(経理担当者、営業担当者など)に基づいてサブタイプ・ビュー行をインスタンス化でき、サブタイプ・ビュー行の属性は、指定されたジョブID値によって決定されます。たとえば、ジョブIDがSA_REPの営業担当者には、サブタイプ・ビュー行属性CommissionPctがありますが、他のジョブ・タイプのサブタイプ・ビュー行ではこの属性は省略されます。

ノードの基礎となるビュー・オブジェクトによって識別子属性が定義される場合は、RESTリソースの概要エディタで、構造ツリーの各ノードのサブタイプ・ビュー・オブジェクトを公開できます。たとえば、図16-7では、概要エディタでEmployeesリソースとEmployeesView2リソース・ノードが選択されています。基礎となるビュー・オブジェクトEmployeesViewは、識別子属性JobIdを定義し、サブタイプ・ビュー・オブジェクトSalesEmployeeViewは、サブタイプSA_REPを定義しています。エディタで、「識別子サブタイプを含める」を有効にし、「識別子名」を指定して識別子属性値を省略することによって、SalesEmployeesViewサブタイプ・ビュー・オブジェクトが公開されます。JobId識別子属性値を省略することにより、リクエストされた従業員のJobId値に基づくEmployeesのサービス・クライアント・リクエストで、確実にサブタイプ属性が返されます。

図16-19 RESTリソース定義での識別子属性の定義

「図16-19 RESTリソース定義での識別子属性の定義」の説明

ノート:

識別子属性は基礎となるビュー・オブジェクトで定義され、サブタイプ・ビュー行をサポートします。サブタイプ・ビュー・オブジェクトは設計時にADF RESTリソースとして公開されません。サブタイプ定義はアプリケーション・モジュールで、ADF RESTランタイムによって指定されます。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

ビュー・オブジェクトでサブタイプ・ビュー行がどのようにサポートされるかを理解しておくと役立つ場合があります。詳細は、「多相ビュー行関連の作業」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「多相ビュー行を持つビュー・オブジェクトの作成方法」の説明に従って、多相ビュー・オブジェクトを作成します。

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、リソースを追加または削除するRESTリソースを作成します。

リソース定義でサブタイプ・ビュー行を公開するには:

1. 「アプリケーション」ウィンドウで、編集するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. RESTリソースの概要エディタで、「リソース」ドロップダウンから対象のリソースを選択し、「構造」ツリーを展開して、サブタイプ・ビュー・オブジェクトを公開するリソース・ノードを選択します。

   データ・モデルで、ルート・リソースの基礎となるビュー・インスタンスに対してマスター/ディテール階層が定義されていない場合は、「構造」ツリーにビュー・リンク・アクセッサ・ノードは表示されません。「構造」ノードの詳細は、表16-1を参照してください。

3. 概要エディタの「表現」タブをクリックし、「識別子サブタイプを含める」を選択して、現在の「構造」ツリー選択でサブタイプ・ビュー行を有効にします。
4. 「識別子名」ドロップダウンからサブタイプ識別子属性を選択し、サブタイプ・ビュー・オブジェクトでサブタイプ識別子属性値が定義される場合は、対象のサブタイプ・ビュー行を定義する値を省略します。

   「識別子名」ドロップダウンは、基礎となるビュー・オブジェクトの識別子属性定義によって移入されます。たとえば、EmployeesViewビュー・オブジェクトは、識別子属性JobId属性を、サブタイプ・ビュー・オブジェクトSaleEmployeesViewを持つ識別子属性として定義できます。ほとんどの場合、サブタイプ・ビュー・オブジェクトはサブタイプ識別子属性値を定義するため、リソース定義で属性値を空にしておくことができます。たとえば、サブタイプ・ビュー・オブジェクトSalesEmployeesViewで、SA_REP (営業担当者)がJobId識別子属性値として定義されている場合、Employeesリソースに対して行われるリクエストには、リソースで定義されたサブタイプではなく、従業員のジョブIDに基づくサブタイプ属性が含められます。リソースで識別子属性サブタイプ値を定義すると、同じタイプがリソース・アイテムに適用されます。

ADF RESTリソースで標準のHTTPアクションを公開する方法

ADF RESTリソースで公開する標準のデータ処理操作は、リソースの基礎となるビュー・インスタンスのアクションに対応しています。実行時、サービス・クライアントは、RESTful Webサービスでこれらの操作をHTTPアクションとして起動します。

表16-2に、RESTリソースの概要エディタにおいてデフォルトで公開される標準操作をリストします。リソース・ツリーで行った各リソース選択のリストから操作を選択解除することにより、別の操作セットを公開できます。GETメソッドは常にリソースに対して公開されることに注意してください。

表16-2 標準ビュー・インスタンス・データ処理操作

操作選択	HTTPメソッド名	操作の説明
作成	POST	1つのADFビジネス・コンポーネント・ビュー行またはビュー行セットを作成します。
作成および更新(組み合せてUpsertに相当)	POST	POSTメソッドと、trueに設定したUpsert-Modeヘッダーを組み合せて使用して、ペイロード・コンテンツをRESTリソースとマージします。RESTリソースが存在しない場合は、RESTリソースを作成します。そのRESTリソースが存在する場合は、ペイロード・コンテンツをRESTリソースとマージします。
更新	PATCH	1つのADFビジネス・コンポーネント・ビュー行の指定されたアイテムを更新します。成功するには、この操作に対してビュー行が存在する必要があります。
削除	DELETE	1つのADFビジネス・コンポーネント・ビュー行またはビュー行セットを削除します。
なし	GET	1つのADFビジネス・コンポーネント・ビュー行またはビュー行セットを読み取ります。この操作は、リソースの作成時にデフォルトで使用できることに注意してください。

ノート:

ADF RESTリソース・リクエストでHTTP PUTメソッドを実行する機能は推奨されていないことに注意してください。現在のリリースでは、基礎となるビュー・オブジェクトで更新操作が有効になっている場合は、ADF RESTリソースの記述でPUTアクションが引き続き表示されています(操作でPUTおよびPATCHメソッドを有効にします)が、この機能は今後のリリースではサポートされないため、ADF RESTサービス・クライアントで、PUTリクエスト(ビュー行のすべてのアイテムが置き換えられます)を行わないでください。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。

HTTPアクションを公開するには:

1. 「アプリケーション」ウィンドウで、編集するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. RESTリソースの概要エディタで、「リソース」ドロップダウンから対象のリソースを選択し、「構造」ツリーを展開して、編集するリソース・アクセッサ・ノードを選択します。

   ルート・リソースおよび子リソースに対して操作を公開できます。「構造」ノードの詳細は、表16-1を参照してください。

3. 概要エディタの「表現」タブをクリックし、「使用可能な操作」セクションで、現在の「構造」ツリー選択に対して公開する操作を選択します。
4. 「構造」ツリーで別のノードを選択して、リソース構造の別のリソース・アクセッサで操作を公開します。

ADF RESTリソースの取得操作の最適化に関する必知事項

すべてのADF RESTリソースでは、サービス・クライアントによる読取り操作がサポートされます。効率的な読取り操作(HTTP GETリクエスト)をサポートするには、ADF RESTリソースの基礎となるビュー・オブジェクト定義で、HTTPリクエスト・ペイロードでのコレクションのページングをサポートするように設定されたアクセス・モードを定義する必要があります。範囲ページングの詳細は、「ビュー・オブジェクトの範囲ページ移動を有効にする方法」を参照してください。

ADF RESTリソースのキャッシュを制御する方法

ADF RESTリソース・リクエストにより発生したADF RESTリソース・ペイロードのキャッシュ継続期間を細かく制御する場合は、RESTリソース概要エディタで、リソースのルートにキャッシュ制御(秒数)を構成します。実行時、キャッシュ設定によって、HTTPレスポンスでリソース・ペイロードをキャッシュ/格納する中間プロキシを回避できます。

JDeveloperのRESTリソースの概要エディタでは、リソースのルート・ノードの「構成」タブに、リソース・キャッシュ制御の設定が表示されます。ルート・リソースでこの設定が行われると、web.xmlファイル内にアプリケーション・レベルのキャッシュ設定が構成されていたとしても、その設定はオーバーライドされます。たとえば、次の図では、Departmentsリソースのルートに、キャッシュ最大有効期間が30秒に設定されています。オプション「カタログに表示」を選択すると、ADF RESTリソース・リクエストの記述にキャッシュ設定を表示できます。

図16-20 RESTリソースのルートに設定されたキャッシュ最大有効期間(秒数)

12.1.1.4.0リリース以降、RESTフレームワークではCache-Controlの追加の構成オプションがサポートされています。「ヘッダー・フィールド定義 - キャッシュ制御」を参照してください。これらの追加の構成オプションは、ソース・エディタで指定できます。有効な値のいずれかを指定すると、そのCache-Controlヘッダーがペイロード・レスポンスに追加されます。

有効な値は、次のとおりです。

• キャッシュ可能性: レスポンスをキャッシュできるかどうかを示します。有効な値はpublic、privateおよびno-cacheです。

  値publicは、キャッシュのステータスに関係なくレスポンスを任意のキャッシュでキャッシュできることを示します。認可ヘッダーを持つリクエストでは共有キャッシュでレスポンスをキャッシュできないため、この値はauthorizationヘッダーを含むリクエストで役立ちます。

  値no-cacheはレスポンスをキャッシュしないという意味ではありませんが、レスポンスを戻す前に再検証するようブラウザに指示します。

• NoStore:: キャッシュ可能性の設定に関係なく、レスポンスをキャッシュできないことを示します。これは、値trueおよびfalseを持つブール・フラグです。trueに設定した場合、他の設定がある場合はno-storeがカンマで区切られて、レスポンスのCache-Controlヘッダーに追加されます。
• 再有効化: 失効したレスポンスを戻すようにキャッシュが構成されている場合、レスポンスを再検証する必要があることを示します。MaxAgeを0に構成した場合、レスポンスは即座に失効するため、キャッシュで毎回再検証する必要があります。有効な値はmust-revalidateです。

「Cache - Controlヘッダーに関する必知事項」を参照してください。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従って、ビュー・オブジェクトにRESTリソースを作成します。

キャッシュ制御の最大有効期間の設定を構成するには:

1. 「アプリケーション」ウィンドウで、編集するADF RESTリソースを定義するリソース定義ファイルをダブルクリックします。
2. RESTリソースの概要エディタで、「リソース」ドロップダウンから対象のリソースを選択し、「構造」ツリーで、ルート・リソース・ノードを選択します。

   「構造」ノードの詳細は、表16-1を参照してください。

3. 概要エディタの「構成」タブをクリックし、記述にキャッシュ制御の設定を表示する場合には「カタログに表示」をクリックします。「最大有効期間」には、ペイロード・キャッシュの最大有効期間(秒数)を入力します。

   このタブは、「構造」ツリーで選択する子リソース・ノードには表示されません。

Cache - Controlヘッダーに関する必知事項

次の表に、有効な組合せで選択されたオプションのサブセットを使用してRESTフレームワークでサポートされているユースケースの例をいくつか示します。開発者は任意の組合せを選択して、レスポンスに必要なCache-Controlヘッダーを生成できます。

Cache-Control値	カテゴリ	説明	例
<CacheControl> <Cacheability>no-cache</Cacheability> <NoStore>true</NoStore> <Revalidation>must-revalidate</Revalidation> </CacheControl>	機密データ	レスポンスはキャッシュされません。	銀行口座情報
<CacheControl> <Cacheability>public</Cacheability> <MaxAge>30</MaxAge> </CacheControl>	パブリック共有データ	指定した秒数まで、レスポンスをブラウザおよび任意の中間キャッシュでキャッシュできます。	LOV。国コードなど
<CacheControl> <Cacheability>private</Cacheability> <MaxAge>30</MaxAge> </CacheControl>	プライベート・データ	指定した秒数まで、レスポンスをクライアントのブラウザでキャッシュできます。	オーダー履歴

たとえば、次のサービス構成がDeptAM_DeptVOResources.xmlで定義されています。

<tree IterBinding="DeptIter" id="departments" AccessorFolder="Always">
  <ServiceConfiguration>
    <CacheControl>
      <Cacheability>private</Cacheability>
      <MaxAge>600</MaxAge>
    </CacheControl>
  </ServiceConfiguration>
  <nodeDefinition .../>
</tree>

部門リソースに対するすべてのリクエストには、次のCache-Controlヘッダーがあります。

REQUEST

GET http://example.com/demoApi/resources/1.0/departments

RESPONSE

200 OK
Cache-Control: private, 
max-age=600
{
  ...

ADF RESTレスポンスの形式の制御方法

REST-Pretty-Printヘッダーを使用して、レスポンス・ペイロードの余分な空白を削除できます。この属性は、記述およびGET、PATCHおよびPOSTペイロード・レスポンスに設定できます。このプロパティは、startup Properties要素の下のadf-config.xmlで設定する必要があります。

<adf-adfm-config xmlns="http://xmlns.oracle.com/adfm/config">
    <startup>
      <Properties>
        <adf-property name="ORACLE.BC.REST.PRETTYPRINTJSON" value="true"/>
      </Properties>
    </startup>
</adf-adfm-config>

記述の場合、このヘッダーによりレスポンスのサイズが約50%削減されます。

ADF RESTリソースのバージョニング

JDeveloperでは、ADF RESTリソースをバージョニングできます。これにより、ADF RESTリソースのユース・ケースまたはバッキング・ビュー・オブジェクトが変更された場合に、ADF RESTリソースの新しいバージョンを簡単に作成できます。

開発サイクル中は、リソースをバージョニングする必要なく、ADF RESTリソースに変更を加えることができます。ただし、RESTful Webサービスをデプロイした後、ADF RESTリソースにアクセスするサービス・クライアントでそれらのユースケースが満たされることは、リソース・コレクションの安定性に依存します。

時間の経過に伴い、ユースケースが変化したり、RESTリソースの基礎となるビュー・オブジェクトが変化したりすることによって、すでにデプロイされているリソースのリソース構造を変更することが必要になる場合があります。このとき、既存のADF RESTリソースに対する変更に、デプロイされているRESTサービスとの後方互換性がない場合があり、新しいバージョン識別子およびそのバージョンのADF RESTリソースを作成することが必要になる場合があります。

ADF RESTリソースのバージョニング方法

adf-config.xmlファイルの概要エディタを使用して、新しいバージョン識別子を作成し、既存のバージョンのライフサイクル・ステータスを更新します。ライフサイクル・ステータスは、active、deprecatedまたはdesupportedのいずれかになります。サービス・クライアントが、リクエストされたバージョンに存在しないリソースをリクエストすると、ADF RESTランタイムによって、ステータスがactiveまたはdeprecatedになっている前のバージョンにフォールバックされます

リリース・バージョン・リスト内のリリース名識別子の順序は重要です。ADF RESTランタイムは、最上位のリリース名を最新バージョンとして認識します。リストの最上位の名前の下に続くリリース名は、バージョンの順序リストを形成します。図16-21に示すように、11.0は最初のバージョンであるため、リストの一番下に表示される必要があり、後続のバージョンはその上にリストされます。ここでは、11.2が最新バージョンです。

図16-21 ADF RESTリソースのバージョン管理

「図16-21 ADF RESTリソースのバージョン管理」の説明

ノート:

バージョンの順序リストでリリース識別子の位置を変更するには、概要エディタの「リリース・バージョン」ページで矢印を使用して、識別子をリストの上(より新しいバージョン)または下(以前のバージョン)に移動できます。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、どのような編集によって、後方互換性のない変更がリソースに発生し、新規バージョンのリソースの作成が必要となるかを理解しておくと役立つ場合があります。詳細は、「ADF RESTリソースのバージョニングに関する必知事項」を参照してください。

また、サービス・クライアントによるリクエストがリソースのバージョン識別子にどのように依存するかについても、理解しておくと役立つ場合があります。詳細は、「実行時に行われる処理: ADF RESTリソースのバージョンの起動」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

ADF RESTのバージョンを管理するには:

1. 「アプリケーション」ウィンドウの「アプリケーション・リソース」ペインで、DescriptorsおよびADF META-INFノードを開き、adf-config.xmlファイルをダブルクリックします。
2. adf-config.xmlファイルの概要エディタで、「リリース・バージョン」ナビゲーション・タブをクリックし、「新規リリース・バージョンの作成」アイコン・ボタンをクリックして新しいリソース・バージョン識別子を作成します。
3. ランタイムに影響するバージョンの順序を変更する場合は、表からバージョンを選択し、表の右にある矢印を使用して、バージョンのリスト内でその階層を変更します。

   ADF RESTランタイムは、リストの最上位のバージョンをリソースの最新バージョンとして認識します。

4. オプションで、対象のリソース・ライフサイクルに適合するように、ステータス(active、desupported、deprecated)を選択します。

   バージョンを作成してRESTリソースに割り当てた後で、バージョン識別子をadf-config.xmlファイルから削除する必要があります。バージョンを効率的に削除するには、そのステータスをdesupportedに変更する方法が適しています。

ADF RESTリソースのバージョニングに関する必知事項

次に、すでにデプロイされているRESTful Webサービスと後方互換性がないとみなす必要があるADF RESTリソース構造への変更の例を示します。

• 公開されている属性の名前変更

• すでに公開されている属性の削除または非表示

• すでに公開されている子リソースの削除

• 標準操作の無効化

• LOVビュー・アクセッサの無効化または別のビュー・オブジェクトに対するLOVの変更

特定の状況では、リソースをバージョニングしないで、ADF REST構造を変更できます。次の変更は後方互換性があるとみなされるため、すでにデプロイされているADF RESTリソースの新規バージョンを作成する必要はありません。

• 属性を必須として定義しない新規属性および基礎となるビュー・オブジェクトの公開

  必須として定義された属性を公開する場合は、リソースをバージョニングする必要があることに注意してください。

• 標準操作の公開

• 新しい子リソースの公開

• すでに公開されている属性に対するLOVビュー・アクセッサの定義

実行時に行われる処理: ADF RESTリソースのバージョンの起動

指定するバージョン識別子は、サービス・クライアントがRESTリソースの操作の起動に使用するURLを形成します。たとえば、次のGETリクエストでは、URLパラメータ11.0および11.1を指定して、Departmentsリソースの2つの異なるバージョンにアクセスします。

http://localhost:7101/RESTSample_App/rest/11.0/Departments

http://localhost:7101/RESTSample_App/rest/11.1/Departments

adf-config.xmlファイルの概要エディタを使用して、既存のバージョンのライフサイクル・ステータスを更新する場合は、各バージョンにactive、deprecatedまたはdesupportedのいずれかのタグを付けます。ステータスdeprecatedは実行時の影響はなく、ドキュメントの目的で提供されていますが、ステータスをdesupportedにすると、デプロイされているリソースにアクセスできなくなります。

adf-config.xmlファイルのリリース・バージョン・リスト内のリリース名識別子の順序は重要です。ADF RESTランタイムは、最上位のリリース名を最新バージョンとして認識します。リストの最上位の名前の下のリリース名は、バージョンの順序リストを形成します。たとえば、次のGETリクエストでは、Departmentsリソースのバージョン11.1を取得します。ここで、11.1は、リリース・バージョン・リストの最上位です:

http://localhost:7101/RESTSample_App/rest/11.1/Departments

サービス・クライアントが、リクエストされたバージョンに存在しないリソースをリクエストすると、ADF RESTランタイムによって、ステータスがactiveまたはdeprecatedになっている前のバージョンにフォールバックされます。このため、Departmentsリソースのバージョン11.0および11.1が存在し、11.2が存在しない場合は、バージョン11.2へのリクエストに対して、次に最新のリソースであるバージョン11.1が返されます。

ADF RESTランタイム・フレームワークのバージョニング

JDeveloperでは、ADF RESTリソースに対するリクエストの処理時に、サービス・クライアントで使用するデフォルトのADF RESTランタイム・フレームワークを指定できます。デフォルトのフレームワーク・バージョンを宣言すると、クライアントは適切なレベルの機能とやり取りするようになります。

Oracle JDeveloper 12cでは、リリース12.2.1.2.0から、サービス・クライアントで新しいラインタイム機能をサポートするためにADF RESTフレームワーク拡張機能が導入されます。アプリケーションでこのような拡張機能が役立つかどうかは、アプリケーションのユース・ケースによって決まります。サービス・クライアントに公開する前にフレームワーク拡張機能を評価できるように、ADF RESTフレームワークの各版はバージョン1、2、3といったバージョン番号で識別されます(バージョン1はデフォルトでアプリケーションに関連付けられます)。アプリケーションは、現在のフレームワーク・バージョン(ベース・フレームワーク・バージョン1など)のままにしておくことも、新しいバージョン(フレームワーク・バージョン2など)を選択してアプリケーションのユース・ケースを拡張することもできます。これにより、ADF RESTランタイムでは、サービス・クライアントに対して必要なレベルの機能を提供するフレームワーク・バージョンを使用してリクエストを処理するようになります。アプリケーションでリクエストを処理するフレームワーク・バージョンを指定できると、準備が整えばそれらの機能を選択できます。

新しいADF RESTランタイム・フレームワーク・バージョンが導入されると、後続フレームワークで提供されるランタイム機能を使用するようにアプリケーションの更新が必要になることがあります。これを実行するために、ADF RESTデザインタイムでは、adf-config.xmlファイルでrestFrameworkVersionプロパティを関連付けてアプリケーションのADF RESTリソースの各バージョンにデフォルトのフレームワーク・バージョンを定義できます。たとえば、リソース・バージョン11.0があり、フレームワーク・バージョン1の基本機能にデフォルトで関連付けられています。その場合、Oracle JDeveloper 12.2.1.2.0およびADF RESTフレームワーク・バージョン2以降、新しいリソース・バージョン11.1を作成してフレームワーク・バージョン2に関連付けることを選択できます。あるいは、新しいリソース・バージョンを作成するかわりに、既存のリソース・バージョンでフレームワーク・バージョン2を選択できます。個々のリソース・バージョンに関連付けるデフォルトのフレームワーク・バージョンを指定することで、アプリケーションによって適切なレベルの機能がサービス・クライアントに公開されるようになります。

ノート:

JDeveloperリリース12.2.1.2.0以降、ADF RESTランタイム・フレームワークのバージョン1、2および3が存在します(バージョン1はベース・バージョンであり、ADF RESTサービス・クライアントに対して複数のフレームワーク・バージョンをサポートする機能が含まれています)。JDeveloperリリース12.2.1.4.0以降、バージョン4、5、6および7も存在します。フレームワークのバージョンの詳細は、「ADF RESTランタイム・フレームワークのバージョニングに関する必知事項」を参照してください。

ADF RESTランタイム・フレームワークのバージョニング方法

「ソース」ビューでadf-config.xmlファイルの概要エディタを使用し、ADF RESTアプリケーションのリソース・バージョンに対してデフォルトのADF RESTフレームワーク・バージョンを宣言します。サービス・クライアントがリソースをリクエストすると、ADF RESTランタイムでは、リクエストURLに指定されたリソース・バージョンに関連付けられている宣言されたフレームワーク・バージョンを使用してリクエストを処理します。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

アプリケーションのADF RESTリソースについてリソースの版を管理するために作成したリリース・バージョンの役割を理解しておくと役立つ場合があります。詳細は、「ADF RESTリソースのバージョニング」を参照してください。

また、新しいリソース・バージョンを作成し、それに対してデフォルトのフレームワーク・バージョンを宣言する必要がある後方互換性のない変更がADF RESTフレームワーク・バージョンによってどのように導入されるかを理解しておくと役立つ場合があります。「ADF RESTフレームワークのバージョニングに関する必知事項」を参照してください。

さらに、サービス・クライアントによるリクエスト処理がリソース・バージョンに対して宣言されたADF RESTフレームワークによってどのように影響を受けるかを理解しておくと役立つ場合があります。「実行時に行われる処理: ADF RESTフレームワーク・バージョンの起動」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。「RESTful Webサービスの追加機能」を参照してください。

デフォルトのADF RESTフレームワーク・バージョンを宣言するには:

1. 「アプリケーション」ウィンドウの「アプリケーション・リソース」ペインで、DescriptorsおよびADF META-INFノードを開き、adf-config.xmlファイルをダブルクリックします。
2. adf-config.xmlファイルの概要エディタで、「リリース・バージョン」ナビゲーション・タブをクリックし、アプリケーションで使用されるリリース・バージョンの既存のリストを表示します。
3. 必要に応じて、「新規リリース・バージョンの作成」アイコン・ボタンをクリックし、新しいフレームワーク・バージョンと関連付けるための新しいリソース・バージョン識別子を作成します。たとえば、新しいADF RESTフレームワーク・バージョンによって後方互換性のない変更がサービス・クライアントに導入され、既存のフレームワーク・バージョンに関連付けることができる既存のリリース・バージョンの元の機能を保持する場合に、新しいリリース・バージョンを作成できます。
4. デフォルトのフレームワーク・バージョンを指定して、特定のリリース・バージョンのリソースに対するリクエストを処理するには、「ソース」タブをクリックし、<version>要素を編集して特定のフレームワーク・バージョン番号を指定したrestFrameworkVersionプロパティを追加します。JDeveloper 12.2.1.2.0以降、バージョン1、2および3を使用できます。JDeveloper 12.2.1.4.0以降、バージョン4、5、6および7も使用できます。XMLに対して他に変更を加えないでください。特にリリース・バージョンの順序(最上位のリリース・バージョンが最新リリース・バージョン)を変更しないでください。

   <versions>
       <version name="11.2" displayName="11.2" restFrameworkVersion="3"/>
       <version name="11.1" displayName="11.1" restFrameworkVersion="2"/>
       <version name="11.0" displayName="11.0" restFrameworkVersion="1"/>
   </versions>

   前述の例では、バージョン11.0というADF RESTリソースに対するリクエストではフレームワーク・バージョン1を使用してリクエストを処理する一方、11.1というリソースに対するリクエストでは、フレームワーク・バージョン2で提供される機能を使用し、11.2というリソースに対するリクエストでは、リクエストの処理時にフレームワーク・バージョン3で提供される機能を使用します。

ADF RESTフレームワークのバージョニングに関する必知事項

ADF RESTアプリケーションのADF RESTフレームワークのバージョニングが必要となる理由の1つは、ADF RESTランタイム・フレームワークの後続バージョンで提供される新機能を選択することです。現在、次のフレームワーク・バージョンが提供されています。

ノート:

バージョン1より後の各ADF RESTフレームワーク・バージョンでは、以前のフレームワーク・バージョンではサポートされていない機能が提供されます。そのため、後のフレームワーク・バージョンを選択すると、REST APIを使用するサービス・クライアントに関する後方互換性がない変更がアプリケーションのREST APIに導入される可能性があります。このトピックでは、各フレームワーク・バージョンに対する変更について説明します。

フレームワーク・バージョン1

バージョン1と識別されるADF RESTフレームワークは、JDeveloperリリース12.2.1.0.0から使用できます(ADF RESTの初期導入時)。これは、特定のJSONペイロード形式を指定したベース・バージョンです。このリリースおよびすべての後続リリースでは、adf-config.xmlファイルでrestFrameworkVersionプロパティを使用できることで、複数のフレームワーク・バージョンをサポートする機能が組み込まれました。

バージョン1は、他のバージョンが指定されていない場合にサービス・クライアントのリクエストを処理するためにADF RESTランタイムで使用されるデフォルトのバージョンです。したがって、基本レベルの機能でサービス・クライアントをサポートする場合、アプリケーションでは、adf-config.xmlファイルでrestFrameworkVersionプロパティを使用してバージョンを宣言する必要がありません。

ベース・フレームワーク・バージョン(バージョン1)でサポートされるQuery-By-Exampleリソース問合せ構文は、ADF RESTフレームワークの後続バージョンと互換性がないことに注意してください。ADF RESTフレームワークのバージョン2から、より高度な問合せ構文がかわりに提供されます。

フレームワーク・バージョン2

バージョン2と識別されるADF RESTランタイム・フレームワークは、JDeveloperリリース12.2.1.2.0から使用できます。この新しいバージョンの目的は、ADF RESTリクエスト用の拡張問合せ式構文を導入することです。ADF RESTフレームワークのバージョン2では、q問合せパラメータ値をフレームワーク・バージョン1とは異なって解析するため、フレームワーク・バージョン1に依存するサービス・クライアントに後方互換性のない変更が導入されます。フレームワーク・バージョン2 (以降)がリソース・リクエストに指定されている場合のみ、ADF RESTランタイムではリクエストを処理するために拡張式構文の使用がサポートされます。

バージョン1では、次のように、q問合せパラメータを使用したリソース・コレクションのフィルタ処理がQuery-by-Example構文に制限されます。

GET /rest/11.0/Departments?q=Dname SA*;Loc BOSTON

これに対してバージョン2から、次のように、新しい拡張問合せ構文ではRowMatch問合せ式を使用したリソース・コレクションのフィルタ処理がサポートされます。

GET /rest/11.1/Departments?q=Dname like 'SA*' or Loc = 'BOSTON'

ノート:

RowMatch式(フレームワーク・バージョン2以降で提供)とQuery-by-Example構文(バージョン1のみ)の両方をサポートするには、フレームワーク・バージョン2 (以降)をadf-config.xmlファイルでRESTリソースに定義する新しいリリース・バージョン識別子に関連付ける必要があります。たとえば、前述のURLサンプルでは、リリース・バージョン11.0の元の機能を保持しながら、バージョン11.1の新機能を公開できます。これは、アプリケーションのadf-config.xmlファイルで、リリース・バージョン11.1でrestFrameworkVersion="2"プロパティを使用して、フレームワーク・バージョン2がデフォルトとして宣言されていることを前提としています。あるいは、サービス・クライアントで現在のフレームワーク・バージョンの機能が不要になった場合に、新しいフレームワーク・バージョンを既存のリリース・バージョン識別子に関連付けることができます。したがって、新しいフレームワーク・バージョンを使用するために、リリース・バージョンを増す必要がありません。

RowMatch式で提供される拡張問合せ構文の説明は、「ADF RESTフレームワーク・バージョン2の拡張問合せ構文に関する必知事項」を参照してください。

フレームワーク・バージョン3

バージョン3と識別されるADF RESTランタイム・フレームワークは、JDeveloperリリース12.2.1.2.0から使用できます。このバージョンの目的は、後続のADF RESTリクエストでリソース・アイテムがさらに返されるかどうかを判別するためにサービス・クライアントで使用できるペイロード属性によってネストされた子リソースを取得するためのサポートを追加することです。この機能をサポートするために、フレームワーク・バージョン3でのペイロード構造では、ネストされた子リソースをアイテムの配列(バージョン1および2)でなく、リソース・コレクションとして表すようになっています。したがって、バージョン3では、フレームワーク・バージョン1またはバージョン2に依存するサービス・クライアントに後方互換性のない変更が導入されます。バージョン3を選択することにした場合、GET操作で?expandおよび?fields問合せパラメータを使用してネストされた子リソースをhasMore属性とともにリソース・コレクションとして返すことができる機能が公開されます。要するに、この変更により、フェッチするために1つ以上のリクエストを必要とするネストされた子リソースのページ区切りがサポートされます。

フレームワーク・バージョン3のサポートをアプリケーションに追加する場合は、adf-config.xmlファイルでrestFrameworkVersionプロパティを使用した既存レベルの機能の保持に、フレームワーク・バージョン2 (前述の項を参照)について説明している同じガイドラインが適用されます。

バージョン3で導入されるネストされた子リソースの新しいペイロード構造の例については、「ネストされた子リソースのフェッチ」 および「属性のフィルタ処理による問合せ(部分取得)」を参照してください。hasMore属性を使用したリソース・コレクションのページ区切りの詳細は、「リソース・コレクションのページング」を参照してください。

フレームワーク・バージョン4

バージョン4と識別されるADF RESTランタイム・フレームワークは、JDeveloperリリース12.2.1.4.0から使用できます。リクエストでADF RESTフレームワーク・バージョン4を使用でき、そのリクエストがapplication/vnd.oracle.adf.error+jsonまたはapplication/jsonメディア・タイプで実行される場合、レスポンスでは、HTTPステータス・コードとエラー・メッセージの他に、例外の詳細を取得できます。フレームワーク・バージョン4では、レスポンスの形式が例外の詳細ペイロードになり、サービス・クライアントに次の利点をもたらします。

• 1つのリクエスト内で複数のエラーが発生した場合、各エラーの詳細が階層構造で表示されます。

• 各エラーに対応するADF例外を特定するアプリケーション固有のエラー・コードが表示される場合があります。

• 各エラーの場所を特定するエラー・パスがリクエスト・ペイロード構造で表示される場合があります。

ノート:

例外の詳細には、アプリケーション固有のエラー・コードやリクエスト・ペイロードのエラー・パスなど、一部の詳細が表示される場合とされない場合があります。

たとえば、次のような間違った書式設定の日付フィールドが含まれるペイロードを使用して送信されたPOSTに対するエラー・レスポンスを、フレームワーク・バージョン3 (以前)が有効な場合とフレームワーク・バージョン4 (以降)が有効な場合とで比較します。

{    "EmpNum" : 5027,
     "EmpName" : "John",
     "EmpHireDate" : "not a date"
}

標準エラー・レスポンス

フレームワーク・バージョン4がない場合、レスポンス・ペイロードは生成されず、かわりにリクエスト・ペイロードを参照しない単一のエラー・メッセージのみがレスポンスで返されます。

"An instance of type oracle.jbo.domain.Date cannot be created from string not a date. The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm."

例外ペイロード・エラー・レスポンス

フレームワーク・バージョン4 (以降)が有効になっている場合、次の例外の詳細ペイロードがレスポンス用に生成されます。ペイロードには通常のHTTPステータス・コードが含まれ、1つ以上の例外の詳細が配列構造で書式設定されます。

{    "title" : "Bad Request",
    "status" : "400",
    "o:errorDetails" : [ {
     "detail" : "An instance of type oracle.jbo.domain.Date cannot be created from string not a date. 
               The string value must be in format YYYY-MM-DDTHH:MI:SS.sss+hh:mm.",
       "o:errorCode" : "26099",
       "o:errorPath" : "/EmpHireDate"
    } ]
 }

フレームワーク・バージョン5

バージョン5と識別されるADF RESTランタイム・フレームワークは、JDeveloperリリース12.2.1.4.0から使用できます。バージョン4以前では、ネストされたリソースをLOVターゲットとして選択できます。たとえば、/rest/v1/States/California/Citiesなどです。バージョン5以降では、かわりに、フィルタリングを使用してネストされたLOVリソースにアクセスします(例: /rest/v1/Cities?finder=ByState;name=California)。このフレームワーク・バージョンでは、行コンテキストのLOV URLがペイロードおよび記述で返されなくなります。最上位レベルのリソースを指すLOVリソースURLのみが記述され、ペイロードに含まれます。

「行検索のLOVリソースの構成に関する必知事項」と「フレームワーク・バージョン5以降でのLOV有効属性値の取得」を参照してください。

このフレームワーク・バージョン5では、現在サポートされている文字列、数値、日付およびブール型のほかに、リクエスト・パラメータおよびレスポンス・パラメータもサポートされます。サポートされるJava型には、java.util.Listおよびjava.util.Mapが含まれます。ADF RESTカタログの記述では、レスポンス・パラメータがjava.util.Listの場合、リクエスト・パラメータをarrayに指定し、レスポンス・パラメータがjava.util.Mapの場合は、リクエスト・パラメータにobjectを指定します。

{
  "name" : "sales",
  "parameters" : [ {
    "name" : "prices",
    "type" : "array",
    "typeProperties": {
      "itemType": "number"
    },
    "mandatory" : false
  }, {
    "name" : "quantities",
    "type" : "object",
    "typeProperties": {
      "itemType": "array",
      "typeProperties": {
        "itemType": "integer"
      }
    },
    "mandatory" : false
  } ],
  "resultType" : "object",
  "typeProperties": {
    "itemType": "number"
  },
  "method" : "POST",
  "requestType" : [ "application/vnd.oracle.adf.action+json" ],
  "responseType" : [ "application/vnd.oracle.adf.actionresult+json", "application/json" ]
}

フレームワーク・バージョン6

バージョン6と識別されるADF RESTランタイム・フレームワークは、JDeveloperリリース12.2.1.4.0から使用できます。このフレームワーク・バージョンの目的は、リソース・フィールドと、リンクやヘッダーなどのアイテム・コンテキスト情報を容易に区別することです。このバージョンでは、新しい要素@contextが導入され、アイテムのすべての情報が@contextセクションの下に移動します。changeIndicator値がheadersの下のETagに移動します。新しいコンテキスト情報キーは、特定のリソース・アイテムの一意識別子を文字列として含む@contextの下に入れられます。@contextセクションにも、作成/アップサートおよび更新アクション用のレスポンス・ペイロードの警告が含まれます。「グループ化されたコンテキスト情報を持つリソースのフェッチ」を参照してください。

レスポンス・ペイロードおよびコレクション・レスポンス・ペイロードのリソース・アイテムの新しいペイロードは次のようになります。

{
   "field1": "value1",
   "field2": "value2",
     ...
   "@context" : {
      "key" : "AB8765BCD",
      "headers" : {
         "ETag" : "ACED..."
       ...
      },
      "links": [ {
         "rel": "self",
         "href":
          ...
      } ]
      "warnings": [ {
         "detail": "Warning from overridden validateEntity method in DeptImpl : DeptName = ABC"
      }, {
         "detail": "Attribute set with value 92 for DeptNum in Dept failed",
         "o:errorCode": "27011",
         "o:errorPath": "/DeptNum"
      }, {
        "detail": "Warning from overridden afterCommit method in DeptViewImpl"
      }, {
        "detail": "Warning from overridden afterCommit method in DeptViewImpl"
      } ]
  }
}

フレームワーク・バージョン7

バージョン7と識別されるADF RESTランタイム・フレームワークは、JDeveloperリリース12.2.1.4.0から使用できます。このフレームワーク・バージョンでは、最上位レベルのLOVがサポートされ、ADF REST記述の行レベルのLOVリソースの記述が完全に削除されます。フレームワーク・バージョン5より前のフレームワーク・バージョンでは、RESTリソースの行コンテキストで、ネストされたLOVがサポートされます。フレームワーク・バージョン7が有効の場合は、「フレームワーク・バージョン5以降でのLOV有効属性値の取得」の説明に従って、かわりに静的LOVリソースおよび行検索URLリンクを記述で使用します。

さらに、バージョン7では、レスポンスのリソース・アイテムのペイロード・リンク・セクションからLOVリンクが削除されます。目的は、LOVリンクを削除することで、バージョン5以降で実装されたパラメータ化された行検索の使用を強制することです。たとえば、バージョン7を有効にして作成されたリソース・アイテム・リクエストについて、このレスポンスを以前のバージョンの同じリクエストと比較します。

{
   "EmpId" : 101,
   "EmpName" : "Bob",
   "@context" : {
      "key" : "1",
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/12.0/Employees/101",
        "name" : "Employees",
        "kind" : "item"
      }, {
        "rel" : "canonical",
        "href" : "http://server/demo/rest/12.0/Employees/101",
        "name" : "Employees",
        "kind" : "item"
      } ]
   } 
}

LOVリソース・リンクが戻された、以前のバージョンの同じリクエストを示します。

{
   "EmpId" : 101,
   "EmpName" : "Bob",
   "@context" : {
      "key" : "1",
      "links" : [ {
        "rel" : "self",
        "href" : "http://server/demo/rest/12.0/Employees/101",
        "name" : "Employees",
        "kind" : "item"
      }, {
        "rel" : "canonical",
        "href" : "http://server/demo/rest/12.0/Employees/101",
        "name" : "Employees",
        "kind" : "item"
      }, {
        "rel" : "lov",
        "href" : "http://server/demo/rest/12.0/Employees/10/lov/JobsLOV",
        "name" : "JobsLOV",
        "kind" : "collection"
      } ]
   } 
}

ADF RESTフレームワーク・バージョン2の拡張問合せ構文に関する必知事項

バージョン2と識別されるADF RESTランタイム・フレームワークは、JDeveloperリリース12.2.1.2.0から提供されました。このフレームワーク・バージョンの目的は、ADF RESTリクエスト用の拡張問合せ式構文を導入することです。このバージョンでは、q問合せパラメータ値をフレームワーク・バージョン1とは異なって解析するため、フレームワーク・バージョン1に依存するサービス・クライアントに後方互換性のない変更が導入されます。

フレームワーク・バージョン2 (以降)を選択することにした場合、ADF RESTランタイムでは拡張式構文を使用してq問合せパラメータに関するフェッチ・リクエストを処理する一方、Query-by-Example構文を使用しているリクエストは無効になり、エラーを返します。しかし、リリース・バージョンのデフォルトをフレームワーク・バージョン1に設定されたままにすることで、フレームワーク・バージョン2で提供される機能を選択しないこともできます。あるいは、adf-config.xmlファイルで既存のリリース識別子をフレームワーク・バージョン1のままにすると同時に、フレームワーク・バージョン2に関連付ける新しいリリース・バージョン識別子を作成することで、基本機能を保持することもできます。

バージョン1では、次のように、問合せパラメータを使用したリソース・コレクションのフィルタ処理が、セミコロンを使用して式を区切るQuery-by-Example構文に制限されます。

GET /rest/11.0/Departments?q=Dname SA*;Loc BOSTON

これに対してバージョン2から、次のように、新しい拡張問合せ構文ではRowMatch式を使用したリソース・コレクションのフィルタ処理がサポートされます。

GET /rest/11.1/Departments?q=Dname like 'SA*' or Loc = 'BOSTON'

このようなRowMatch式には、大/小文字を区別するリソース・アイテムの名前と、その後に演算子と(使用する演算子によって決まる)1つ以上のオペランド値が含まれます。フィルタは単一式のような簡素なものでも、andおよびor結合をグループ分けのための対となったカッコとともに使用して式を組み合せてもかまいません。

フレームワーク・バージョン2以降で提供される拡張問合せ構文の利点

RowMatch式の利点は次のとおりです。

• サポートされている演算子を使用できます。

  DepartmentNumber = 20

  DepartmentNumber <> 20

  DepartmentNumber <= 20

  DepartmentNumber < 20

  DepartmentNumber >= 20

  DepartmentNumber >20

  DepartmentNumber between 20 and 40

  DepartmentNumber not between 20 and 40

  DepartmentNumber in (20, 30, 40)

  DepartmentName like '%S%'

  DepartmentName like 'RE%'

  DepartmentName not like 'RE%'

  Location is null

  Location is not null

• 複数の属性を挿入できます。

  DepartmentNumber = 10 or DepartmentName like 'RESEARCH'

  DepartmentNumber > 10 and DepartmentNumber < 40

  DepartmentNumber < 20 or DepartmentNumber > 30

  (DepartmentNumber = 10 or DepartmentNumber = 30) and (DepartmentName like 'SALES')

  DepartmentNumber BETWEEN 20 and 40) and (Location like 'DAL%')

  (DepartmentNumber > 0 and DepartmentNumber < 100) and (DepartmentName <> 'SALES') and (Location not like 'NEW%')

  (DepartmentNumber = 10 or DepartmentNumber = 30) and (DepartmentName = 'ACCOUNTING' or DepartmentName = 'SALES')

  (DepartmentNumber = 10 and DepartmentName like 'ACC%') or (DepartmentNumber = 20 and DepartmentName like 'RES%')

  DepartmentName='ACCOUNTING' or (DepartmentName like 'R%' and Location like '%ALLA%')

  (DepartmentName like 'R%' and Loc like '%ALLA%') or DepartmentName='ACCOUNTING'

  (DepartmentName like 'R%' or Loc like '%ALLA%') or DepartmentName='ACCOUNTING'

  (DepartmentNumber between 20 and 40) and DepartmentNumber is not null

• ネストした子リソースの属性を挿入できます。

  Deptno > 5 and Emps.Job = 'MANAGER'

  Emps.Job = 'MANAGER' and Deptno > 5

  Deptno > 5 and (Emps.Job = 'MANAGER')

  (Emps.Job = 'MANAGER') and Deptno > 5

  (Deptno > 5) and (Emps.Job = 'MANAGER')

  (Deptno = 10 and Emps.Job = 'PRESIDENT') or (Deptno = 20 and Emps.Job = 'MANAGER')

  Deptno > 5 and Emps.Job = 'MANAGER' and Emps.Sal >= 2500

  Deptno > 5 and (Emps.Job = 'ANALYST' or Emps.Sal >= 4000)

  (Deptno > 5 and Emps.Job = 'ANALYST') or Emps.Sal >= 4000

  Emps.Job = 'ANALYST' or Emps.Job = 'SALESMAN'

  Deptno > 5 and (Emps.Job = 'ANALYST' or Emps.Job = 'SALESMAN')

  Deptno > 5 and Emps.Job = 'MANAGER' and Emps.DirectReports.Sal >= 2000

  Deptno > 5 and (Emps.Job = 'MANAGER' or Emps.DirectReports.Sal >= 2000)

  Deptno > 10 and (Emps.Job = 'MANAGER' and (Loc = 'NEW YORK' or Emps.Mgr=7698))

  Deptno > 10 and (Emps.Job = 'MANAGER' or (Loc = 'NEW YORK' or Emps.Mgr=7698))

  Deptno > 10 and (Emps.Job = 'MANAGER' or (Loc = 'NEW YORK' or Emps.Mgr=7698)) or Deptno = 40

  Deptno > 10 and (Emps.Job = 'MANAGER' or (Loc = 'NEW YORK' or Emps.Mgr=7698)) or (Deptno = 40)

  Deptno > 10 and (Emps.Job = 'MANAGER' or (Emps.DirectReports.Sal > 2000 and (Emps.DirectReports.Comm = 500 or Emps.DirectReports.Deptno > 10)))

  Deptno > 10 and (Emps.Job = 'MANAGER' and (Emps.DirectReports.Sal >= 2000 and (Emps.DirectReports.Comm = 500 or Emps.DirectReports.Deptno > 10)))

• UPPER関数を挿入できます。

  UPPER(DepartmentName) = 'RESEARCH'

  UPPER(DepartmentName) = UPPER('research')

  UPPER(DepartmentName) like 'RES%' and UPPER(Location) like 'DAL%'

  UPPER(DepartmentName) like UPPER('research')

フレームワーク・バージョン2以降で提供される拡張問合せ構文の概要

次に、RowMatch式の例をいくつか示します。

• 値がnullかどうかテストするには、is nullまたはis not nullキーワードを使用する必要があります。

  AssignedToId is null

  AssignedToId is not null

• 等しいことには=記号を使用し、等しくないことには!=または<>演算子を使用します。

  AssignedToId = 100000000089003

  Priority != 1

  Priority <> 1

  ActivityType != 'RS'

  ActivityType <> 'RS'

• 関係比較には、よく使用される<、<=、>または<>の各演算子の他、betweenまたはnot betweenを使用します。

  Priority <= 2

  Priority < 3

  Priority <> 1

  Priority > 1

  Priority >= 1

  TotalLoggedHours >= 12.75

  Priority between 2 and 4

  Priority not between 2 and 4

• 文字列照合には、like演算子を使用でき、パーセント記号%をワイルドカードとして採用し、ワイルドカードの挿入位置に応じて"starts with"、"contains"または"ends with"形式のフィルタ処理を実現します。

  RecordName like 'TT-%'

  RecordName like '%-TT'

  RecordName like '%-TT-%'

• フィールドの値が可能値のリストに含まれているかどうかをテストするには、in演算子を使用できます。

  ActivityType in ('OC','IC','RS')

• andおよびor結合をグループ分けのための対となったカッコとともに使用して式を組み合せて、次のようなさらに複雑なフィルタを作成できます。

  (AssignedToId is null) or ( (Priority <= 2) and (RecordName like 'TT-99%'))

  (AssignedToId is not null) and ( (Priority <= 2) or (RecordName like 'TT-99%'))

  between句またはin句を使用する際、andまたはor結合を使用して他の句と連結する場合は、カッコで囲む必要があります。

実行時に行われる処理: ADF RESTフレームワーク・バージョンの起動

Oracle JDeveloperによって新しいADF RESTフレームワーク・バージョン(JDeveloperリリース12.2.1.2.0以降で提供されるフレームワーク・バージョン2など)が導入された後、サービス・クライアントで適切なレベルの機能が使用されるようにするために、新しいリソース・バージョンを作成して新しいフレームワーク・バージョンに関連付けることが必要になる場合もあります。

たとえば、次のURLではリソース・バージョン11.2を指定しています(アプリケーションのadf-config.xmlファイルにより、このリソース・バージョンはADF RESTフレームワークのバージョン2と関連付けられています)。ADF RESTフレームワーク・バージョン2ではRowMatchフィルタ式がサポートされるため、結果として、ADF RESTランタイムでは適切な機能でリクエストを処理し、SAで始まる名前(SALESなど)の部門またはLocationがBOSTONの部門をフェッチします。

http://server/demo/rest/11.2/Departments?q=DepartmentName like 'SA*' or Location = 'BOSTON'

サービス・クライアントでは、デフォルトのフレームワーク・バージョンをオーバーライドし、カスタム・ヘッダーREST-Framework-Versionに渡された指定のフレームワーク・バージョンを使用して個々のリクエストを処理することもあります。その場合、ADF RESTランタイムでは、アプリケーションのデフォルトのフレームワーク・バージョン宣言を無視します。カスタム・ヘッダーがリクエストで省略されている場合、ADF RESTランタイムでは常に、adf-config.xmlファイルで定義されているアプリケーションのデフォルトのフレームワーク・バージョンを使用します。アプリケーションでデフォルトのフレームワーク・バージョンが定義されておらず、サービス・クライアントに対するリクエストでバージョン・ヘッダーが省略されている場合、ADF RESTフレームワークのバージョン1と想定されます。フレームワーク・バージョンを使用したリクエストの処理の詳細は、「ADF RESTフレームワーク・バージョンの使用」を参照してください。

次の表では、リクエストで特定のADF RESTフレームワーク・バージョンでサポートされている(またはサポートされていない)機能を使用する際の実行時に行われる処理を対比します。特に、バージョン1でのみサポートされるQuery-by-Example構文をバージョン2 (以降)でサポートされるRowMatch式と対比したURLに注目してください。REST-Framework-Versionヘッダーの列は、リクエストのバージョン・ヘッダーが渡されるかどうかを示します。リクエストにバージョン・ヘッダーが含まれる場合、ADF RESTランタイムでは渡されたフレームワーク値でリクエストを処理し、adf-config.xmlファイルのデフォルトの宣言をオーバーライドします。

表16-3 ADF RESTフレームワーク・バージョンによって処理されたリクエストの例

URI	REST-Framework-Versionヘッダー	解決されたバージョン	成功/エラーのノート
GET /rest/11.0/Departments		1	成功。リソース・バージョン11.0のデフォルトのフレームワーク・バージョンを使用します。
GET /rest/11.0/Departments	1	1	成功。リクエストされたフレームワーク・バージョンを使用します(adf-config.xmlファイルのデフォルトの宣言と一致します)。
GET /rest/11.0/Departments	2	2	成功。リクエストされたフレームワーク・バージョンを使用します(adf-config.xmlファイルのデフォルトの宣言をオーバーライドします)。
GET /rest/11.1/Departments		2	成功。リソース・バージョン11.1のデフォルトのフレームワーク・バージョンを使用します。
GET /rest/11.0/Departments?q=Dname SA*;Loc BOSTON		1	成功。リソース・バージョン11.0のデフォルトのフレームワーク・バージョン(バージョン1として定義)を使用します。 フレームワーク・バージョン1ではQuery by Example構文がサポートされています。
GET /rest/11.1/Departments?q=Dname SA*;Loc BOSTON		2	エラーが戻されます。リソース・バージョン11.1のデフォルトのフレームワーク・バージョン(バージョン2として定義)を使用します。 フレームワーク・バージョン2ではQuery by Example構文がサポートされていません。
GET /rest/11.0/Departments?q=Dname LIKE 'SA*' OR Loc = 'BOSTON'	2	2	成功。リクエストされたフレームワーク・バージョンを使用します(adf-config.xmlファイルのデフォルトの宣言をオーバーライドします)。 フレームワーク・バージョン2ではRowMatch式がサポートされています。
GET /rest/11.0/Departments?q=Dname LIKE 'SA*' OR Loc = 'BOSTON'		1	エラーが戻されます。リソース・バージョン11.1のデフォルトのフレームワーク・バージョン(バージョン1として定義)を使用します。 フレームワーク・バージョン1ではRowMatch式がサポートされていません。
GET /rest/11.1/Departments?q=Dname LIKE 'SA*' OR Loc = 'BOSTON'	1	1	エラーが戻されます。リクエストされたフレームワーク・バージョンを使用します(adf-config.xmlファイルのデフォルトの宣言をオーバーライドします)。 フレームワーク・バージョン1ではRowMatch式がサポートされていません。

ADF RESTリソースへのクライアント・アクセスの付与

ADFセキュリティの構成ウィザードを使用し、このウィザードでWebプロジェクトとしてRESTWebService.jprを選択して、ADF RESTリソース・セキュリティを管理します。

RESTリクエストでのアクションの起動に対してユーザー認証が要求されるようにする場合は、ADF RESTリソースに対してセキュリティを有効にできます。ADFセキュリティの構成ウィザードを実行し、ウィザードでWebプロジェクトとしてRESTWebService.jprを選択すると、セキュリティはすべてのFusion Webアプリケーションのように処理され、有効化されます。Webサービス・プロジェクトでADFセキュリティを有効にすることは、デプロイされているサービスにデフォルトではアクセスできず、ユーザーには特定のアクセス権限を付与するアプリケーション・ロールに対するセキュリティ権限が必要となることを意味します。

RESTful Webサービスのユーザーに付与できる権限は、次のクラスによって定義されます。

• RESTリソースで定義されている標準のアクションに対する認可付与を定義するoracle.adf.share.security.authorization.RestServicePermission。

表16-4に、定義されたアプリケーション・ロールに付与できるADF REST権限クラスによって定義されているアクションをリストします。

表16-4 ADF RESTリソースのセキュリティ保護されたアクション

許可できるアクション	RESTリソースへの影響
describe	RESTリソースのコレクションおよびインスタンスを記述できるようにします。
get	RESTリソースのコレクションまたはインスタンスを返すことができるようにします。
update	RESTリソースのコレクションまたはインスタンスを更新できるようにします。
delete	RESTリソースのコレクションまたはインスタンスを削除する権限。
create	RESTリソースのコレクションまたはインスタンスを作成できるようにします。

ADF RESTリソースのアクションを起動するユーザーを認証する一般的なプロセスは、次のとおりです。

1. RESTリソースに対する必要な標準のアクションを有効にします。

2. RESTWebServiceプロジェクトで、ADFセキュリティ・ウィザードを実行します。

3. 1つ以上のアプリケーション・ロールとテスト・ユーザーを作成してJDeveloperでセキュリティをテストします。

4. 必要なアプリケーション・ロールに関連付けるRESTリソースに対するリソース権限を作成します。

5. アプリケーション・ロールとそれらのリソース権限をテスト・ユーザーにマップします。

ADF RESTリソースに対するリソース権限の作成方法

セキュリティ・ポリシーの概要エディタを使用して、リソースで公開した操作をセキュリティ保護する権限を作成します。JDeveloperによって、リソース・タイプの定義とOPSS権限クラスoracle.adf.share.security.authorization.RestServicePermissionが照合されます(表16-4を参照)。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、 「RESTful Webサービスの追加機能」を参照してください。

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

• 「ビュー・オブジェクト・インスタンスからのADF RESTリソースの作成方法」の説明に従い、必要なRESTリソースを作成します。

• 「ADF RESTリソースで標準のHTTPアクションを公開する方法」の説明に従い、RESTリソースでセキュリティ保護する標準操作を有効にします。

• ADFセキュリティの構成ウィザードを実行してセキュリティを適用し、RESTリソース・メソッドがデフォルトで保護されるようにします。ウィザードの「認証タイプ」ページで、ViewControllerを選択するかわりに、「ADFセキュリティの有効化」で説明するように、「Webプロジェクト」ドロップダウンからデフォルトで生成されるRESTWebServiceを選択し、ADF RESTリソースを定義するADFビジネス・コンポーネント・モデル・プロジェクトのADFセキュリティを構成します。

• 「テスト・ユーザーとアプリケーション・ロールを関連付ける方法」で説明するように、1つ以上のテスト・ユーザーを作成し、リソース権限を付与する目的で作成したアプリケーション・ロールにそれらをマップします。

ADF RESTリソース権限を作成するには:

1. メイン・メニューで「アプリケーション」を選択し、「保護」→「リソース権限」を選択します。
2. セキュリティ・ポリシーの概要エディタの「リソース権限」ページで、「リソース・タイプ」ドロップダウンから「ADF RESTリソース」を選択します。
3. リソースを定義するモデル・プロジェクトを見つけて、これを「ソース・プロジェクト」フィールドに追加します。
4. 「リソース」列で、このリソースを選択します。
5. 「付与先」列で「権限受領者の追加」アイコンをクリックして「アプリケーション・ロールの追加」を選択します。その後、「アプリケーション・ロールの選択」ダイアログで、「追加」アイコンをクリックし、リソース権限を受け取るアプリケーション・ロールを選択します。たとえば、ManagerRoleというロールを作成した場合、ロールを選択し、「OK」をクリックします。
6. 「付与先」列で選択したロールに対して、「アクション」リストから必要なアクションを選択します。

   図16-22のように、概要エディタにアプリケーション・ロールに対するリソース権限が表示されます。

   図16-22 ADF RESTリソースに対する権限の作成

   
   「図16-22 ADF RESTリソースに対する権限の作成」の説明

ADF RESTリソースのデプロイ

JDeveloperの統合Oracle WebLogic ServerまたはスタンドアロンOracle WebLogic Serverに、RESTful Webサービスをデプロイできます。

JDeveloperの統合WebLogic ServerまたはスタンドアロンOracle WebLogic Serverに、RESTful Webサービスをデプロイできます。

統合WebLogic ServerへのADF RESTリソースのデプロイ方法

図16-23に示すように、RESTWebServiceプロジェクトで選択したデフォルトの「実行」オプションを使用して、JDeveloperの統合WebLogic ServerにRESTful Webサービスをデプロイできます。

図16-23 RESTWebServiceプロジェクトでのデフォルトの「実行」オプションの使用

統合WebLogic Serverにサービスをデプロイすると、「ログ」ウィンドウでターゲットURLをクリックして、JDeveloperのHTTPアナライザ・ツールでサービスにアクセスし、リクエスト(GETまたはPOSTなど)を作成する構文を使用してテストを実行できます。RESTful Webサービスのテストの詳細は、「統合WebLogic Serverを使用したADF RESTリソースのテスト」を参照してください。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。

• オプションで、デフォルト・ドメインの使用に関する項の説明に従い、統合WebLogic Server接続を作成し、デフォルト・ドメインを構成します。接続が作成されていない場合は、JDeveloperにより接続を作成するように要求されます。

• オプションで、デプロイされているRESTful Webサービスへのアクセスに使用されるターゲットURLに出現するように、RESTサーブレットのURLパターンおよびコンテキスト・ルートを編集します。URLパターンの編集の詳細は、「サービス・クライアントによって使用されるターゲットURLの変更に関する必知事項」を参照してください。

Webサービスを統合WebLogic Serverにデプロイするには:

1. 「アプリケーション」ウィンドウで、RESTWebServiceプロジェクト・ノードを選択し、右クリックして「実行」を選択します。

   統合WebLogic Serverが構成されていない場合は、JDeveloperによりデフォルト・ドメインを構成するように要求されます。

   JDeveloperによってアプリケーションがデプロイされ、Webサービスが開始されます。この間、これらのプロセスからの出力が「ログ」ウィンドウの実行中: IntegratedWebLogicServerタブに表示されます。図16-24に示すように、Webサービスが開始された後、ターゲットURLがログの下部に表示されます。

   図16-24 ターゲットURLが表示された「ログ」ウィンドウ

   
2. Webサービスのデプロイ後、「ログ」ウィンドウの実行中: IntegratedWebLogicServerタブで、ターゲットURLをクリックしてHTTPアナライザでWebサービスにアクセスし、JDeveloperでデプロイされているサービス上でテストを実行します。

   たとえば、「ログ」ウィンドウの実行中: IntegratedWebLogicServerタブに、クリック可能な次のターゲットURLが表示される場合があります。ここで、7101はポート番号で、その後にサービス・コンテキスト・ルートおよびRESTサーブレットのURLパターンが続きます。

   http://<hostname>:7101/RESTSample_App-context-root/rest

3. または、Webブラウザを使用してWebサービスを表示するには、「ログ」ウィンドウのターゲットURLをブラウザのアドレス・フィールドに貼り付けて、ADF RESTリソースを識別するようにURLを変更し、HTTP GETリクエストを発行します。

   たとえば、Departmentsリソースのバージョン11.1に対するGETリクエストは次のようになります。

   http://localhost:7101/RESTSample_App-context-root/rest/11.1/Departments

   構成したリソースのバージョン番号をURLに含めてください。この例では、図16-25に示すように、Departmentsリソースのバージョンとして11.1が構成されました。

   図16-25 ブラウザを使用したGET RESTリクエストの実行

   

スタンドアロンOracle WebLogic Serverのデプロイメントに対するADF RESTリソースのデプロイメント・プロファイルの構成方法

RESTful WebサービスをスタンドアロンOracle WebLogic Serverにデプロイする前に、ADF RESTリソースのデプロイメント・プロファイルを構成し、ADF RESTアプリケーションEARファイルの依存モジュールとしてRESTWebServiceプロジェクトを宣言する必要があります。このプロジェクトには、サービス・クライアントが確実にRESTリソースにアクセスできるようにするweb.xmlファイルおよびweblogic.xmlファイルが含まれています。

JDeveloperで、「EARデプロイメント・プロファイルのプロパティの編集」ダイアログの「アプリケーション・アセンブリ」ページを使用して、モジュールの依存性をアプリケーションに追加します。次に、ADF RESTアプリケーションをデプロイすると、選択したRESTWebServiceプロジェクトの2つのファイルが、デプロイされているEARファイルにWARファイルとしてアセンブルされます。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。

デプロイメント・プロファイルを構成するには:

1. RESTWebServiceプロジェクトをアプリケーションのEARデプロイメント・プロファイルの依存性として追加します。

   1. 「アプリケーション」ウィンドウで、アプリケーションを選択し、メイン・メニューから「アプリケーション」→「アプリケーション・プロパティ」を選択します。

   2. 「アプリケーション・プロパティ」ダイアログで、「デプロイメント」を選択してからアプリケーション・モジュール・デプロイメント・プロファイルを選択し、「プロファイルの編集」をクリックします。

   3. 「EARデプロイメント・プロファイルのプロパティの編集」ダイアログで、「アプリケーション・アセンブリ」を選択してRESTWebService.jprモジュールを開き、図16-26に示すようにプロジェクトを選択して「OK」をクリックします。

      図16-26 RESTWebServiceプロジェクトへのデプロイメントの依存性の追加

      

スタンドアロンOracle WebLogic ServerへのADF RESTリソースのデプロイ方法

スタンドアロンOracle WebLogic ServerにRESTful Webサービスをデプロイできます。

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。詳細は、「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。詳細は、「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。

• 「スタンドアロンOracle WebLogic Serverのデプロイメントに対するADF RESTリソースのデプロイメント・プロファイルの構成方法」の説明に従い、デプロイメント・プロファイルを変更して、依存性としてRESTWebServiceプロジェクトを追加し、Webサービスをデプロイします。

• Oracle Metadata Services (MDS)フレームワークによって提供されるカスタマイズ機能がアプリケーションで使用され、かつ形成定義がADF RESTリソースに適用されている場合は、「ADF RESTリソースのデプロイとMDSカスタマイズ・サポートに関する必知事項」の説明に従い、カスタマイズ機能のMARプロファイルを変更する必要があります。

• オプションで、デプロイされているRESTful Webサービスへのアクセスに使用されるターゲットURLに出現するように、RESTサーブレットのURLパターンおよびコンテキスト・ルートを編集します。URLパターンの編集の詳細は、「サービス・クライアントによって使用されるターゲットURLの変更に関する必知事項」を参照してください。

スタンドアロンOracle WebLogic ServerにWebサービスをデプロイするには:

1. 「アプリケーション」ウィンドウで、アプリケーションを選択し、メイン・メニューから「アプリケーション」→「デプロイ」→deployment_profile→server_nameを選択します。

   JDeveloperによってアプリケーションがデプロイされ、Webサービスが開始されます。この間、これらのプロセスからの出力が「ログ」ウィンドウの「デプロイメント」タブに表示されます。Webサービスの開始後、ターゲットURLも「ログ」ウィンドウに表示されます。

2. Webサービスのデプロイ後、「ログ」ウィンドウの「デプロイメント」を開き、ターゲットURLをクリックしてWebサービスにアクセスし、デプロイされているサービス上でテストを実行します。

サービス・クライアントによって使用されるターゲットURLの変更に関する必知事項

サービス・クライアントがサービスへのアクセスに使用するURLに出現するように、RESTサーブレットのURLパターンを編集できます。デフォルトでは、サーブレット・マッピングでURLパターンのrestを使用します。

http://localhost:7101/RESTSample_App-context-root/rest/11.1/Departments

サーブレット・マッピング・パターンを編集するには、「アプリケーション」ウィンドウで、RESTWebServiceプロジェクトを開いてweb.xmlファイルをダブルクリックし、図16-27に示すように、web.xmlファイルのエディタでRESTサーブレットのURLパターンを編集します。

図16-27 RESTサーブレット・マッピングのURLパターンの編集

「図16-27 RESTサーブレット・マッピングのURLパターンの編集」の説明

サービスにアクセスするURLに出現するように、コンテキスト・ルートも編集できます。デフォルトでは、コンテキスト・ルートはアプリケーション名に基づいており、必要に応じて短縮できます。コンテキスト・ルートを編集するには、「アプリケーション」ウィンドウで、RESTWebServiceプロジェクトを右クリックして「プロジェクト・プロパティ」を選択し、「プロジェクト・プロパティ」ダイアログで「Java EEアプリケーション」をクリックして、図16-28に示すように「Java EEコンテキスト・ルート」を編集して「OK」をクリックします。

図16-28 RESTWebServiceプロジェクトでのデフォルトのコンテキスト・ルートの編集

ADF RESTリソースのデプロイとMDSカスタマイズ・サポートに関する必知事項

モデル・プロジェクトでビュー・オブジェクト形成定義を定義し、アプリケーションでOracle Metadata Services (MDS)フレームワークの機能を使用してエンド・ユーザーのカスタマイズをサポートする場合は、userディレクトリに/persdef/を含むMARプロファイルを作成する必要があります。

ADF REST形成定義で共有するネームスペース・パスがMDSカスタマイズによって定義されるため、このことが必要になります。

<namespace path="/persdef/" metadata-store-usage="reposX"/>

この場合、adf-config.xmlファイルでは、対応するmetadata-store-usage要素に対してdeploy-target="true"を定義する必要があります。

カスタマイズしたメタデータをパッケージ化する方法の詳細は、「カスタマイズしたアプリケーションをパッケージ化してデプロイする方法」を参照してください。

統合WebLogic Serverを使用したADF RESTリソースのテスト

JDeveloperでは、統合WebLogic ServerにデプロイされたADF RESTリソースをテストできます。HTTPアナライザ(HTTPリクエストを作成する場合)、Webブラウザ(GETリクエスト用)またはcURLコマンドライン・ツールを使用します。

JDeveloperを使用して、RESTful Webサービスを統合WebLogic Serverにデプロイし、デプロイメント・プロセスによって生成されるターゲットURLを使用してADF RESTリソースにアクセスします。生成されたURLを使用すると、ADFモデル・プロジェクトのADF RESTリソースをテストするリクエストを実行できます。

次のいずれかの方法を使用して、必要なペイロードを返すようにデプロイされているサービスのURLを変更することによって、デプロイされているRESTful Webサービスをテストできます。

• JDeveloperのHTTPアナライザでHTTPリクエストの作成オプションを使用

• Webブラウザ(通常GETリクエストに限定されています)

• コマンド・ウィンドウからのcURLコマンド行ツール

  cURLはサードパーティ・ツールで、これをインストールして、コマンド・ウィンドウを使用してRESTリクエストを実行するように構成できます。

デプロイされているRESTful Webサービスを使用したADFリソースをテストするには、ADF RESTランタイムによって有効化されているREST API構文を理解していることが必要です。ただし、このドキュメントの手順を使用すると、基本的なGETリクエストを実行してリソース・コレクションを表示できます。

たとえば、すべてのリソースのすべてのバージョンを返すGETリクエストは次のようになります。

http://<server>/<context-root>/rest

たとえば、特定のバージョンのすべてのリソースを返すGETリクエストは次のようになります。

http://<server>/<context-root>/rest/<versionID>/describe

たとえば、特定のリソース・コレクションの特定のバージョンを返すGETリクエストは次のようになります。

http://<server>/<context-root>/rest/<versionID>/<resourceName>

始める前に:

ADF RESTフレームワークによって、アプリケーション・モジュールがどのようにサポートされ、サービス・クライアントのデータ行アクセスやサービス操作の実行がどのように有効化されるかについて理解しておくと役立ちます。「RESTful WebサービスおよびADFビジネス・コンポーネントについて」を参照してください。

ADF RESTフレームワークおよびHTTPメソッドを使用してAPIコールを行う構文も理解しておくと役立つ場合があります。「ADF RESTful Webサービスの消費」を参照してください。

また、ADF RESTリソースに依存する他のOracle ADF機能を理解しておくと役立つ場合があります。「RESTful Webサービスの追加機能」を参照してください。

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

• 「アプリケーション・モジュールを使用したADF RESTリソースの作成」の説明に従い、必要なRESTリソースを作成します。

• 「統合WebLogic ServerへのADF RESTリソースのデプロイ方法」の説明に従い、ADF RESTリソースを統合WebLogic Serverにデプロイします。

• RESTリソースに対してRESTful Webサービス操作をテストするためのツールを使用するには、コマンド行ツールcURLをダウンロードします。

HTTP GETを使用してWebサービスをテストするには:

1. JDeveloperのHTTPアナライザを使用してテストするには、メイン・メニューから「ツール」→「HTTPアナライザ」を選択し、HTTPアナライザの「ログ」ウィンドウで「新規HTTPリクエストの作成」を選択し、HTTPアナライザの「HTTPコンテンツ」タブを選択して、「ログ」ウィンドウからコピーしたターゲットURLを「URL」フィールドに貼り付け、RESTリソースを識別するURLを変更し、対象の「メソッド」を選択して「リクエストの送信」をクリックします。

   構成したリソースのバージョン番号をURLに含めてください。この例では、図16-29に示すように、11.1はDepartmentsリソースのアクセスに使用されるリリース名バージョン識別子です。

   図16-29 HTTPアナライザを使用したGET RESTリクエストの実行

   
   「図16-29 HTTPアナライザを使用したGET RESTリクエストの実行」の説明

   HTTPアナライザではSOAP、標準のHTTPおよびRESTタイプのリクエストがサポートされることに注意してください。ただし、汎用RESTful Webサービスを定義するためにHTTPアナライザに通常指定するWADLでは、ADF RESTリソースの記述形式はサポートされていません。そのため、HTTPアナライザを使用して、デプロイされているADF RESTリソースをテストする場合は、RESTリクエストではなく、新規のHTTPタイプのリクエストを作成する必要があります。

2. サードパーティのcURLコマンド行ツールを使用してテストするには、コマンド・プロンプトを開き、次のようなRESTリソースに対するcURLコマンドを入力します。ここで、-vはcURLによって送信された内容を表示するオプションで、-Xはリクエスト・オプションです。

   curl -v -X GET http://127.0.0.1:7101/RESTDemo/rest/11.1/Departments

   構成したリソースのバージョン番号をURLに含めてください。この例では、図16-30に示すように、11.1はDepartmentsリソースのアクセスに使用されるリリース名バージョン識別子です。

   図16-30 cURLを使用したRESTリクエストの実行