Oracle® Fusion Middleware

Oracle WebLogic Server RESTful Webサービスの開発と保護

12c (12.1.2)

E47996-02(原本部品番号:E28162-03)

2014年2月

ソフトウェア開発者を対象に、Java API for RESTful Web Services (JAX-RS)を使用して、Representational State Transfer (REST)アーキテクチャ・スタイルに従ったWebLogic Webサービスを開発する方法について説明するドキュメントです。

Oracle Fusion Middleware Oracle WebLogic Server RESTful Webサービスの開発と保護, 12c (12.1.2)

E47996-02

Copyright © 2013, 2014 Oracle and/or its affiliates. All rights reserved.

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション(人的傷害を発生させる可能性があるアプリケーションを含む)への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性(redundancy)、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

目次

タイトルおよび著作権情報

はじめに

- ドキュメントのアクセシビリティについて

- 表記規則

このガイドでの新しい情報

- 12c (12.1.2)での新機能と変更された機能

1 RESTful Webサービスの概要

- RESTアーキテクチャ・スタイルの概要

- RESTful Webサービスとは

- WebLogic ServerでのRESTful Webサービスの開発の標準サポート

- RESTful Webサービスの実装のロードマップ

- RESTful WebサービスのOracle WebLogic Server 10.3.xから12.1.xへのアップグレード

- RESTful Webサービスの詳細

2 RESTful Webサービスの開発

- RESTful Webサービスの開発について

- RESTful Webサービスを開発するタスクの概要

- RESTful Webサービスの例

- ルート・リソース・クラスの定義

- ルート・リソースおよびサブリソースの相対URIの定義

- リソース・クラスの相対URI (@Path)の定義方法

- サブリソースの相対URI (@Path)の定義方法

- 実行時の処理: 基底URIの構成方法

- 受信HTTPリクエストのJavaメソッドへのマッピング

- Jerseyブックマーク・サンプルについて

- リソースの表現の送信方法(@GET)

- リソースの表現の作成または更新方法(@PUT)

- リソースの表現の削除方法(@DELETE)

- リソースの表現でのアクションの作成、更新または実行方法(@POST)

- リクエスト・メッセージおよびレスポンス・メッセージのメディア・タイプのカスタマイズ

- リクエスト・メッセージのメディア・タイプのカスタマイズ方法(@Consumes)

- レスポンス・メッセージのメディア・タイプのカスタマイズ方法(@Produces)

- 実行時の処理: レスポンス・メッセージに対するリソース・メソッドの選択方法

- リクエスト・メッセージからの情報の抽出

- リクエストURIからの変数情報の抽出方法(@PathParam)

- リクエスト・パラメータの抽出方法(@QueryParam)

- DefaultValueの定義方法(@DefaultValue)

- パラメータ値のエンコードの有効化(@Encode)

- カスタム・レスポンス・メッセージの構築

- エンティティ・プロバイダを使用したHTTPリクエストおよびレスポンスのエンティティ本文のマッピング

- アプリケーション・コンテキストのアクセス

- URIの構築

- 条件付きGETの使用

- WADLのアクセス

- 高度なRESTful Webサービス・タスク

3 RESTful Webサービス・クライアントの開発

- RESTful Webサービス・クライアントの開発について

- RESTful Webサービス・クライアントを開発するタスクの概要

- RESTful Webサービス・クライアントの例

- クライアント・インスタンスの作成および構成

- Webリソース・インスタンスの作成

- リソースへのリクエストの送信

- リクエストの構築方法

- HTTPリクエストの送信方法

- 問合せパラメータを渡す方法

- Acceptヘッダーの構成方法

- カスタム・ヘッダーの追加方法

- リクエスト・エンティティの構成方法

- リソースからのレスポンスの受信

- リクエストのステータスへのアクセス方法

- レスポンス・エンティティの取得方法

- 高度なRESTful Webサービス・クライアント・タスク

- スタンドアロン・クライアントからのRESTful Webサービスの呼出し

4 RESTful Webサービスのパッケージ化とデプロイ

- RESTful Webサービスのパッケージ化とデプロイメントについて

- アプリケーション・サブクラスとのパッケージ化

- サーブレットとのパッケージ化

- RESTful Webサービス・アプリケーションのサーブレット3.0とのパッケージ化方法

- アプリケーション・サブクラスのあるweb.xmlを使用したRESTful Webサービス・アプリケーションのパッケージ化

- アプリケーション・サブクラスのないweb.xmlを使用したRESTful Webサービス・アプリケーションのパッケージ化

- RESTful Webサービス・アプリケーションの3.0以前のサーブレットとのパッケージ化方法

- デフォルト・リソースとしてのパッケージ化

5 RESTful Webサービスとクライアントの保護

- RESTful Webサービス・セキュリティの概要

- OWSMポリシーを使用したRESTful Webサービスとクライアントの保護

- web.xmlを使用したRESTful Webサービスの保護

- SecurityContextを使用したRESTful Webサービスの保護

- Javaセキュリティ・アノテーションを使用したRESTful Webサービスの保護

6 RESTful Webサービスのテスト

7 RESTful Webサービスとクライアントの監視

- RESTful Webサービスの監視について

- Enterprise Manager Fusion Middleware Controlを使用したRESTful Webサービスの監視

- 管理コンソールを使用したRESTful Webサービスの監視

- WLSTを使用したRESTful Webサービスの監視

- トレース機能の有効化

- サーバー全体のトレース機能の有効化方法

- リクエストごとのトレース機能の有効化方法

A Jersey JAX-RS RIのバージョンの更新

- Jersey JAX-RS RIのバージョンの更新について

- アプリケーション・レベルでのJersey JAX-RS RIのバージョンの更新

- EARファイルでのJersey JAX-RS RIのバージョンの更新方法

- WARファイルでのJersey JAX-RS RIのバージョンの更新方法

はじめに

ここでは、このガイド『Oracle WebLogic Server RESTful Webサービスの開発と保護』で使用されるドキュメントのアクセシビリティ機能および表記規則について説明します。

ドキュメントのアクセシビリティについて

Oracleのアクセシビリティについての詳細情報は、Oracle Accessibility ProgramのWebサイトhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=docaccを参照してください。

Oracleサポートへのアクセス

Oracleのお客様は、My Oracle Supportにアクセスして電子サポートを受けることができます。詳細情報はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=infoか、聴覚に障害のあるお客様はhttp://www.oracle.com/pls/topic/lookup?ctx=acc&id=trsを参照してください。

表記規則

このマニュアルでは次の表記規則を使用します。

規則

意味

太字

太字は、操作に関連するGraphical User Interface要素、または本文中で定義されている用語および用語集に記載されている用語を示します。

斜体

イタリックは、ユーザーが特定の値を指定するプレースホルダー変数を示します。

固定幅フォント

固定幅フォントは、段落内のコマンド、URL、サンプル内のコード、画面に表示されるテキスト、または入力するテキストを示します。

このガイドでの新しい情報

次のトピックでは、RESTful Webサービスの新機能と変更された機能を紹介するとともに、追加情報の参照箇所を示します。このドキュメントは当初、Oracle Fusion Middleware 12cリリース1 (12.1.1)でリリースされていました。

12c (12.1.2)での新機能と変更された機能

Oracle Fusion Middleware 12c (12.1.2)のこのドキュメントでは、次の新機能と変更された機能について説明します。

- Oracle Web Services Manager (OWSM)ポリシーを使用したRESTful Webサービスの保護。詳細は、「OWSMポリシーを使用したRESTful Webサービスとクライアントの保護」を参照してください。

- 基本的なRESTful Webサービス・クライアント側機能をサポートする新しいスタンドアロンWebサービス・クライアントのJARファイルと、Oracle Web Services Manager (OWSM)のセキュリティ・ポリシーのサポート。「スタンドアロン・クライアントからのRESTful Webサービスの呼出し」を参照してください。

1 RESTful Webサービスの概要

この章では、Java API for RESTful Web Services (JAX-RS)を使用して、Representational State Transfer (REST)アーキテクチャ・スタイルに従ったWebLogic Webサービスの開発の概要について説明します。

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

- RESTアーキテクチャ・スタイルの概要

- RESTful Webサービスとは

- WebLogic ServerでのRESTful Webサービスの開発の標準サポート

- RESTful Webサービスの実装のロードマップ

- RESTful Webサービスの詳細

RESTアーキテクチャ・スタイルの概要

RESTとは、Simple Object Access Protocol (SOAP)のように追加のメッセージ層を使用することなく、HTTPなどの標準化されたインタフェースでデータを転送するためのシンプルなインタフェースを記述したものです。RESTはアーキテクチャ・スタイルであり、ツールキットではありません。リソースまたは特定の情報のソース(データおよび機能)として表示される、ステートレスなサービスを作成するための設計ルールのセットを提供します。各リソースは一意のURI (Uniform Resource Identifier)で識別されます。

クライアントはURI、標準化されたメソッドの固定セットを使用してリソースにアクセスし、リソースの表現が戻されます。リソースの表現は、一般的にリソースの現在または意図された状態を取得するドキュメントです。クライアントは、新しいリソース表現を受け取るたびに転送状態に設定されます。

表1-1に、アプリケーションがRESTfulだと見なされるために従う必要のある、RESTアーキテクチャ・スタイルにより定義された制約のセットを定義します。

表1-1 RESTアーキテクチャ・スタイルの制約

制約

説明

アドレス可能度

URI (Uniform Resource Identifier)を使用してすべてのリソースを識別します。英語では、URIは名詞と同じです。

共通インタフェース

HTTPメソッド(GET、POST、PUT、DELETE)などの共通インタフェースを使用して、リソースへのアクセスを可能にします。英語の類推を適用して、これらのメソッドは動詞と見なされ、名前付けされたリソースに適用できるアクションを説明します。

クライアント・サーバー・アーキテクチャ

クライアントとサーバーを、インタフェース要件とデータ・ストレージ要件とに分割します。このアーキテクチャは、サーバー・コンポーネントを簡略化することで、複数のプラットフォーム間でのユーザー・インタフェースの移植性と拡張性を高めます。

ステートレスな相互作用

ステートレスな通信プロトコルを使用します。通常はHypertext Transport Protocol (HTTP)です。すべてのリクエストは、特定のリクエストに必要なすべての情報を含む必要があります。セッション状態はクライアントにのみ保存されます。

この相互作用のスタイルにより、次のことが向上します。

- 可視性—1つのリクエストでリクエストのすべての詳細が提供されます。

- 信頼性—部分的な障害からの回復を容易にします。

- 拡張性—状態を保存する必要がないので、サーバーは迅速にリソースを解放できます。

キャッシュ可能

クライアントのレスポンスのキャッシングを可能にします。レスポンスはキャッシュ可能かキャッシュ不可能かに識別される必要があります。キャッシングにより、一部の相互作用は必要なくなり、効率性、拡張性、および認識されるパフォーマンスが向上します。

階層化システム

クライアントがエンド・サーバーに直接接続するのではなく中間サーバーに接続できるようにします(クライアントは認識しません)。中間サーバーの使用は、ロード・バランシングと共有キャッシングを提供することで、システムの拡張性を向上させます。

RESTful Webサービスとは

RESTful Webサービスは、REST原則に従って構築され、それによりWebで適切に動作するように設計されたサービスです。

RESTful Webサービスは、表1-1に定義されたアーキテクチャ・スタイル制約に従います。通常、RESTful WebサービスはHTTPプロトコル上に構築され、GET、POST、PUT、DELETEなどの共通HTTPメソッドにマップされる操作を実装し、リソースをそれぞれ作成、取得、更新、削除します。

WebLogic ServerでのRESTful Webサービスの開発の標準サポート

JAX-RSは、RESTアーキテクチャ・スタイルに従ったWebサービスの作成のサポートを提供します。JAX-RSはアノテーションを使用して、RESTful Webサービスの開発を簡略化します。アノテーションをWebサービスに追加するだけで、リソースと、そのリソースで実行できるアクションを定義できます。JAX-RSはJava EE 6 Full Profile の一部で、Contexts and Dependency Injection (CDI) for the Java EE Platform (CDI)、Enterprise JavaBeans (EJB)テクノロジおよびJavaサーブレット・テクノロジと統合されています。

WebLogic Serverは、JSR-311 JAX-RS 1.1仕様(https://jcp.org/en/jsr/summary?id=311で定義)の製品レベル品質を実装したJersey 1.13 JAX-RS Reference Implementation (RI)をサポートしています。必要に応じて、Jersey JAX-RS RIのより新しいバージョンを使用できます。付録A「Jersey JAX-RS RIのバージョンの更新」を参照してください。

Jersey 1.13 JAX-RS RIバンドルには次の機能が含まれます。

- Jersey

- JAX-RS API

- JSON処理およびストリーミング

JAX-RSとサンプルの詳細は、「RESTful Webサービスの詳細」を参照してください。

RESTful Webサービスの実装のロードマップ

次の表に、WebLogic Serverを使用して、RESTful Webサービスおよびクライアントを開発、パッケージ化、デプロイ、呼び出し、および監視するための共通タスクのロードマップを示します。

表1-2 RESTful Webサービスの実装のロードマップ

参照する章

内容

第2章「RESTful Webサービスの開発」

RESTful Webサービスを開発します。

第3章「RESTful Webサービス・クライアントの開発」

JerseyクライアントAPIを使用して、RESTful Webサービスを呼び出すクライアントを開発します。

第4章「RESTful Webサービスのパッケージ化とデプロイ」

RESTful Webサービスをパッケージ化およびとデプロイします。

第5章「RESTful Webサービスとクライアントの保護」

RESTful Webサービスを保護します。

第6章「RESTful Webサービスのテスト」

RESTful Webサービスをテストします。

第7章「RESTful Webサービスとクライアントの監視」

RESTful Webサービスを監視します。

付録A「Jersey JAX-RS RIのバージョンの更新」

RESTful Webサービス・アプリケーションで使用するJersey JAX-RS Reference Implementation (RI)のバージョンを更新します。

RESTful WebサービスのOracle WebLogic Server 10.3.xから12.1.xへのアップグレード

Oracle WebLogic Server 11gリリース1 (10.3.x)環境で構築したRESTful Webサービスを、Oracle WebLogic Server 12cリリース1 (12.1.x)環境で実行するようにアップグレードできます。詳細な手順は、『Oracle WebLogic Serverのアップグレード』の10.3.x RESTful Webサービス(JAX-RS)の12.1.xへのアップグレードに関する項を参照してください。

RESTful Webサービスの詳細

表1-2に、RESTful Webサービスの詳細に関するリソースのリストを示します。

表1-3 詳細に関するリソース

リソース

リンク

Jersey 1.13 User Guide

https://jersey.java.net/nonav/documentation/1.13/user-guide.html

RESTful Webサービス(JAX-RS)サンプル

『Oracle WebLogic Serverの理解』のサンプル・アプリケーションとコード例に関する項

Java EE 6チュートリアル-JAX-RSを使用したRESTful Webサービスの構築

http://docs.oracle.com/javaee/6/tutorial/doc/giepu.html

Jerseyサイト

https://jersey.java.net

JerseyプロジェクトのWikiコミュニティ

https://wikis.oracle.com/display/Jersey/Main

Jersey 1.13 API Javadoc

https://jersey.java.net/nonav/apidocs/1.13/jersey/overview-summary.html

JSR-311 JAX-RS仕様

https://jcp.org/en/jsr/summary?id=311

JSR-311 JAX-RSプロジェクト

https://jsr311.java.net/

JSR-311 JAX-RS API Javadoc

https://jsr311.java.net/nonav/javadoc/index.html

『Architectural Styles and the Design of Network-based Software Architectures』 (Roy Fieldingの論文)の「Representational State Transfer (REST)」

http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm

2 RESTful Webサービスの開発

この章では、Java API for RESTful Web Services (JAX-RS)を使用して、Representational State Transfer (REST)アーキテクチャ・スタイルに従ったWebLogic Webサービスを開発する方法について説明します。

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

- RESTful Webサービスの開発について

- ルート・リソース・クラスの定義

- ルート・リソースおよびサブリソースの相対URIの定義

- 受信HTTPリクエストのJavaメソッドへのマッピング

- リクエスト・メッセージおよびレスポンス・メッセージのメディア・タイプのカスタマイズ

- リクエスト・メッセージからの情報の抽出

- パラメータ値のエンコードの有効化(@Encode)

- カスタム・レスポンス・メッセージの構築

- エンティティ・プロバイダを使用したHTTPリクエストおよびレスポンスのエンティティ本文のマッピング

- アプリケーション・コンテキストのアクセス

- URIの構築

- 条件付きGETの使用

- WADLのアクセス

- 高度なRESTful Webサービス・タスク

Oracle JDeveloperを使用したRESTful Webサービス・クライアントの開発の詳細は、『Oracle JDeveloperによるアプリケーションの開発』のRESTful Webサービスおよびクライアントの作成に関する項を参照してください。

RESTful Webサービスの開発について

JAX-RSは、アノテーションを使用して、RESTful Webサービスの開発を簡略化するJavaプログラミング言語APIです。JAX-RSアノテーションは実行時アノテーションです。JAX-RSリソース・クラスを含むJava EEアプリケーション・アーカイブをWebLogic Serverにデプロイする場合(第4章「RESTful Webサービスのパッケージ化とデプロイ」を参照)、ランタイムはリソースを構成し、ヘルパー・クラスおよびアーティファクトを生成し、リソースをクライアントに公開します。

以下の項で、RESTful Webサービスの開発についての詳細を説明します。

- RESTful Webサービスを開発するタスクの概要

- RESTful Webサービスの例

RESTful Webサービスを開発するタスクの概要

表2-1に、JAX-RSアノテーションを使用してRESTful Webサービスを開発するのに必要なタスクのサブセットの概要を示します。高度なタスクの詳細は、「高度なRESTful Webサービス・タスク」を参照してください。

以下で説明する開発タスクに加えて、javax.ws.rs.core.Applicationを拡張するクラスを作成して、RESTful Webサービス・アプリケーション・デプロイメントのコンポーネントを定義し、追加のメタデータを提供できる場合があります。詳細は、「アプリケーション・サブクラスとのパッケージ化」を参照してください。

表2-1 RESTful Webサービスを開発するタスクの概要

タスク

詳細情報

ルート・リソース・クラスを定義します。

ルート・リソース・クラスの定義

@Pathアノテーションを使用して、ルート・リソースの相対URIとそのメソッドを定義します。

変数を使用して@Pathアノテーションを定義する場合、@PathParamアノテーションを使用して、値をそれに割り当てることができます。

ルート・リソースおよびサブリソースの相対URIの定義

@GET、@POST、@PUTまたは@DELETEを使用して、受信HTTPリクエストをJavaメソッドにマッピングして、それぞれリソースを取得、作成、更新または削除します。

受信HTTPリクエストのJavaメソッドへのマッピング

必要に応じて、リクエストおよびレスポンス・メッセージをカスタマイズして、リソースが生成および消費できるMIMEメディア・タイプを指定します。

リクエスト・メッセージおよびレスポンス・メッセージのメディア・タイプのカスタマイズ

リクエストから情報を抽出します。

リクエスト・メッセージからの情報の抽出

レスポンス・コードをカスタマイズする、または追加メタデータを含めるためのカスタム・レスポンス・メッセージを構築します。

カスタム・レスポンス・メッセージの構築

アプリケーション・デプロイメント・コンテキストまたは個別リクエストのコンテキストに関する情報にアクセスします。

アプリケーション・コンテキストのアクセス

新規のリソースURIを構築、または既存のリソースURIを拡張します。

URIの構築

GETリクエストの処理前に1つ以上の前条件を評価することで、潜在的に帯域幅を縮小し、サーバー・パフォーマンスを改善します。

条件付きGETの使用

WADLにアクセスします。

WADLのアクセス

RESTful Webサービスを保護します。

第5章「RESTful Webサービスとクライアントの保護」

RESTful Webサービスの例

例2-1に、RESTful Webサービスの簡単な例を示します。この例の内容は次のとおりです。

- helloWorldクラスは/helloworldとして定義された相対URIパスを含むリソースです。実行時に、WARファイルのコンテキスト・ルートがhttp://examples.comとして定義されている場合、リソースにアクセスするためのフルURIはhttp://examples.com/helloworldです。詳細は、「ルート・リソースおよびサブリソースの相対URIの定義」を参照してください。

- sayHelloメソッドはHTTP GETメソッドをサポートします。詳細は、「受信HTTPリクエストのJavaメソッドへのマッピング」を参照してください。

- sayHelloメソッドはMIMEメディア・タイプtext/plainのコンテンツを生成します。詳細は、「リクエスト・メッセージおよびレスポンス・メッセージのメディア・タイプのカスタマイズ」を参照してください。

追加の例を「RESTful Webサービスの詳細」に示します。

例2-1 簡単なRESTful Webサービスの例

package samples.helloworld;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;

// Specifies the path to the RESTful service
@Path("/helloworld")
public class helloWorld {

// Specifies that the method processes HTTP GET requests
@GET
@Produces("text/plain")
public String sayHello() {
return "Hello World!";
}
}

ルート・リソース・クラスの定義

ルート・リソース・クラスは、次の条件の1つまたは両方がtrueであるPlain Old Java Object (POJO)です。

- @Pathでアノテーションが付けられている。詳細は、「ルート・リソースおよびサブリソースの相対URIの定義」を参照してください。

- 少なくとも1つのメソッドが@Path、または@GET、@POST、@PUT、@DELETEなどのリクエスト・メソッド指定子によりアノテーションが付けられている。リソース・メソッドはリクエスト・メソッド指定子を使用してアノテーションが付けられたリソース・クラスのメソッドです。詳細は、「受信HTTPリクエストのJavaメソッドへのマッピング」を参照してください。

ルート・リソースおよびサブリソースの相対URIの定義

リソースのクラス・レベルでjavax.ws.rs.Pathアノテーションを追加し、RESTful Webサービスの相対URIを定義します。このようなクラスはルート・リソース・クラスと呼ばれます。特定の機能をグループ化するためのサブリソースを定義するため、@Pathもルート・リソース・クラスのメソッドに追加できます。

次の項では、ルート・リソースおよびサブリソースの相対URIの定義方法について説明します。

- リソース・クラスの相対URI (@Path)の定義方法

- サブリソースの相対URI (@Path)の定義方法

- 実行時の処理: 基底URIの構成方法

リソース・クラスの相対URI (@Path)の定義方法

@Pathアノテーションはリソースの相対URIを定義し、定数または変数(URIパス・テンプレートとして参照される)として定義できます。@Pathアノテーションをクラスまたはメソッド・レベルで追加できます。

URIを定数値として定義するには、定数値を@Pathアノテーションに渡します。先頭と末尾のスラッシュ(/)はオプションです。

例2-2では、リソース・クラスの相対URIが定数値/helloworldとして定義されます。

例2-2 相対URIの定数値としての定義

package samples.helloworld;
import javax.ws.rs.Path;
...
// Specifies the path to the RESTful service
@Path("/helloworld")
public class helloWorld {. . .}

URIをURIパス・テンプレートとして定義するには、1つまたは複数の変数値を@Pathアノテーションに中カッコで囲んで渡します。すると、javax.ws.rs.PathParamアノテーションを使用して、@Pathアノテーションで定義されたリクエストURIから変数情報を抽出でき、メソッド・パラメータの値を初期化できます(変数情報をリクエストURI (@PathParam)から抽出する方法を参照)。

例2-3では、リソース・クラスの相対URIが、中かっこで囲まれた変数を使用して定義されます。たとえば、/users/{username}です。

例2-3 相対URIの変数値としての定義

package samples.helloworld;

import javax.ws.rs.Path;
...
// Specifies the path to the RESTful service
@Path("/users/{username}")
public class helloWorld {. . .}
}

変数をさらにカスタマイズするには、デフォルトの正規表現の"[^/]+?"を、変数定義の一部として必要な正規表現を指定することでオーバーライドできます。以下に例を示します。

@Path("users/{username: [a-zA-Z][a-zA-Z_0-9]}")

この例では、username変数は、1つの大文字または小文字で始まり、ゼロまたはそれ以上の英数字またはアンダースコア文字が続くユーザー名にのみ一致します。ユーザー名が要件に一致しない場合、404 (Not Found)レスポンスがクライアントに送信されます。

@Pathアノテーションの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/Path.htmlを参照してください。

サブリソースの相対URI (@Path)の定義方法

javax.ws.rs.Pathアノテーションをリソースのメソッドに追加して、サブリソースを定義します。サブリソースによってユーザーは、リソースに対する特定の機能をグループ化できます。

例2-3で、URIのリクエスト・パスがusers/listの場合は、getUserListサブリソース・メソッドが照合され、ユーザーのリストが返されます。

例2-4 サブリソースの定義

package samples.helloworld;

import javax.ws.rs.GET;
import javax.ws.rs.Path;

// Specifies the path to the RESTful service
@Path("/users")
public class UserResource {
. . .
@GET
@Path("/list")
public String getUserList() {
...
}
}

実行時の処理: 基底URIの構成方法

基底URIは次のように構成されます。

http://myHostName/contextPath/servletURI/resourceURI

- myHostName— Web サーバーにマップされるDNS名。これを、WebLogic Serverを実行しているマシン名とリクエストのリスニングに使用するポートを指定するhost:portで置き換えることができます。

- contextPath—スタンドアロンWebアプリケーションの名前。Webアプリケーション名はEARファイル内のMETA-INF/application.xmlデプロイメント記述子またはWARファイルのweblogic.xmlデプロイメント記述子に指定されます。指定されない場合、デフォルトはWARファイルから.war拡張子を取り去った名前です。詳細は、『Oracle WebLogic Server Webアプリケーション、サーブレット、JSPの開発』のcontext-rootに関する項を参照してください。

- servletURI—サーブレットのコンテキスト・パスの基底URIです。このパスは、表4-1で定義されているパッケージ化オプションの一部として構成されます。特に、次を実行して、サーブレットのコンテキスト・パスを定義できます。

- web.xmlデプロイメント記述子を更新して、サーブレット・マッピングを定義します。

- javax.ws.rs.ApplicationPathアノテーションをjavax.ws.rs.core.Applicationを拡張するクラスに追加します(定義されている場合)。

サーブレットのコンテキスト・パスが上記のオプションの両方を使用して構成されている場合、サーブレット・マッピングが優先されます。上記のオプションのいずれかを使用して、構成内にサーブレットのコンテキスト・パスが構成されない場合、WebLogic ServerはデフォルトのRESTful Webサービス・アプリケーションのコンテキスト・パスresourcesを提供します。詳細は、「RESTful Webサービスのパッケージ化とデプロイメントについて」を参照してください。

- resourceURI—リソースまたはサブリソースに対して指定された@Path値。このパスは、複数のリソースおよびサブリソースの@Path値で構成されることがあります。

例2-2では、WARファイルに対するコンテキスト・パスがrestとして定義されていて、サーブレットのデフォルトURI (resources)が有効な場合、実行時のリソースにアクセスする基底URIはhttp://myServer:7001/rest/resources/helloworldです。

例2-3では、実行時に、基底URIは変数に対して指定された値に基づき構成されます。たとえば、ユーザーがユーザー名としてjohnsmithを入力した場合、リソースにアクセスする基底URIはhttp://myServer:7001/rest/resources/users/johnsmithです。

受信HTTPリクエストのJavaメソッドへのマッピング

JAX-RSはJavaアノテーションを使用して受信HTTPリクエストをJavaメソッドにマッピングします。表2-2に、同じような名前が付けられたHTTPメソッドにマッピングする、使用可能なアノテーションを示します。

表2-2 HTTPリクエストのJavaメソッドへのマッピング用javax.ws.rsアノテーション

アノテーション

説明

多重呼出し不変

@GET

URIにより識別されるリソースの表現をクライアントに送信します。フォーマットは、HTML、プレーン・テキスト、JPEGなどです。「リソースの表現の送信方法(@GET)」を参照してください。

はい

@PUT

URIで識別された特定のリソースの表現を作成または更新します。「リソースの表現の作成または更新方法(@PUT)」を参照してください。

はい

@DELETE

URIで識別されたリソースの表現を削除します。「リソースの表現の削除方法(@DELETE)」を参照してください。

はい

@POST

URIで識別された特定のリソースの表現でのアクションを作成、更新、または実行します。「リソースの表現でのアクションの作成、更新または実行方法(@POST)」を参照してください。

いいえ

@HEAD

レスポンス・ヘッダーのみを戻し、実際のリソースは戻しません(つまり、メッセージ本文はありません)。これは、実際にダウンロードせずにリソースの特性を確認して、バンド幅を節約するのに役に立ちます。詳細は、http://docs.oracle.com/javaee/6/api/index.html?j7avax/ws/rs/HEAD.htmlを参照してください。

HEADメソッドは明示的に実装されないと、自動的に実装されます。この場合、ランタイムは実装されたGETメソッド(存在する場合)を呼び出し、レスポンス・エンティティ(設定されている場合)を無視します。

はい

@OPTIONS

URIで識別された特定のリソースのリクエスト/レスポンス・チェーンで使用可能な通信オプションを戻します。Allowレスポンス・ヘッダーはリソースでサポートされるHTTPメソッドのセットに設定され、WADLファイルが戻されます。詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/OPTIONS.htmlを参照してください。

OPTIONSメソッドは明示的に実装されないと、自動的に実装されます。このケースでは、Allowレスポンス・ヘッダーはリソースでサポートされるHTTPメソッドのセットに設定され、リソースを記述するWADLが戻されます。

はい

@HttpMethod

アノテーションの付けられたメソッドを使用してHTTPリクエストを処理する必要があることを示します。詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/HttpMethod.htmlを参照してください。

該当なし

次の項では、HTTPリクエストのJavaメソッドへのマッピングに使用されるJAX-RSアノテーションの詳細について説明します。

- Jerseyブックマーク・サンプルについて

- リソースの表現の送信方法(@GET)

- リソースの表現の作成または更新方法(@PUT)

- リソースの表現の削除方法(@DELETE)

- リソースの表現でのアクションの作成、更新または実行方法(@POST)

Jerseyブックマーク・サンプルについて

次の項に示す例は、Jersey 1.13 JAX-RS RIとともに提供されるブックマーク・サンプルからの抜粋です。ブックマーク・サンプルは、ユーザーやブラウザが設定したブックマークを保持するWebアプリケーションを提供します。

サンプル内のリソース・クラス、関連URIパス、各クラスにより実証されるHTTPメソッドについて、次の表にまとめます。

表2-3 Jerseyブックマーク・サンプルについて

リソース・クラス

URIパス

実証されるHTTPメソッド

UsersResource

/users/

GET

UserResource

/users/{userid}

GET、PUT、DELETE

BookmarksResource

/users/{userid}/bookmarks

GET、POST

BookmarkResource

/users/{userid}/bookmarks/{bmid}

GET、PUT、DELETE

ブックマーク・サンプルおよびその他のJerseyサンプルは、次のいずれかの方法でアクセスできます。

- https://jersey.java.netで、Jersey 1.13ソフトウェアをダウンロード

- https://maven.java.net/content/repositories/releases/com/sun/jersey/samplesで、Mavenリポジトリを参照

リソースの表現の送信方法(@GET)

javax.ws.rs.GETアノテーションは、URIにより識別されるリソースの表現をクライアントに送信します。レスポンスのエンティティ本文で戻される形式または表現は、HTML、プレーン・テキスト、JPEGなどです。@GETアノテーションの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/GET.htmlを参照してください。

例2-5では、Jerseyブックマーク・サンプルのBookmarksResourceクラスからの、アノテーションが付けられたJavaメソッドgetBookmarkAsJsonArrayが、HTTP GETリクエストを処理します。Jerseyブックマーク・サンプルの詳細は、「Jerseyブックマーク・サンプルについて」を参照してください。

例2-5 HTTP GETリクエストのJavaメソッドへのマッピング(BookmarksResourceクラス)

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
...
public class BookmarksResource {
...
@Path("{bmid: .+}")
public BookmarkResource getBookmark(@PathParam("bmid") String bmid) {
return new BookmarkResource(uriInfo, em,
userResource.getUserEntity(), bmid);
}
@GET
@Produces("application/json")
public JSONArray getBookmarksAsJsonArray() {
JSONArray uriArray = new JSONArray();
for (BookmarkEntity bookmarkEntity : getBookmarks()) {
UriBuilder ub = uriInfo.getAbsolutePathBuilder();
URI bookmarkUri = ub.
path(bookmarkEntity.getBookmarkEntityPK().getBmid()).
build();
uriArray.put(bookmarkUri.toASCIIString());
}
return uriArray;
}
...
}

例2-6では、Jerseyブックマーク・サンプルのBookmarkResourceクラスからの、アノテーションが付けられたJavaメソッドgetBookmarkが、HTTP GETリクエストを処理します。この例では、戻されたJSONオブジェクトの処理方法を示します。Jerseyブックマーク・サンプルの詳細は、「Jerseyブックマーク・サンプルについて」を参照してください。

例2-6 HTTP GETリクエストのJavaメソッドへのマッピング(BookmarkResourceクラス)

import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
...
public class BookmarkResource {
...
@GET
@Produces("application/json")
public JSONObject getBookmark() {
return asJson();
}
...
public JSONObject asJson() {
try {
return new JSONObject()
.put("userid", bookmarkEntity.getBookmarkEntityPK().getUserid())
.put("sdesc", bookmarkEntity.getSdesc())
.put("ldesc", bookmarkEntity.getLdesc())
.put("uri", bookmarkEntity.getUri());
} catch (JSONException je){
return null;
}
}
}

リソースの表現の作成または更新方法(@PUT)

javax.ws.rs.PUTアノテーションは、URIで識別された特定のリソースの表現を作成または更新します。@PUTアノテーションの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/PUT.htmlを参照してください。

例2-7では、Jerseyブックマーク・サンプルのBookmarkResourceクラスからの、アノテーションが付けられたJavaメソッドputBookmarkが、HTTP PUTリクエストを処理し、指定したブックマークを更新します。Jerseyブックマーク・サンプルの詳細は、「Jerseyブックマーク・サンプルについて」を参照してください。

例2-7 HTTP PUTリクエストのJavaメソッドへのマッピング

import javax.ws.rs.PUT;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
...
public class BookmarkResource {
...
@PUT
@Consumes("application/json")
public void putBookmark(JSONObject jsonEntity) throws JSONException {
bookmarkEntity.setLdesc(jsonEntity.getString("ldesc"));
bookmarkEntity.setSdesc(jsonEntity.getString("sdesc"));
bookmarkEntity.setUpdated(new Date());

TransactionManager.manage(new Transactional(em) { public void transact() {
em.merge(bookmarkEntity);
}});
}

}

リソースの表現の削除方法(@DELETE)

javax.ws.rs.DELETEアノテーションは、URIで識別された特定のリソースの表現を削除します。レスポンスのエンティティ本文ではステータス・メッセージが返されるか、または空の可能性があります。@DELETEアノテーションの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/DELETE.htmlを参照してください。

例2-8では、Jerseyブックマーク・サンプルのBookmarkResourceクラスからの、アノテーションが付けられたJavaメソッドdeleteBookmarkが、HTTP DELETEリクエストを処理し、指定したブックマークを削除します。Jerseyブックマーク・サンプルの詳細は、「Jerseyブックマーク・サンプルについて」を参照してください。

例2-8 HTTP DELETEリクエストのJavaメソッドへのマッピング

import javax.ws.rs.DELETE;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;
...
public class BookmarkResource {
...
@DELETE
public void deleteBookmark() {
TransactionManager.manage(new Transactional(em) { public void transact() {
UserEntity userEntity = bookmarkEntity.getUserEntity();
userEntity.getBookmarkEntityCollection().remove(bookmarkEntity);
em.merge(userEntity);
em.remove(bookmarkEntity);
}});
}
}

リソースの表現でのアクションの作成、更新または実行方法(@POST)

javax.ws.rs.POSTアノテーションは、URIで識別された特定のリソースの表現でのアクションを作成、更新、または実行します。@POSTアノテーションの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/POST.htmlを参照してください。

例2-9では、Jerseyブックマーク・サンプルのBookmarksResourceクラスからの、アノテーションが付けられたJavaメソッドpostFormが、HTTP POSTリクエストを処理し、指定した情報を更新します。Jerseyブックマーク・サンプルの詳細は、「Jerseyブックマーク・サンプルについて」を参照してください。

例2-9 HTTP POSTリクエストのJavaメソッドへのマッピング

import javax.ws.rs.POST;
import javax.ws.rs.Produces;
...
public class BookmarksResource {
...
@POST
@Consumes("application/json")
public Response postForm(JSONObject bookmark) throws JSONException {
final BookmarkEntity bookmarkEntity = new BookmarkEntity(
getBookmarkId(bookmark.getString("uri")),
userResource.getUserEntity().getUserid());

bookmarkEntity.setUri(bookmark.getString("uri"));
bookmarkEntity.setUpdated(new Date());
bookmarkEntity.setSdesc(bookmark.getString("sdesc"));
bookmarkEntity.setLdesc(bookmark.getString("ldesc"));
userResource.getUserEntity().getBookmarkEntityCollection().add(bookmarkEntity);

TransactionManager.manage(new Transactional(em) { public void transact() {
em.merge(userResource.getUserEntity());
}});

URI bookmarkUri = uriInfo.getAbsolutePathBuilder().
path(bookmarkEntity.getBookmarkEntityPK().getBmid()).
build();
return Response.created(bookmarkUri).build();
}
}

リクエスト・メッセージおよびレスポンス・メッセージのメディア・タイプのカスタマイズ

リソースのクラス・レベルでjavax.ws.rs.Consumesまたはjavax.ws.rs.Producesアノテーションを追加し、リクエストおよびレスポンス・メディア・タイプをカスタマイズします。次の項を参照してください。

- リクエスト・メッセージのメディア・タイプのカスタマイズ方法(@Consumes)

- レスポンス・メッセージのメディア・タイプのカスタマイズ方法(@Produces)

- 実行時の処理: レスポンス・メッセージに対するリソース・メソッドの選択方法

リクエスト・メッセージのメディア・タイプのカスタマイズ方法(@Consumes)

javax.ws.rs.Consumesアノテーションにより、クライアントから送信され、リソースが消費できる表現のMIMEメディア・タイプを指定できます。@Consumesアノテーションはクラスとメソッド・レベルの両方に指定でき、複数のメディア・タイプを同じ@Consumes宣言で宣言できます。

指定されたMIMEメディア・タイプを消費できるメソッドがリソース内にない場合、ランタイムはHTTP 「415 - サポートされていないメディア・タイプ」エラーを返します。

@Consumesアノテーションの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/Consumes.htmlを参照してください。

例2-11では、JavaクラスhelloWorldに定義された@Consumesアノテーションは、クラスがtext/plain MIMEメディア・タイプを使用してメッセージを作成することを指定します。

例2-10 @Consumesを使用したリクエスト・メッセージのメディア・タイプのカスタマイズ

package samples.consumes;

import javax.ws.rs.Consumes;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
...
@Path("/helloworld")
public class helloWorld {
...
@POST
@Consumes("text/plain")
public void postMessage(String message) {
// Store the message
}
}

レスポンス・メッセージのメディア・タイプのカスタマイズ方法(@Produces)

javax.ws.rs.Producesアノテーションにより、リソースが生成でき、クライアントに戻すことができる、表現のMIMEメディア・タイプを指定できます。@Producesアノテーションはクラスとメソッド・レベルの両方に指定でき、複数のメディア・タイプを同じ@Produces宣言で宣言できます。

指定されたMIMEメディア・タイプを生成できるメソッドがリソース内にない場合、ランタイムはHTTP 「406 許可されません」エラーを返します。

@Producesアノテーションの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/Produces.htmlを参照してください。

例2-11では、JavaクラスSomeResourceに指定された@Producesアノテーションは、クラスがtext/plain MIMEメディア・タイプを使用してメッセージを作成することを指定します。doGetAsPlainTextメソッドのデフォルトは、クラス・レベルで指定されたMIMEメディア・タイプです。doGetAsHtmlメソッドはクラス・レベルの設定をオーバーライドし、メソッドがプレーン・テキストではなくHTMLを生成することを指定します。

例2-11 @Producesを使用したレスポンスのメディア・タイプのカスタマイズ

package samples.produces;
import javax.ws.rs.Produces;
import javax.ws.rs.Path;

@Path("/myResource")
@Produces("text/plain")
public class SomeResource {
@GET
public String doGetAsPlainText() { ... }

@GET
@Produces("text/html")
public String doGetAsHtml() { ... }
}

実行時の処理: レスポンス・メッセージに対するリソース・メソッドの選択方法

リソース・クラスが複数のMIMEメディア・タイプの生成が可能な場合、選択されたリソース・メソッドは、HTTPリクエストのAcceptヘッダーに宣言された受入れ可能なメディア・タイプに対応します。例2-11では、AcceptヘッダーがAccept: text/htmlの場合、doGetAsPlainTextメソッドが呼び出されます。

複数のMIMEメディア・タイプが@Producesアノテーションに含まれており、両方がクライアントに受入れ可能な場合、指定された最初のメディア・タイプが使用されます。例2-11では、AcceptヘッダーがAccept: application/html, application/textの場合、doGetAsHtmlメソッドが呼び出され、リストの最初に表示されるapplication/html MIMEメディア・タイプが使用されます。

リクエスト・メッセージからの情報の抽出

javax.ws.rsパッケージでは、表2-2に示すとおり、リクエスト・メッセージから情報を抽出し、Javaメソッドのパラメータに注入できるアノテーションのセットを定義します。

表2-4 リクエスト・メッセージから情報を抽出するためのjavax.ws.rsアノテーション

アノテーション

説明

@CookieParam

HTTP Cookie関連ヘッダーから情報を抽出し、メソッド・パラメータの値を初期化します。詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/CookieParam.htmlを参照してください。

@DefaultValue

次に示すアノテーションのいずれかを使用してバインドされるリクエスト・メタデータのデフォルト値を定義します。@CookieParam、@FormParam、@HeaderParam、@MatrixParam、@PathParamまたは@QueryParam。詳細は、「DefaultValueの定義方法(@DefaultValue)」を参照してください。

@Encode

@FormParam、@MatrixParam、@PathParamまたは@QueryParamのいずれかのアノテーションを使用してバインドされるパラメータ値のエンコードを有効にします。詳細は、「パラメータ値のエンコード(@Encode)の有効化」を参照してください。

@FormParam

タイプapplication/x-www-form-urlencodedのHTMLフォームから情報を抽出します。詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/FormParam.htmlを参照してください。

@HeaderParam

HTTPヘッダーから情報を抽出し、メソッド・パラメータの値を初期化します。詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/HeaderParam.htmlを参照してください。

@MatrixParam

URIパス・セグメントから情報を抽出し、メソッド・パラメータの値を初期化します。詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/MatrixParam.htmlを参照してください。

@PathParam

相対URIを変数として定義します(URIパス・テンプレートとして参照)。詳細は、「リクエストURIからの変数情報の抽出方法(@PathParam)」を参照してください。

@QueryParam

リクエストURIの問合せ部分から情報を抽出し、メソッド・パラメータの値を初期化します。詳細は、「リクエスト・パラメータの抽出方法(@QueryParam)」を参照してください。

リクエストURIからの変数情報の抽出方法(@PathParam)

javax.ws.rs.PathParamアノテーションをリソースのメソッド・パラメータに追加し、リクエストURIから変数情報を抽出し、メソッド・パラメータの値を初期化します。@DefaultValueアノテーションを使用して、変数値のデフォルト値を定義できます。「DefaultValueの定義方法(@DefaultValue)」を参照してください。

例2-3では、@PathParamアノテーションが、@PathアノテーションによりURIパスの一部として定義されたusername変数の値をuserNameメソッド・パラメータに割り当てます。

例2-12 リクエストURIからの変数情報の抽出

package samples.helloworld;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.PathParam;

// Specifies the path to the RESTful service
@Path("/users")
public class helloWorld {
. . .
@GET
@Path("/{username}")
@Produces("text/xml")
public String getUser(@PathParam("username") String userName) {
...
}
}

リクエスト・パラメータの抽出方法(@QueryParam)

javax.ws.rs.QueryParamアノテーションをリソースのメソッド・パラメータに追加し、リクエストURIの問合せ部分から情報を抽出し、メソッド・パラメータの値を初期化します。

アノテーションの付けられたメソッド・パラメータの種類は次のとおりです。

- プリミティブ型(int、char、byteなど)

- ユーザー定義型

- 1つの文字列引数を受入れるコンストラクタ

- 1つの文字列引数を受入れる静的メソッドvalueOfまたはfromString(たとえば、integer.valueOf(String))

- List<T>、Set<T>、またはSortedSet<T>

@QueryParamアノテーションが指定されても、関連する問合せパラメータがリクエストに存在しない場合、そのパラメータ値は、List、SetまたはSortedSetの場合は空のコレクション、プリミティブ型の場合はJava定義のデフォルト、およびその他のすべてのオブジェクト型の場合はNULLに設定されます。または、@DefaultValueアノテーションを使用して、パラメータのデフォルト値を定義できます。「DefaultValueの定義方法(@DefaultValue)」を参照してください。

@QueryParamアノテーションの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/QueryParam.htmlを参照してください。

例2-13では、step問合せパラメータがリクエストURIの問合せコンポーネントに存在する場合、その値はstepメソッドのパラメータに整数値として割り当てられます。値が整数値として解析できない場合、400 (クライアント・エラー)レスポンスが返ります。step問合せパラメータがリクエストURIの問合せコンポーネント内に存在しない場合、値はNULLに設定されます。

例2-13 リクエスト・パラメータの抽出(@QueryParam)

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.QueryParam;
...
@Path("smooth")
@GET
public Response smooth(@QueryParam("step") int step)
{ ... }
}

DefaultValueの定義方法(@DefaultValue)

javax.ws.rs.DefaultValueアノテーションを追加して、次に示すアノテーションのいずれかを使用してバインドされるリクエスト・メタデータのデフォルト値を定義します。@CookieParam、@FormParam、@HeaderParam、@MatrixParam、@PathParamまたは@QueryParam。@DefaultValueアノテーションの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/DefaultValue.htmlを参照してください。

例2-14では、step問合せパラメータがリクエストURIの問合せコンポーネントに存在しない場合、デフォルトの値2がstepパラメータに割り当てられます。

例2-14 DefaultValueの定義(@DefaultValue)

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.QueryParam;
...
@Path("smooth")
@GET
public Response smooth(@DefaultValue("2") @QueryParam("step") int step)
{ ... }
}

パラメータ値のエンコードの有効化(@Encode)

クラスまたはメソッド・レベルでjavax.ws.rs.Encodeアノテーションを追加して、@FormParam、@MatrixParam、@PathParamまたは@QueryParamのいずれかのアノテーションを使用してバインドされるパラメータ値のエンコードを有効にします。クラス・レベルで指定した場合は、そのクラスのすべてのメソッドのパラメータがエンコードされます。詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/Encoded.htmlを参照してください。

例2-15の@Encodeアノテーションは、@PathParamアノテーションを使用してバインドされるパラメータ値のエンコードを有効にします。

例2-15 パラメータ値のエンコード

package samples.helloworld;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.PathParam;
import javax.ws.rs.Encode;

// Specifies the path to the RESTful service
@Path("/users")
public class helloWorld {
. . .
@GET
@Path("/{username}")
@Produces("text/xml")
@Encode
public String getUser(@PathParam("username") String userName) {
...
}
}

カスタム・レスポンス・メッセージの構築

デフォルトでは、正常なGETリクエストには200 OK、正常なPUTリクエストには201 CREATEDなどの、HTTP仕様で定義されたデフォルト・レスポンス・コードを使用して、JAX-RSはHTTPリクエストに応答します。

場合によっては、返されたレスポンス・コードをカスタマイズする、または追加メタデータ情報をレスポンスに含めることがあります。たとえば、新しく作成されたリソースにURIを指定するためのLocationヘッダーを含めるような場合です。返されたレスポンス・メッセージは、javax.ws.rs.core.Responseクラスを使用して変更できます。

アプリケーションではResponseクラスを直接拡張するか、表2-5で定義された静的Responseメソッドの1つを使用することで、javax.ws.rs.core.Response.ResponseBuilderインスタンスを作成してResponseインスタンスを構築できます。Responseメソッドの詳細は、Javadoc (http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/core/Response.html)を参照してください。

表2-5 ResponseBuilderクラスを使用したレスポンス・インスタンスの作成

メソッド

説明

created()

新しいResponseBuilderインスタンスを作成して、Locationヘッダーを指定された値に設定します。

fromResponse()

新しいResponseBuilderインスタンスを作成して、既存のレスポンスをコピーします。

noContent()

新しいResponseBuilderインスタンスを作成して、空のレスポンスを定義します。

notAcceptable()

新しいResponseBuilderインスタンスを作成して、許可できないレスポンスを定義します。

notModified()

新しいResponseBuilderインスタンスを作成して、変更されていないステータスを返します。

ok()

新しいResponseBuilderインスタンスを作成して、OKステータスを返します。

seeOther()

リダイレクトのための新しいResponseBuilderインスタンスを作成します。

serverError()

新しいResponseBuilderインスタンスを作成して、サーバー・エラー・ステータスを返します。

status()

新しいResponseBuilderインスタンスを作成して、指定されたステータスを返します。

temporaryRedirect()

一時的なリダイレクトのための新しいResponseBuilderインスタンスを作成します。

ResponseBuilderインスタンスを作成した後は、表2-6で定義されたメソッドを呼び出してカスタム・リソースを定義できます。次に、build()メソッドを呼び出して最終的なResponseインスタンスを作成します。ResponseBuilderクラスとそのメソッドの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/core/Response.ResponseBuilder.htmlを参照してください。

表2-6 カスタム・レスポンスを構築するためのResponseBuilderメソッド

メソッド

説明

build()

現在のResponseBuilderインスタンスからレスポンス・インスタンスを作成します。

cacheControl()

キャッシュ・コントロールを設定します。

clone()

ResponseBuilderのコピーを作成してその状態を保存します。

contentLocation()

コンテンツの場所を設定します。

cookie()

レスポンスにCookieを追加します。

entity()

エンティティを定義します。

expires()

有効期限を設定します。

header()

レスポンスにヘッダーを追加します。

language()

言語を設定します。

lastModified()

最終変更日を設定します。

location()

場所を設定します。

newInstance()

新しいResponseBuilderインスタンスを作成します。

status()

ステータスを設定します。

tag()

エンティティ・タグを設定します。

type()

レスポンス・メディア・タイプを設定します。

variant()

表現メタデータを設定します。

variants()

使用可能なバリアントの一覧を示すVaryヘッダーを追加します。

例2-16は、ResponseBuilderを使用したResponseインスタンスの構築方法を示しています。この例では、200 OKの標準ステータス・コードが返され、レスポンスのメディア・タイプがtext/htmlに設定されます。build()メソッドの呼出しによって最終的なResponseインスタンスが作成されます。

例2-16 カスタム・レスポンスの構築

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.ResponseBuilder;
...
@Path("/content")
public class getDocs {
@GET
@Path("{id}")
public Response getHTMLDoc(@PathParm("id") int docId)
{
Document document = ...;
ResponseBuilder response = Response.ok(document);
response.type("text/html");
return response.build();
}
}

汎用型を使用してHTTPレスポンスを構築する場合、実行時に型のイレイジャを回避するために、汎用型を保持するjavax.ws.rs.core.GenericEntityオブジェクトを作成する必要があります。詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/core/GenericEntity.htmlを参照してください。

例2-17に、汎用型を保持するGenericEntityを使用する、HTTPレスポンスの構築方法の例を示します。

例2-17 汎用型を使用したカスタム・レスポンスの構築

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.PathParam;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.ResponseBuilder;
javax.ws.rs.core.GenericEntity;
...
@Path("/content")
public class getDocs {
@GET
@Path("{id}")
public Response getHTMLDoc(@PathParm("id") int docId)
{
Document document = ...;
List<String> list = new ArrayList<String>();
GenericEntity<List<String>> entity = new GenericEntity<List<String>>(list) {};
...
ResponseBuilder response = Response.ok(document);
response.entity(entity);
return response.build();
}
}

エンティティ・プロバイダを使用したHTTPリクエストおよびレスポンスのエンティティ本文のマッピング

表2-7に、HTTPリクエストおよびレスポンスのエンティティ本文で自動的にサポートされるJavaタイプを示します。

表2-7 HTTPリクエストおよびレスポンスのエンティティ本文でサポートされるJavaタイプ

Javaタイプ

サポートされるメディア・タイプ

byte[]

すべてのメディア・タイプ(*/*)

java.lang.String

すべてのメディア・タイプ(*/*)

java.io.InputStream

すべてのメディア・タイプ(*/*)

java.io.Reader

すべてのメディア・タイプ(*/*)

java.io.File

すべてのメディア・タイプ(*/*)

javax.activation.DataSource

すべてのメディア・タイプ(*/*)

javax.xml.transform.Source

XMLメディア・タイプ(text/xml、application/xmlおよびapplication/*+xml)およびJSONメディア・タイプ(application/json、application/*+json)

javax.xml.bind.JAXBElementおよびアプリケーション提供のJAXBのクラス

XMLメディア・タイプ(text/xml、application/xmlおよびapplication/*+xml)

MultivaluedMap<String,String>

フォーム・コンテンツ(application/x-www-form-urlencoded)

StreamingOutput

すべてのメディア・タイプ(*/*)、MessageBodyWriterのみ

RESTful Webサービスで、表2-7に示されていないタイプを使用する場合は、表2-8に定義されているインタフェースのいずれかを実装することでエンティティ・プロバイダを定義し、HTTPリクエストおよびレスポンスのエンティティ本文をメソッドのパラメータおよび戻りタイプにマップする必要があります。

表2-8 HTTPリクエストおよびレスポンスのエンティティ本文をメソッドのパラメータおよび戻りタイプにマップするためのエンティティ・プロバイダ

エンティティ・プロバイダ

説明

javax.ws.rs.ext.MessageBodyReader

HTTPリクエストのエンティティ本文をメソッドのパラメータにマップします。@Consumesアノテーションを使用すると、必要に応じて、エンティティ・プロバイダでサポートされているMIMEメディア・タイプを指定できます。詳細は、「リクエスト・メッセージおよびレスポンス・メッセージのメディア・タイプのカスタマイズ」を参照してください。

以下に例を示します。

@Consumes("application/x-www-form-urlencoded")
@Provider
public class FormReader implements MessageBodyReader<NameValuePair> { ... }

javax.ws.rs.ext.MessageBodyWriter

HTTPレスポンスのエンティティ本文に戻り値をマップします。@Producesアノテーションを使用すると、必要に応じて、エンティティ・プロバイダでサポートされているMIMEメディア・タイプを指定できます。詳細は、「リクエスト・メッセージおよびレスポンス・メッセージのメディア・タイプのカスタマイズ」を参照してください。

以下に例を示します。

@Produces("text/html")
@Provider
public class FormWriter implements
MessageBodyWriter<Hashtable<String, String>> { ... }

注意:

Jersey JSONには、jersey-jsonモジュールとともに配布される、JAX-RS MessageBodyReaderプロバイダおよびMessageBodyWriterプロバイダのセットが用意されています。詳細は、『Jersey User Guide』の「JSON Support」(https://jersey.java.net/documentation/1.13/user-guide.html#json)を参照してください。

次に示すコードの抜粋は、カスタム・タイプを返すメソッド(getClass)を含むクラスの例を示しています。このコードにはエンティティ・プロバイダを記述する必要があります。

public class Class1
{
public String hello() { return "Hello"; }
public Class2 getClass(String name) { return new Class2(); };
}

public class Class2
{
public Class2() { }
}

アプリケーション・コンテキストのアクセス

javax.ws.rs.core.Contextアノテーションを使用すると、アプリケーション・デプロイメント・コンテキストと個別リクエストのコンテキストに関する情報にアクセスできます。表2-9に@Contextアノテーションを使用してアクセスできるコンテキスト・タイプの概要を示します。詳細は、Javadoc (http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/core/Context.html)を参照してください。

表2-9 コンテキスト・タイプ

コンテキスト・タイプ名

目的

HttpHeaders

HTTPヘッダー情報にアクセスします。

Providers

一連の検索基準を基に、プロバイダ・インスタンスを参照します。

Request

最も一致する表現バリアントを判別し、リソースの現在の状態が定義済の前条件に一致するかどうかを評価します。詳細は、「条件付きGETの使用」を参照してください。

SecurityContext

セキュリティ・コンテキストにアクセスし、RESTful Webサービスを保護します。詳細は、「SecurityContextを使用したRESTful Webサービスの保護」を参照してください。

UriInfo

アプリケーションおよびリクエストURI情報にアクセスします。詳細は、「URIの構築」を参照してください。

URIの構築

javax.ws.rs.core.UriInfoを使用して、アプリケーションおよびリクエストURI情報にアクセスできます。具体的には、UriInfoは次の情報を返すために使用できます。

- デプロイされたアプリケーションの基底URI

- 基底URIに相対するリクエストURI

- 絶対パスURI (問合せパラメータ付きの場合もあり)

UriInfoを使用して、URIまたはjavax.ws.rs.core.UriBuilderインスタンスを返すことができます。UriBuilderはURIの構築プロセスを簡素化し、新規URIの構築、または既存URIの拡張にも使用できます。

UriBuilderメソッドは、対応するURIコンポーネントでは許可されていない文字のコンテキスト・エンコーディングを、次のルールに基づいて実行します。

- 問合せパラメータについてはapplication/x-www-form-urlencodedメディア・タイプ(URL: http://www.w3.org/TR/html4/interact/forms.html#h-17.13.4.1にあるHTML仕様の「Forms」で定義)

- その他すべてのコンポーネントについてはRFC 3986 (URL: http://www.ietf.org/rfc/rfc3986.txtで定義)

例2-18に、@Contextを使用したUriInfoのインスタンスの取得と、そのインスタンスを使用して、リクエストURIの絶対パスをUriBuilderインスタンスとして返す方法を示します。次に、UriBuilderを使用して、ユーザーIDをパス・セグメントとして追加して特定のユーザー・リソースに対するURIを構築し、配列内に格納します。この例では、UriInfoインスタンスはクラス・フィールドに注入されます。この例は、「Jerseyブックマーク・サンプルについて」に記述されているとおり、ブックマーク・サンプルからの抜粋です。

例2-18 URIの構築

import javax.ws.rs.Path;
import javax.ws.rs.GET;
import javax.ws.rs.Produces;
import javax.ws.rs.core.UriBuilder;
import javax.ws.rs.core.UriInfo;
import javax.ws.rs.core.Context;
...
@Path("/users/")
public class UsersResource {

@Context UriInfo uriInfo;

...

@GET
@Produces("application/json")
public JSONArray getUsersAsJsonArray() {
JSONArray uriArray = new JSONArray();
for (UserEntity userEntity : getUsers()) {
UriBuilder ub = uriInfo.getAbsolutePathBuilder();
URI userUri = ub.path(userEntity.getUserid()).build();
uriArray.put(userUri.toASCIIString());
}
return uriArray;
}
}

条件付きGETの使用

条件付きGETを使用すると、GETリクエストを処理する前に前条件を1つ以上評価できます。前条件が一致する場合、Not Modified (304)レスポンスを通常のレスポンスのかわりに返すことが可能で、これによって潜在的に帯域幅が縮小され、サーバー・パフォーマンスが向上します。

JAX-RSは、条件付きGETの実行を可能にするjavax.ws.rs.core.Requestコンテキスト・インタフェースを提供します。evaluatePreconditions()メソッドを呼び出してjavax.ws.rs.core.EntityTag、(java.util.Dateオブジェクトとして)最終変更日のタイムスタンプ、あるいはその両方を渡します。値はIf-None-MatchヘッダーまたはIf-Not-Modifiedヘッダーと、このヘッダーがリクエストとともに送信された場合は、それぞれ比較されます。

ヘッダーがリクエストとともに含まれ、前条件値がヘッダー値と一致する場合は、evaluatePreconditions()メソッドが定義済のResponseBuilderレスポンスをNot Modified (304)のステータス・コードとともに返します。前条件値が一致しない場合、evaluatePreconditions()メソッドはNULLを返し、通常のレスポンスが200, OKステータスとともに返されます。

例2-19に、EntityTagをevaluatePreconditions()メソッドに渡し、前条件の一致の有無に基づいてレスポンスを構築する方法を示します。

例2-19 条件付きGETの使用

...
@Path("/employee/{joiningdate}")
public class Employee {

Date joiningdate;
@GET
@Produces("application/xml")
public Employee(@PathParam("joiningdate") Date joiningdate, @Context Request req,
@Context UriInfo ui) {

this.joiningdate = joiningdate;
...
this.tag = computeEntityTag(ui.getRequestUri());
if (req.getMethod().equals("GET")) {
Response.ResponseBuilder rb = req.evaluatePreconditions(tag);
// Preconditions met
if (rb != null) {
return rb.build();
}
// Preconditions not met
rb = Response.ok();
rb.tag(tag);
return rb.build();
}
}
}

WADLのアクセス

Web Application Description Language (WADL)は、RESTful Webサービス・アプリケーションを記述するXMLベースのファイル形式です。デフォルトでは、ベースWADLがランタイムに生成され、RESTfulアプリケーションの基底URIでGETを/application.wadlリソースに発行することで、RESTful Webサービスからアクセスできます。以下に例を示します。

GET http://<path_to_REST_app>/application.wadl

もしくは、OPTIONSメソッドを使用して特定のリソースに対するWADLを返すこともできます。

例2-20に、例2-1の簡単なRESTful Webサービスに対するWADLの例を示します。

例2-20 WADLの例

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
<doc xmlns:jersey="http://jersey.dev.java.net/"
jersey:generatedBy="Jersey: 0.10-ea-SNAPSHOT 08/27/2008 08:24 PM"/>
<resources base="http://localhost:9998/">
<resource path="/helloworld">
<method name="GET" id="sayHello">
<response>
<representation mediaType="text/plain"/>
</response>
</method>
</resource>
</resources>
</application>

高度なRESTful Webサービス・タスク

以下を含む、高度なRESTful Webサービス・デプロイメント・タスクの詳細は、『Jersey 1.13 User Guide』(http://jersey.java.net/nonav/documentation/1.13/user-guide.html)を参照してください。

- JAX-RSとEJBテクノロジおよびContexts and Dependency Injection (CDI)の統合

- JAXBおよびJSONの使用

3 RESTful Webサービス・クライアントの開発

この章では、Java API for RESTful Web Services (JAX-RS)を使用して、Representational State Transfer (REST)アーキテクチャ・スタイルに従ったWebLogic Webサービス・クライアントを開発する方法について説明します。

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

- RESTful Webサービス・クライアントの開発について

- クライアント・インスタンスの作成および構成

- Webリソース・インスタンスの作成

- リソースへのリクエストの送信

- リソースからのレスポンスの受信

- 高度なRESTful Webサービス・クライアント・タスク

- スタンドアロン・クライアントからのRESTful Webサービスの呼出し

Oracle JDeveloperを使用したRESTful Webサービス・クライアントの開発の詳細は、『Oracle JDeveloperによるアプリケーションの開発』のRESTful Webサービスおよびクライアントの作成に関する項を参照してください。

RESTful Webサービス・クライアントの開発について

Jersey JAX-RS RIにより、RESTful Webサービス・クライアントを開発するためのクライアントAPIが提供されます。クライアントAPIにアクセスするには、weblogic.jaxrs.api.client.Clientクラスのインスタンスを作成してから、そのインスタンスを使用してWebリソースへのアクセスおよびHTTPリクエストの送信を行います。

注意:

標準のクライアントAPIはJSR-311 JAX-RS 2.0仕様の一部としてサポートされる予定です。

以下の項で、RESTful Webサービス・クライアントの開発の詳細について説明します。

- RESTful Webサービス・クライアントを開発するタスクの概要

- RESTful Webサービス・クライアントの例

RESTful Webサービス・クライアントを開発するタスクの概要

次の表に、RESTful Webサービス・クライアントを開発するのに必要なタスクのサブセットの概要を示します。高度なタスクの詳細は、「高度なRESTful Webサービス・クライアント・タスク」を参照してください。

表3-1 RESTful Webサービス・クライアントを開発するタスクの概要

タスク

詳細情報

weblogic.jaxrs.api.client.Clientクラスのインスタンスを作成します。

クライアント・インスタンスの作成および構成

Webリソースのインスタンスを作成します。

Webリソース・インスタンスの作成

リソースへリクエストを送信します。たとえば、リソース情報をGET、PUT、POSTおよびDELETEするHTTPリクエストです。

リソースへのリクエストの送信

リソースからレスポンスを受信します。

リソースからのレスポンスの受信

RESTful Webサービス・クライアントの例

次に、例2-1「簡単なRESTful Webサービス」で定義されたRESTful Webサービスを呼び出すのに使用できる簡単なRESTful Webサービス・クライアントの例を示します。この例の内容は次のとおりです。

- ClientインスタンスがクライアントAPIにアクセスするために作成されます。詳細は、「クライアント・インスタンスの作成と構成」を参照してください。

- WebResourceインスタンスがWebリソースにアクセスするために作成されます。詳細は、「Webリソース・インスタンスの作成」を参照してください。

- getリクエストがリソースに送信されます。詳細は、 「リソースへのリクエストの送信」を参照してください。

- レスポンスは文字列値で返されます。レスポンスの受信についての詳細は、「リソースからのレスポンスの受信」を参照してください。

追加の例を「RESTful Webサービスの詳細」に示します。

例3-1 簡単なRESTful Webサービス・クライアント

package samples.helloworld.client;

import weblogic.jaxrs.api.client.Client;
import com.sun.jersey.api.client.WebResource;

public class helloWorldClient {
public helloWorldClient() {
super();
}

public static void main(String[] args) {
Client c = Client.create();
WebResource resource = c.resource("http://localhost:7101/RESTfulService-Project1-context-root/jersey/helloWorld");
String response = resource.get(String.class);
}
}

クライアント・インスタンスの作成および構成

Jersey JAX-RS RIクライアントAPIにアクセスするには、weblogic.jaxrs.api.client.Clientクラスのインスタンスを作成します。

注意:

かわりに、com.sun.jersey.api.client.Clientクラスのインスタンスを作成することもできます。ただし、「OWSMポリシーを使用したRESTful Webサービスとクライアントの保護」で説明しているような、Oracle Web Services Manager (OWSM)ポリシーを使用したRESTfulクライアントの保護などのOracle拡張機能は利用できません。

クライアント・インスタンスの作成時、com.sun.jersey.api.client.config.ClientConfigを定義してcreateメソッドに情報を渡すことで、必要に応じて、表3-2で定義しているクライアント構成プロパティを渡すことができます。詳細は、https://jersey.java.net/apidocs/1.13/jersey/index.html?com/sun/jersey/api/client/config/ClientConfig.htmlを参照してください。

表3-2 RESTful Webサービス・クライアント構成プロパティ

プロパティ

説明

PROPERTY_BUFFER_RESPONSE_ENTITY_ON_EXCEPTION

クライアントがレスポンス・エンティティをバッファリングする必要があるかどうかと、ある場合にはUniformInterfaceExceptionがスローされるとリソースを閉じるかどうかを指定するブール値です。このプロパティのデフォルトはtrueです。

PROPERTY_CHUNKED_ENCODING_SIZE

チャンク化されたエンコードのサイズを指定する整数値です。0以下の値はデフォルトのチャンク・サイズが使用されることを示します。設定されない場合、チャンクは使用されません。

PROPERTY_CONNECT_TIMEOUT

接続タイムアウト間隔をミリ秒単位で指定する整数値です。このプロパティが0または設定されない場合、間隔は無限です。

PROPERTY_FOLLOW_REDIRECTS

3xxレスポンスで宣言されたURIに自動的にリダイレクトされるかどうかを指定するブール値です。このプロパティのデフォルトはtrueです。

PROPERTY_READ_TIMEOUT

読取りタイムアウト間隔をミリ秒単位で指定する整数値です。このプロパティが0または設定されない場合、間隔は無限です。

例3-2にクライアント・インスタンスの作成方法の例を示します。

例3-2 クライアント・インスタンスの作成

import weblogic.jaxrs.api.client.Client;
...
public static void main(String[] args) {
Client c = Client.create();
...

例3-3に、クライアント・インスタンスを作成し、構成プロパティをcreateに渡す方法の例を示します。

例3-3 クライアント・インスタンスの作成および構成

import com.sun.jersey.api.client.*;
import weblogic.jaxrs.api.client.Client;
...
public static void main(String[] args) {
ClientConfig cc = new DefaultClientConfig();
cc.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
Client c = Client.create(cc);
...

また、getPropertiesメソッドから戻されたマップにプロパティを設定するか、または特定のsetterメソッドを呼び出すことで、クライアントの作成後にクライアント・インスタンスを構成することもできます。

例3-4に、クライアントを作成した後で構成する方法の例を示します。この例の内容は次のとおりです。

- PROPERTY_FOLLOW_REDIRECTSはgetPropertiesメソッドから戻されたマップにプロパティを設定することにより構成されます。

- PROPERTY_CONNECT_TIMEOUTはsetterメソッドを使用して構成されます。

例3-4 クライアント・インスタンスの作成後の構成

import com.sun.jersey.api.client.*;
import weblogic.jaxrs.api.client.Client;
...
public static void main(String[] args) {
Client c = Client.create();
c.getProperties().put(ClientConfig.PROPERTY_FOLLOW_REDIRECTS, true);
c.setConnectTimeout(3000);
...

例3-5に、基本認証を使用するようにクライアント・インスタンスを構成する方法の例を示します。

例3-5 基本認証を使用するクライアント・インスタンスの構成

import javax.ws.rs.core.MediaType;

import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.filter.HTTPBasicAuthFilter;
...
Client c = Client.create();
c.addFilter(new HTTPBasicAuthFilter("weblogic", "weblogic1"));
WebResource resource = c.resource("http://localhost:7001/management/tenant-monitoring/datasources/JDBC%20Data%20Source-0");
String response = resource.accept("application/json").get(String.class); //application/xml
// resource.accept(MediaType.APPLICATION_JSON_TYPE).get(String.class);
System.out.println(response);
...

Webリソース・インスタンスの作成

RESTful Webサービスにリクエストを送信する前に、URIで指定したリソースにアクセスするための、com.sun.jersey.api.client.WebResourceまたはcom.sun.jersey.api.client.AsyncWebResourceのインスタンスを作成する必要があります。WebResourceまたはAsyncWebResourceインスタンスはクライアント・インスタンスに対して定義された構成を継承します。詳細については、以下を参照してください。

- WebResource: https://jersey.java.net/apidocs/1.13/jersey/index.html?com/sun/jersey/api/client/WebResource.html

- AsyncWebResource: https://jersey.java.net/apidocs/1.13/jersey/index.html?com/sun/jersey/api/client/AsyncWebResource.html

注意:

クライアント・インスタンスはコストの高いリソースなので、複数のWebリソースを作成する場合、可能ならば1つのクライアント・インスタンスを再利用することを推奨します。

例3-6に、http://example.com/helloworldにホストされたWebリソースへのインスタンスを作成する方法の例を示します。

例3-6 Webリソース・インスタンスの作成

import com.sun.jersey.api.client.*;
import weblogic.jaxrs.api.client.Client;
...
public static void main(String[] args) {\
...
Client c = Client.create();
WebResource resource = c.resource("http://example.com/helloWorld");
...

例3-6に、http://example.com/helloworldにホストされた非同期Webリソースへのインスタンスを作成する方法の例を示します。

例3-7 非同期Webリソース・インスタンスの作成

import com.sun.jersey.api.client.*;
import weblogic.jaxrs.api.client.Client;
...
public static void main(String[] args) {\
...
Client c = Client.create();
AsyncWebResource asyncResource = c.resource("http://example.com/helloWorld");
...

リソースへのリクエストの送信

次の項で説明するように、WebResourceまたはAsyncWebResourceインスタンスを使用して、関連するWebリソースへのリクエストを構築します。

- リクエストの構築方法

- HTTPリクエストの送信方法

- Acceptヘッダーの構成方法

- 問合せパラメータを渡す方法

リクエストの構築方法

Webリソースへのリクエストは、com.sun.jersey.api.client.RequestBuilderインタフェースで定義したように、ビルダー・パターンを使用して構造化されます。RequestBuilderインタフェースはcom.sun.jersey.api.client.WebResource、com.sun.jersey.api.client.AsyncWebResourceおよびその他のリソース・クラスにより実装されます。

表3-3に定義されているメソッドを使用してリクエストを構築できます。HTTPリクエスト・メソッドについては、次の「HTTPリクエストの送信方法」を参照してください。リクエストの構築方法の例は、後続の各項で説明しています。

RequestBuilderとそのメソッドの詳細は、https://jersey.java.net/apidocs/1.13/jersey/index.html?com/sun/jersey/api/client/RequestBuilder.htmlを参照してください。

表3-3 リクエストの構築

メソッド

説明

accept()

有効なメディア・タイプを定義します。「Acceptヘッダーの構成方法」を参照してください。

acceptLanguage()

acceptLanguageメソッドを使用して有効な言語を定義します。

cookie()

設定するcookieを追加します

entity()

リクエスト・エンティティを構成します。「リクエスト・エンティティの構成方法」を参照してください。

header()

HTTPヘッダーおよび値を追加します。「Acceptヘッダーの構成方法」を参照してください。

type()

メディア・タイプを構成します。「リクエスト・エンティティの構成方法」を参照してください。

HTTPリクエストの送信方法

表3-4に、HTTPリクエストを送信する際に使用できるWebResourceおよびAsyncWebResourceの各メソッドを示します。

AsyncWebResourceの場合、java.util.concurrent.Future<V>オブジェクトが返されます。このオブジェクトは後で、実行を妨げずに計算結果へアクセスする際に使用できます。Future<V>の詳細は、http://docs.oracle.com/javase/7/docs/api/index.html?java/util/concurrent/Future.htmlを参照してください。

表3-4 HTTPリクエストを送信するためのWebResourceメソッド

メソッド

説明

get()

リソースの表現を取得するためにHTTP GETメソッドを呼び出します。

post()

指定したリソースの表現を作成または更新するためにHTTP POSTメソッドを呼び出します。

put()

リソースの表現を更新するためにHTTP PUTメソッドを呼び出します。

delete()

リソースの表現を削除するためにHTTP DELETEメソッドを呼び出します。

レスポンスにエンティティ(または表現)が含まれる場合、インスタンスのJavaタイプはHTTPメソッド内で宣言される必要があります。

例3-8に、HTTP GETリクエストの送信方法の例を示します。この例では、レスポンス・エンティティはStringのインスタンスであることが要求されます。レスポンス・エンティティはStringインスタンスにデシリアライズされます。

例3-8 HTTP GETリクエストの送信

import com.sun.jersey.api.client.WebResource;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
String response = resource.get(String.class);
...

例3-9に、HTTP PUTリクエストの送信とエンティティfoo:barのWebリソースへの配置方法を示します。この例では、レスポンス・エンティティはcom.sun.jersey.api.client.ClientResponseのインスタンスであることが要求されます。

例3-9 HTTP PUTリクエストの送信

import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.ClientResponse;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
ClientResponse response = resource.put(ClientResponse.class, "foo:bar");
...

汎用型を使用してHTTPリクエストを送信する場合、実行時に型のイレイジャを回避するために、汎用型を保持するcom.sun.jersey.api.client.GenericTypeオブジェクトを作成する必要があります。詳細は、https://jersey.java.net/apidocs/1.13/jersey/index.html?com/sun/jersey/api/client/GenericType.htmlを参照してください。

例3-10に、汎用型を保持するGenericTypeを使用する、汎用型を使用したHTTPリクエストの送信方法の例を示します。

例3-10 汎用型を使用したHTTP GETリクエストの送信

import com.sun.jersey.api.client.WebResource;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
List<String> list = resource.get(new GenericType<List<String>>() {});
...

問合せパラメータを渡す方法

javax.ws.rs.core.MultivaluedMapを定義し、WebリソースでqueryParamsメソッドを使用して、HTTPリクエストの一部としてマップを渡すことで、GETリクエスト内の問合せパラメータを渡すことができます。

MultivaluedMapの詳細は、http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/core/MultivaluedMap.htmlを参照してください。

例3-11に、GETリクエスト内のパラメータをhttp://example.com/helloworldにホストされたWebリソースに渡し、次のリクエストURIの結果となる例を示します: http://example.com/base?param1=val1&param2=val2

例3-11 問合せパラメータを渡す

import com.sun.jersey.api.client.WebResource;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.core.MultivaluedMapImpl;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
MultivaluedMap queryParams = new MultivaluedMapImpl();
queryParams.add("param1", "val1");
queryParams.add("param2", "val2");
String response = resource.queryParams(queryParams).get(String.class);
...

Acceptヘッダーの構成方法

Webリソースでacceptメソッドを使用して、リクエストのAcceptヘッダーを構成します。

例3-12に、http://example.com/helloworldにホストされたWebリソースへのGETリクエストに、有効なMIMEメディア・タイプとしてtext/plainを指定する方法の例を示します。

例3-12 Acceptヘッダーの構成

import com.sun.jersey.api.client.WebResource;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
String response = resource.accept("text/plain").get(String.class);
...

カスタム・ヘッダーの追加方法

Webリソースでheaderメソッドを使用して、カスタム・ヘッダーをリクエストに追加します。

例3-13に、値BARを含むカスタム・ヘッダーFOOを、http://example.com/helloworldにホストされたWebリソースへのGETリクエストに追加する方法の例を示します。

例3-13 カスタム・ヘッダーの追加

import com.sun.jersey.api.client.WebResource;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
String response = resource.header("FOO", "BAR").get(String.class);
...

リクエスト・エンティティの構成方法

Webリソースでentityメソッドを使用して、リクエスト・エンティティとタイプを構成します。または、Webリソースでtypeメソッドのみを使用してリクエスト・エンティティのタイプを構成することもできます。

例3-14に、リクエスト・エンティティおよびタイプの構成方法の例を示します。

例3-14 リクエスト・エンティティの構成

import com.sun.jersey.api.client.WebResource;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
String response = resource.entity(request, MediaType.TEXT_PLAIN_TYPE).get(String.class);
...

例3-15に、リクエスト・エンティティのメディア・タイプのみを構成する方法の例を示します。

例3-15 リクエスト・エンティティのメディア・タイプのみの構成

import com.sun.jersey.api.client.WebResource;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
String response = resource.type(MediaType.TEXT_PLAIN_TYPE).get(String.class);
...

リソースからのレスポンスの受信

「HTTPリクエストの送信方法」で説明したように、HTTPメソッドの呼出し時に、レスポンスにエンティティのJavaタイプ(または表現)を定義します。

レスポンス・メタデータが必要な場合、Javaタイプcom.sun.jersey.api.client.ClientResponseをレスポンス・タイプとして宣言します。ClientResponseタイプを使用すると、ステータス、ヘッダーおよびエンティティ情報にアクセスできます。

次の項で、ClientResponseを使用してアクセスできるレスポンス・メタデータについて説明します。ClientResponseの詳細は、https://jersey.java.net/apidocs/1.13/jersey/index.html?com/sun/jersey/api/client/ClientResponse.htmlを参照してください。

- リクエストのステータスへのアクセス方法

- レスポンス・エンティティの取得方法

リクエストのステータスへのアクセス方法

ClientResponseオブジェクトでgetStatusメソッドを使用して、クライアント・レスポンスのステータスにアクセスします。有効なステータス・コードのリストは、https://jersey.java.net/apidocs/1.13/jersey/index.html?com/sun/jersey/api/client/ClientResponse.Status.htmlを参照してください。

例3-12に、レスポンスのステータス・コードにアクセスする方法の例を示します。

例3-16 リクエストのステータスへのアクセス

import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.ClientResponse;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
ClientResponse response = resource.get(ClientResponse.class);
int status = response.getStatus();
...

レスポンス・エンティティの取得方法

ClientResponseオブジェクトでgetEntityメソッドを使用して、レスポンス・エンティティを取得します。

例3-12に、レスポンス・エンティティを取得する方法の例を示します。

例3-17 レスポンス・エンティティの取得

import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.ClientResponse;
...
public static void main(String[] args) {
...
WebResource resource = c.resource("http://example.com/helloWorld");
ClientResponse response = resource.get(ClientResponse.class);
String entity = response.getEntity(String.class);
...

高度なRESTful Webサービス・クライアント・タスク

次に示すものを含む、高度なRESTful Webサービス・クライアント・タスクの詳細は、『Jersey 1.9 User Guide』(https://jersey.java.net/nonav/documentation/1.13/user-guide.html)を参照してください。

- 表現タイプの追加

- フィルタの使用

- HTTP URLConnectionを使用したセキュリティの有効化

スタンドアロン・クライアントからのRESTful Webサービスの呼出し

Oracle Fusion MiddlewareまたはWebLogic Serverがローカルにインストールされていない環境からRESTful Webサービスを呼び出す場合、CLASSPATHにOracle Fusion MiddlewareまたはWebLogic Serverクラスの完全なセットが含まれていれば、スタンドアロン・クライアントJARファイルを使用してWebサービスを呼び出すことができます。

スタンドアロン・クライアントJARは、基本的なJAX-RSのクライアント側の機能およびOWSMセキュリティ・ポリシーをサポートしています。

クライアント・アプリケーションでスタンドアロン・クライアントJARファイルを使用するには、次の手順を実行します。

1. Oracle JDeveloperなど好みのIDEを使用して、Java SEクライアントを作成します。詳細は、『Oracle JDeveloperによるアプリケーションの開発』のWebサービスとクライアントの開発および保護に関する項を参照してください。

2. ORACLE_HOME/oracle_common/modules/clients/com.oracle.jersey.fmw.client_12.1.2.jarファイルを、Oracle Fusion Middlewareをホストするコンピュータからクライアント・コンピュータにコピーします。ORACLE_HOMEは、Oracle Fusion Middlewareのインストール時にOracleホームとして指定したディレクトリです。
たとえば、クライアント・アプリケーションで使用している他のクラスが格納されているディレクトリにファイルをコピーします。

3. JARファイルをCLASSPATHに追加します。

注意:

CLASSPATHには、スタンドアロン・クライアントJARファイルで使用されるAntクラスのサブセットを含むJARファイル(ant.jar)が確実に格納されるようにしてください。このJARファイルは通常、Antディストリビューションのlibディレクトリ内にあります。

4. Oracle Web Services Manager (OWSM)ポリシーの環境を構成します。この手順は任意であり、OWSMセキュリティ・ポリシーをRESTfulクライアントにアタッチする場合にのみ必要です。
必要な構成手順は、アタッチされるポリシーのタイプによって異なります。以下に例を示します。その他の構成要件は、『Oracle Platform Security Servicesによるアプリケーションの保護』のOPSSを使用するためのJava SEアプリケーションの構成に関する項を参照してください。

注意:

Jersey JAX-RS RIクライアントAPIにアクセスするには、weblogic.jaxrs.api.client.Clientクラスのインスタンスを作成する必要があります。

かわりに、com.sun.jersey.api.client.Clientクラスのインスタンスを作成することもできます。ただし、「OWSMポリシーを使用したRESTful Webサービスとクライアントの保護」で説明しているような、Oracle Web Services Manager (OWSM)ポリシーを使用したRESTfulクライアントの保護などのOracle拡張機能は利用できません。

例: 基本認証

たとえば、oracle/wss_http_token_client_policyセキュリティ・ポリシーを使用して基本認証をサポートするには、次の手順を実行します。

1. jps-config-jse.xmlファイルおよびaudit-store.xmlファイルを、domain_home/config/fmwconfigディレクトリ(domain_homeはドメインの名前と場所)から、RESTfulクライアントにアクセス可能な場所にコピーします。

2. 手順2でファイルをコピーした場所にウォレット(cwallet.sso)を作成します。このウォレットには、oracle.wsm.securityという名前のマップと、クライアント・アプリケーションが使用する資格証明キー名(たとえばweblogic-csf-key)を定義します。
ファイルcwallet.ssoの場所は、構成ファイルjps-config-jse.xmlの<serviceInstance要素で指定されます。詳細は、『Oracle Platform Security Servicesによるアプリケーションの保護』のウォレットベースの資格証明ストアの使用に関する項を参照してください。

3. Javaコマンド・ラインで次のプロパティを渡して、手順1でコピーしたJPS構成ファイルを定義します。

-Doracle.security.jps.config=<pathToConfigFile>

詳細は、『Oracle Platform Security Servicesによるアプリケーションの保護』の「シナリオ3: Java SEアプリケーションの保護」を参照してください。

例: SSL

たとえば、SSLポリシーをサポートするには、次の手順を実行します。

1. jps-config-jse.xmlファイルおよびaudit-store.xmlファイルを、domain_home/config/fmwconfigディレクトリ(domain_homeはドメインの名前と場所)から、RESTfulクライアントにアクセス可能な場所にコピーします。

2. Javaコマンド・ラインで次のプロパティを渡します: 手順1でコピーしたJPS構成ファイルを定義する:
手順1でコピーしたJPS構成ファイルを定義する:

-Doracle.security.jps.config=<pathToConfigFile>

詳細は、『Oracle Platform Security Servicesによるアプリケーションの保護』の「シナリオ3: Java SEアプリケーションの保護」を参照してください。

信頼できる証明書を含むトラスト・ストアを定義する:

-Djavax.net.ssl.trustStore=<trustStore>

詳細は、『Oracle Platform Security Servicesによるアプリケーションの保護』のLDAPへの一方向SSL接続の設定に関する項に記載されている、Java SEアプリケーションの場合のWebLogic Serverの設定に関する項を参照してください。

トラスト・ストアのパスワードを定義する:

-Djavax.net.ssl.trustStorePassword=<password>

4 RESTful Webサービスのパッケージ化とデプロイ

この章では、Java API for RESTful Web Services (JAX-RS)を使用して、Representational State Transfer (REST)アーキテクチャ・スタイルに従ったWebLogic Webサービスをパッケージ化およびデプロイする方法について説明します。

この章では、以下のトピックについて説明します。

- RESTful Webサービスのパッケージ化とデプロイメントについて

- アプリケーション・サブクラスとのパッケージ化

- サーブレットとのパッケージ化

- デフォルト・リソースとしてのパッケージ化

RESTful Webサービスのパッケージ化とデプロイメントについて

すべてのRESTful Webサービス・アプリケーションはWebアプリケーションの一部としてパッケージ化される必要があります。WebサービスがEJBとして実装される場合、WAR内にパッケージ化およびデプロイされる必要があります。Webアプリケーションのデプロイの詳細は、『Oracle WebLogic Serverへのアプリケーションのデプロイ』のWebLogic Serverデプロイメントの理解に関する項を参照してください。

表4-1に、RESTful Webサービス・アプリケーションに使用できる特定のパッケージ化オプションの概要を示します。

表4-1 RESTful Webサービス・アプリケーションのパッケージ化オプション

パッケージ化オプション

説明

アプリケーション・サブクラス

javax.ws.rs.core.Applicationを拡張するクラスを定義して、RESTful Webサービス・アプリケーション・デプロイメントのコンポーネントを定義し、追加のメタデータを提供します。javax.ws.rs.ApplicationPathアノテーションをサブクラスに追加して、サーブレットのコンテキスト・パスを構成できます。詳細は、「アプリケーション・サブクラスとのパッケージ化」を参照してください。

サーブレット

web.xmlデプロイメント記述子を更新して、サーブレットおよびマッピングを構成します。使用されるメソッドはWebアプリケーションがサーブレット3.0またはそれ以前を使用しているかどうかにより異なります。詳細は、「サーブレットとのパッケージ化」を参照してください。

デフォルト・リソース

上記のオプションのいずれかを使用して、構成内にサーブレットのコンテキスト・パスを構成しない場合、WebLogic ServerはデフォルトのRESTful Webサービス・アプリケーション・サーブレットのコンテキスト・パスresourcesを提供します。詳細は、「デフォルト・リソースとしてのパッケージ化」を参照してください。

アプリケーション・サブクラスとのパッケージ化

このパッケージ化シナリオでは、javax.ws.rs.core.Applicationを拡張するクラスを作成して、RESTful Webサービス・アプリケーション・デプロイメントのコンポーネントを定義し、追加のメタデータを提供します。javax.ws.rs.core.Applicationの詳細は、Javadoc (http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/core/Application.html)を参照してください。

Applicationサブクラス内で、必要に応じて、getClasses()およびgetSingletons()メソッドをオーバーライドし、RESTful Webサービス・リソースのリストを戻します。リソースはそれを戻すApplicationサブクラスにバインドされます。

両方のメソッドが同じリソースを戻す場合、エラーが戻されることに注意してください。

javax.ws.rs.ApplicationPathアノテーションを使用して、サーブレットにマップされる基底URIパターンを定義します。この情報がリソースの基底URIで使用される方法の詳細は、「実行時の処理: 基底URIの構成方法」を参照してください。@ApplicationPathアノテーションの詳細は、Javadoc (http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/ApplicationPath.html)を参照してください。

単純なデプロイメントの場合、web.xmlデプロイメント記述子は必要ありません。より複雑なデプロイメントの場合、たとえばWebサービスの保護や初期化パラメータの指定の際は、「サーブレットとのパッケージ化」に示すように、web.xmlデプロイメント記述子をアプリケーションでパッケージ化できます。

例4-1に、javax.ws.rs.core.Applicationを拡張し、@ApplicationPathアノテーションを使用してリソースの基底URIを定義するクラスの例を示します。

例4-1 javax.ws.rs.core.Applicationを拡張するクラスの例

import javax.ws.rs.core.Application;
javax.ws.rs.ApplicationPath;
...
@ApplicationPath("resources")
public class MyApplication extends Application {
public Set<Class<?>> getClasses() {
Set<Class<?>> s = new HashSet<Class<?>>();
s.add(HelloWorldResource.class);
return s;
}
}

サーブレットとのパッケージ化

次の項では、Webアプリケーションがサーブレット3.0またはそれ以前を使用しているかどうかに基づき、web.xmlデプロイメント記述子を使用して、RESTful Webサービス・アプリケーションのサーブレットとのパッケージ化の方法について説明します。

- RESTful Webサービス・アプリケーションのサーブレット3.0とのパッケージ化方法

- RESTful Webサービス・アプリケーションの3.0以前のサーブレットとのパッケージ化方法

web.xmlファイルは、アプリケーション・アーカイブのルート・ディレクトリのWEB-INFディレクトリにあります。web.xmlデプロイメント記述子の詳細は、Oracle WebLogic ServerのためのWebアプリケーション、サーブレットおよびJSPの開発のweb.xmlデプロイメント記述子の要素に関する項を参照してください。

注意:

3.0以前のサーブレットを使用するWebアプリケーションを実行している場合、「サーブレットとのパッケージ化」を参照してください。この項は、サーブレット3.0を実行しているWebアプリケーションにのみ適用されます。

RESTful Webサービス・アプリケーションのサーブレット3.0とのパッケージ化方法

RESTful Webサービス・アプリケーションをサーブレット3.0とパッケージ化するには、web.xmlデプロイメント記述子を更新し、次の項に定義された要素を定義します。要素は、javax.ws.rs.core.Applicationを拡張するクラスをパッケージに含めるかどうかで変わります。

- アプリケーション・サブクラスのあるweb.xmlを使用したRESTful Webサービス・アプリケーションのパッケージ化

- アプリケーション・サブクラスのないweb.xmlを使用したRESTful Webサービス・アプリケーションのパッケージ化

要素の詳細は、『Oracle WebLogic Server Webアプリケーション、サーブレット、JSPの開発』のサーブレットに関する項を参照してください。

アプリケーション・サブクラスのあるweb.xmlを使用したRESTful Webサービス・アプリケーションのパッケージ化

javax.ws.rs.core.Applicationを拡張するクラスがweb.xmlとともにパッケージ化されている場合、要素を表4-2に示すように定義します。たとえば、例4-1を参照してください。

表4-2 アプリケーション・サブクラスのあるweb.xmlを使用したRESTful Webサービス・アプリケーションのパッケージ化

要素

説明

<servlet-name>

この要素を、javax.ws.rs.core.Applicationを拡張するクラスの完全修飾名に設定します。複数のサーブレット・エンティティを指定して、複数のApplicationサブクラス名を定義することもできます。

<servlet-class>

必要ありません。

<init-param>

この要素を、javax.ws.rs.core.Applicationを拡張するクラスを定義するように設定します。

<init-param>
<param-name>
javax.ws.rs.Application
</param-name>
<param-value>
ApplicationSubclassName
</param-value>
</init-param>

<servlet-mapping

サーブレットにマップされる基底URIパターンとして設定します。

指定されない場合、次の優先順位に従って、次の値のいずれかが使用されます。

- javax.ws.rs.core.Applicationサブクラスに定義された@ApplicationPathアノテーション値。以下に例を示します。

package test;
@ApplicationPath("res")
public class MyJaxRsApplication extends java.ws.rs.core.Application
...

詳細は、「アプリケーション・サブクラスとのパッケージ化」を参照してください。

- 値resources。これはRESTful Webサービス・アプリケーションのデフォルトの基底URIパターンです。詳細は、「デフォルト・リソースとしてのパッケージ化」を参照してください。

<servlet-mapping>と@ApplicationPathの両方が指定されている場合、<servlet-mapping>が優先されます。

この情報がリソースの基底URIで使用される方法の詳細は、「実行時の処理: 基底URIの構成方法」を参照してください。

次に、javax.ws.rs.core.Applicationを拡張するクラスがweb.xmlとパッケージ化される場合に、web.xmlファイルを更新する方法の例を示します。

例4-2 アプリケーション・サブクラスがパッケージ内にある場合のサーブレット3.0用web.xmlの更新

<web-app>
<servlet>
<display-name>My JAX-RS Servlet</display-name>
<servlet-name>jersey.samples.MyApplication</servlet-name>
<init-param>
<param-name>javax.ws.rs.Application</param-name>
<param-value>myPackage.myJaxRsApplication</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>MyJaxRsApp</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>

アプリケーション・サブクラスのないweb.xmlを使用したRESTful Webサービス・アプリケーションのパッケージ化

javax.ws.rs.core.Applicationを拡張するクラスがweb.xmlとともにパッケージ化されていない場合は、表4-3に示すように要素を定義します。

注意:

このシナリオでは、複数のRESTful Webサービス・アプリケーションはサポートされません。

表4-3 アプリケーション・サブクラスのないweb.xmlを使用したRESTful Webサービス・アプリケーションのパッケージ化

要素

説明

<servlet-name>

この要素を対象のサーブレット名に設定します。

<servlet-class>

この要素を、すべてのWebリクエストをJerseyサーブレットに委任するように、次のいずれかのクラスに設定します。

- weblogic.jaxrs.server.portable.servlet.ServletContainer

- com.sun.jersey.spi.container.servlet.ServletContainer

<init-param>

この要素を、javax.ws.rs.Applicationを拡張するクラスを定義するように設定します。

<init-param>
<param-name>
javax.ws.rs.Application
</param-name>
<param-value>
ApplicationSubclassName
</param-value>
</init-param>

<servlet-mapping

サーブレットにマップされる基底URIパターンとして設定します。指定しない場合、この値のデフォルトはresourcesです。詳細は、「デフォルト・リソースとしてのパッケージ化」を参照してください。

この情報がリソースの基底URIで使用される方法の詳細は、「実行時の処理: 基底URIの構成方法」を参照してください。

次に、javax.ws.rs.core.Applicationを拡張するクラスがweb.xmlとパッケージ化されない場合、web.xmlファイルを更新する方法の例を示します。

例4-3 アプリケーション・サブクラスがパッケージ内にない場合のサーブレット3.0用web.xmlの更新

<web-app>
<servlet>
<servlet-name>RestServlet</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>RestServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
</web-app>

RESTful Webサービス・アプリケーションの3.0以前のサーブレットとのパッケージ化方法

表4-4に、RESTful Webサービス・アプリケーションを3.0以前のサーブレットとパッケージ化するために、web.xmlデプロイメント記述子で更新する要素を示します。

表4-4 RESTful Webサービス・アプリケーションの3.0以前のサーブレットとのパッケージ化

要素

説明

<servlet-name>

この要素を対象のサーブレット名に設定します。

<servlet-class>

この要素を、すべてのWebリクエストをJerseyサーブレットに委任するように、次のいずれかのクラスに設定します。

- weblogic.jaxrs.server.portable.servlet.ServletContainer

- com.sun.jersey.spi.container.servlet.ServletContainer

<init-param>

この要素を、javax.ws.rs.core.Applicationを拡張するクラスを定義するように設定します。

<init-param>
<param-name>
javax.ws.rs.Application
</param-name>
<param-value>
ApplicationSubclassName
</param-value>
</init-param>

また、次のようにアプリケーション内でパッケージを宣言することもできます。

<init-param>
<param-name>
com.sun.jersey.config.property.packages
</param-name>
<param-value>
project1
</param-value>
</init-param>

<servlet-mapping

サーブレットにマップされる基底URIパターンとして設定します。

指定されない場合、次の優先順位に従って、次の値のいずれかが使用されます。

- javax.ws.rs.core.Applicationサブクラスに定義された@ApplicationPathアノテーション値。以下に例を示します。

package test;
@ApplicationPath("res")
public class MyJaxRsApplication extends java.ws.rs.core.Application
...

詳細は、「アプリケーション・サブクラスとのパッケージ化」を参照してください。

- 値resources。これはRESTful Webサービス・アプリケーションのデフォルトの基底URIパターンです。詳細は、「デフォルト・リソースとしてのパッケージ化」を参照してください。

<servlet-mapping>と@ApplicationPathの両方が指定されている場合、<servlet-mapping>が優先されます。

この情報がリソースの基底URIで使用される方法の詳細は、「実行時の処理: 基底URIの構成方法」を参照してください。

次に、javax.ws.rs.core.Applicationを拡張するクラスがweb.xmlとパッケージ化されない場合、web.xmlファイルを更新する方法の例を示します。

例4-4 3.0以前のサーブレット用web.xmlの更新

<web-app>
<servlet>
<display-name>My JAX-RS Servlet</display-name>
<servlet-name>javax.ws.rs.core.Application</servlet-name>
<servlet-class>weblogic.jaxrs.server.portable.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.resourceConfigClass</param-name>
<param-value>com.sun.jersey.api.core.PackagesResourceConfig</param-value>
</init-param>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>project1</param-value>
</init-param>
</servlet>
</web-app>

デフォルト・リソースとしてのパッケージ化

デフォルトでは、WebLogic ServerはデフォルトのRESTful Webサービス・アプリケーションのコンテキスト・パスresourcesを定義します。デフォルトRESTful Webサービス・アプリケーションのコンテキスト・パスは、次のことが当てはまる場合に使用されます。

- サーブレットのマッピングを含むweb.xmlデプロイメント記述子を更新しなかった(「サーブレットとのパッケージ化」を参照)。

- @ApplicationPathアノテーションがjavax.ws.rs.core.Applicationサブクラスで定義されなかった(「アプリケーション・サブクラスとのパッケージ化」を参照)。

注意:

サーブレットがすでにデフォルトのコンテキスト・パスに登録されている場合、警告が発行されます。

たとえば、RESTful Webサービス・アプリケーションのルート・リソース・クラスの相対URIが@Path('/helloworld')として定義され、デフォルトのRESTful Webサービス・アプリケーションのコンテキスト・パスが使用されている場合、RESTful Webサービス・アプリケーションのリソースは次で使用可能です。

http://<host>:<port>/contextPath/resources/helloworld

5 RESTful Webサービスとクライアントの保護

この章では、Java API for RESTful Web Services (JAX-RS)を使用して、Representational State Transfer (REST)アーキテクチャ・スタイルに従ったWebLogic Webサービスを保護する方法について説明します。

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

- RESTful Webサービス・セキュリティの概要

- OWSMポリシーを使用したRESTful Webサービスとクライアントの保護

- web.xmlを使用したRESTful Webサービスの保護

- SecurityContextを使用したRESTful Webサービスの保護

- Javaセキュリティ・アノテーションを使用したRESTful Webサービスの保護

Oracle JDeveloperを使用したRESTful Webサービス・クライアントの開発の詳細は、『Oracle JDeveloperによるアプリケーションの開発』のRESTful Webサービスとクライアントにポリシーをアタッチする方法に関する項を参照してください。

RESTful Webサービス・セキュリティの概要

認証、認可または暗号化をサポートするための次のいずれかのメソッドを使用して、RESTful Webサービスを保護できます。

- Oracle Web Services Manager (OWSM)ポリシーのアタッチ。「OWSMポリシーを使用したRESTful Webサービスとクライアントの保護」を参照してください。

- web.xmlデプロイメント記述子の更新による、認証されたユーザーに関する情報へのアクセス。「web.xmlを使用したRESTful Webサービスの保護」を参照してください。

- javax.ws.rs.core.SecurityContextインタフェースを使用した、リクエストのセキュリティ関連情報へのアクセス。「SecurityContextを使用したRESTful Webサービスの保護」を参照してください。

- JAX-RSクラスへのアノテーションの適用。「Javaセキュリティ・アノテーションを使用したRESTful Webサービスの保護」を参照してください。

OWSMポリシーを使用したRESTful Webサービスとクライアントの保護

RESTful Webサービスでは、OWSMセキュリティ・ポリシーのサブセットのみがサポートされます。詳細は、『Oracle Web Services ManagerによるWebサービスの保護とポリシーの管理』のRESTful WebサービスでサポートされるOWSMポリシーに関する項を参照してください。

OWSMセキュリティ・ポリシーをRESTful Webサービスにアタッチするには、次のいずれかの方法を使用します。

- 設計時にプログラムを使用してアタッチする。詳細は、『Oracle Web Services ManagerによるWebサービスの保護とポリシーの管理』の設計時にポリシーをRESTful Webサービスとクライアントにアタッチする方法に関する項を参照してください。

- デプロイメント後に直接およびグローバルにアタッチする。次の方法を使用します。

- Fusion Middleware Control。詳細は、『Oracle Web Services ManagerによるWebサービスの保護とポリシーの管理』のFusion Middleware Controlを使用してポリシーをアタッチする方法に関する項を参照してください。

- WLST。詳細は、『Oracle Web Services ManagerによるWebサービスの保護とポリシーの管理』のWLSTを使用してポリシーをアタッチする方法に関する項を参照してください。

例5-1は、WLSTを使用してoracle/http_basic_auth_over_ssl_service_policyポリシーをRESTfulサービスにアタッチする例を示しています詳細は、『Oracle Web Services ManagerによるWebサービスの保護とポリシーの管理』のWLSTを使用してポリシーを直接アタッチする方法に関する項を参照してください。

例5-1 WLSTでOWSMポリシーを使用したRESTful Webサービスの保護

C:\Oracle\Middleware\oracle_common\common\bin> wlst.cmd
...
wls:/offline> connect("weblogic","password","t3://myAdminServer.example.com:7001")
Connecting to t3://myAdminServer.example.com:7001" with userid weblogic ...
Successfully connected to Admin Server "AdminServer" that belongs to domain "my_domain".

Warning: An insecure protocol was used to connect to the
server. To ensure on-the-wire security, the SSL port or
Admin port should be used instead.

wls:/my_domain/serverConfig> beginWSMSession()
Location changed to domainRuntime tree. This is a read-only tree with DomainMBean as the root.
For more help, use help('domainRuntime')

Session started for modification.
wls:/my_domain/serverConfig> selectWSMPolicySubject('weblogic/my_domain/jaxrs_pack', '#jaxrs_pack.war', 'REST-Resource(Jersey)')

The policy subject is selected for modification.

wls:/my_domain/serverConfig> attachWSMPolicy('oracle/http_basic_auth_over_ssl_service_policy')

Policy reference "oracle/http_basic_auth_over_ssl_service_policy" added.

wls:/my_domain/serverConfig> commitWSMSession()

The policy set for subject "/weblogic/my_domain/jaxrs_pack|#jaxrs_pack.war|REST-Resource(Jersey)" was saved successfully.

web.xmlを使用したRESTful Webサービスの保護

web.xmlデプロイメント記述子を他のJava EE Webアプリケーションと同様に使用して、RESTful Webサービスを保護します。詳細は、次を参照してください。

- 『WebLogicセキュリティ・サービスによるアプリケーションの開発』のセキュアなWebアプリケーションの開発に関する項。

- 『The Java EE 6 Tutorial』の「Securing Web Applications」(http://docs.oracle.com/javaee/6/tutorial/doc/gkbaa.html)。

たとえば、基本認証を使用してRESTful Webサービスを保護するには、次のステップを実行します。

1. 保護する予定のRESTfulリソース(URI)の各セットについて<security-constraint>を定義します。

2. <login-config>要素を使用して、使用する認証のタイプとセキュリティ制約が適用されるセキュリティ・レルムを定義します。

3. <security-roleタグを使用して1つ以上のセキュリティ・ロールを定義し、ステップ1で定義されたセキュリティ制約にマッピングします。詳細は、『WebLogicセキュリティ・サービスによるアプリケーションの開発』のsecurity-roleに関する項を参照してください。

4. 暗号化を有効にするには、<user-data-constraint要素を追加して<transport-guaranteeサブ要素をCONFIDENTIALに設定します。詳細は、『WebLogicセキュリティ・サービスによるアプリケーションの開発』のuser-data-constraintに関する項を参照してください。

次に、基本認証を使用してRESTful Webサービスを保護する方法の例を示します。

例5-2 基本認証を使用したRESTful Webサービスの保護

<web-app>
<servlet>
<servlet-name>RestServlet</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>RestServlet</servlet-name>
<url-pattern>/*</url-pattern>
</servlet-mapping>
<security-constraint>
<web-resource-collection>
<web-resource-name>Orders</web-resource-name>
<url-pattern>/orders</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
</web-resource-collection>
<auth-constraint>
<role-name>admin</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>default</realm-name>
</login-config>
<security-role>
<role-name>admin</role-name>
</security-role>
</web-app>

SecurityContextを使用したRESTful Webサービスの保護

javax.ws.rs.core.SecurityContextインタフェースはリクエストのセキュリティ関連情報に対するアクセスを提供します。SecurityContextはjavax.servlet.http.HttpServletRequestと同様の機能を提供して、次のセキュリティ関連情報へのアクセスを可能にします。

- リクエストを作成したユーザーの名前が含まれるjava.security.Principalオブジェクト。

- リソースの保護に使用される認証タイプ(BASIC_AUTH、FORM_AUTH、CLIENT_CERT_AUTHなど)。

- 認証されたユーザーが特定のロールに含まれているかどうか。

- リクエストが安全なチャネル(HTTPSなど)を使用して作成されたかどうか。

javax.ws.rs.core.Contextアノテーションを使用してインスタンスをクラス・フィールド、セッター・メソッドまたはメソッド・パラメータに注入することで、SecurityContextにアクセスします。

詳細は次のJavadocを参照してください。

- SecurityContextインタフェース: http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/core/SecurityContext.html

- @Contextアノテーション: http://docs.oracle.com/javaee/6/api/index.html?javax/ws/rs/core/Context.html

例5-3に、@Contextアノテーションを使用してSecurityContextのインスタンスをscメソッド・パラメータに注入し、レスポンスを返す前に、認可されたユーザーがadminロールに含まれているかどうかを確認する方法を示します。

例5-3 SecurityContextを使用したRESTful Webサービスの保護

package samples.helloworld;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.SecurityContext;
import javax.ws.rs.core.Context;

...

@Path("/stateless")
@Stateless(name = "JaxRSStatelessEJB")
public class StlsEJBApp {
...
@GET
@Produces("text/plain;charset=UTF-8")
@Path("/hello")
public String sayHello(@Context SecurityContext sc) {
if (sc.isUserInRole("admin"))  return "Hello World!";
throw new SecurityException("User is unauthorized.");
}

Javaセキュリティ・アノテーションを使用したRESTful Webサービスの保護

javax.annotation.securityパッケージは、表5-1で定義されている、RESTful Webサービスの保護に使用できるアノテーションを提供します。詳細については、以下を参照してください。

- 『The Java EE Tutorial』の「Specifying Authorized Users by Declaring Security Roles」。

- javax.annotation.securityのJavadoc

表5-1 RESTful Webサービスを保護するためのアノテーション

アノテーション

説明

DenyAll

特定のメソッドがどのセキュリティ・ロールでも呼び出せないことを指定します。

PermitAll

特定のメソッドがすべてのセキュリティ・ロールで呼び出せることを指定します。

RolesAllowed

アプリケーション内のメソッドを呼び出すことができるセキュリティ・ロールのリストを指定します。

例5-4に、helloWorldクラスに定義されたメソッドへのアクセスをデフォルトで許可されている、セキュリティ・ロールの定義方法を示します。sayHelloメソッドは、デフォルトをオーバーライドし、ADMINセキュリティ・ロールに属すユーザーのみを許可するために、@RolesAllowsアノテーションが付けられます。

例5-4 Javaセキュリティ・アノテーションを使用したRESTful Webサービスの保護

package samples.helloworld;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.annotation.Security.RolesAllowed;

@Path("/helloworld")
@RolesAllowed({"ADMIN", "ORG1"})
public class helloWorld {

@GET
@Path("sayHello")
@Produces("text/plain")
@RolesAllows("ADMIN")
public String sayHello() {
return "Hello World!";
}
}

6 RESTful Webサービスのテスト

この章では、Java API for RESTful Web Services (JAX-RS)を使用して、Representational State Transfer (REST)アーキテクチャ・スタイルに従ったWebLogic Webサービスをテストする方法について説明します。

RESTful Webサービスを含むWebアプリケーションをWebLogic Serverにデプロイすると、アプリケーションをテストできます。表6-1に、RESTful Webサービスのテストに使用できるメソッドを示します。

表6-1 RESTful Webサービスのテスト用メソッド

メソッド

説明

Enterprise Manager Fusion Middleware Control

Enterprise Manager Fusion Middleware Controlに付属のテスト・インタフェースを使用して、RESTful Webサービスのリソース・メソッドをテストします。詳細は、『Oracle Web Services ManagerによるWebサービスの保護とポリシーの管理』のRESTful Webサービスのテストに関する項を参照してください。

管理コンソール

管理コンソールで、アプリケーション・デプロイメントの「テスト」タブに移動して、アプリケーション・デプロイメントを検証し、WADLファイルを表示します。詳細は、Oracle WebLogic Server管理コンソール・オンライン・ヘルプのRESTful Webサービスのテストに関する項を参照してください。

7 RESTful Webサービスとクライアントの監視

この章では、Java API for RESTful Web Services (JAX-RS)を使用して、Representational State Transfer (REST)アーキテクチャ・スタイルに従ったWebLogic Webサービスを監視する方法について説明します。

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

- RESTful Webサービスの監視について

- Enterprise Manager Fusion Middleware Controlを使用したRESTful Webサービスの監視

- 管理コンソールを使用したRESTful Webサービスの監視

- WLSTを使用したRESTful Webサービスの監視

- トレース機能の有効化

RESTful Webサービスの監視について

RESTful Webサービスを監視するには、表7-1に定義されているいずれかのメソッドを使用します。

表7-1 RESTful Webサービスの監視用メソッド

メソッド

説明

Enterprise Manager Fusion Middleware Control

実行時情報にアクセスし、実行時統計を監視します。詳細は、「Enterprise Manager Fusion Middleware Controlを使用したRESTful Webサービスの監視」を参照してください。

WebLogic Server管理コンソール

実行時情報にアクセスし、実行時統計を監視します。詳細は、「管理コンソールを使用したRESTful Webサービスの監視」を参照してください。

WebLogic Scripting Tool (WLST)

実行時情報にアクセスし、実行時統計を監視します。詳細は、「WLSTを使用したRESTful Webサービスの監視」を参照してください。

ログ・フィルタ

リクエストが処理される方法と、Jersey JAX-RS RIコンポーネントにディスパッチされる方法を監視します。詳細は、「トレース機能の有効化」を参照してください。

Enterprise Manager Fusion Middleware Controlを使用したRESTful Webサービスの監視

Enterprise Manager Fusion Middleware Controlを使用すると、RESTfulアプリケーションおよびリソースの統計(エラー数、呼出し回数、実行回数など)を監視できます。詳細は、『Webサービスの管理』のWebサービスの監視に関する項を参照してください。

管理コンソールを使用したRESTful Webサービスの監視

管理コンソールを使用すると、RESTfulアプリケーションおよびリソースの統計(エラー数、呼出し回数、実行回数など)を監視できます。

管理コンソールを使用してデプロイ済RESTful Webサービスを監視するには、次の手順を実行します。

1. 次のURLを使用して、ブラウザで管理コンソールを呼び出します。

http://[host]:[port]/console

各文字列の説明:

- host - WebLogic Serverが動作しているコンピュータの名前。

- port - WebLogic Serverがリスニングしているポート番号(デフォルト値は7001です)。

2. Oracle WebLogic Server管理コンソール・オンライン・ヘルプのRESTful Webサービスの監視に関する項で説明されている手順に従います。

WLSTを使用したRESTful Webサービスの監視

WebLogic Serverは表7-2に定義されたものを含む、ランタイムMBeanを提供し、これにより、実行時情報を取得し、RESTful Webサービス・アプリケーションの実行時統計を監視することができます。

表7-2 RESTful Webサービスの監視用ランタイムMBean

ランタイムMBean

説明

JaxRsApplication

RESTful Webサービス・アプリケーションの監視情報を表示します。詳細は、WebLogic Server MBean リファレンスのJaxRsApplicationRuntimeBeanに関する項を参照してください。

ResourceConfig

RESTful Webサービス・アプリケーションのリソース構成に関する監視情報を表示します。詳細は、WebLogic Server MBean リファレンスのJaxRsResourceConfigTypeRuntimeBeanに関する項を参照してください。

RootResources

RESTful Webサービスのリソースに関する監視情報を表示します。コンテナにより管理されるすべてのオブジェクト(EJBなど)はアプリケーション・スコープを含みます。その他のすべてのリソースはデフォルトでリクエスト・スコープを含みます。詳細は、WebLogic Server MBean リファレンスのJaxRsResourceRuntimeBeanに関する項を参照してください。

Servlet

RESTful Webサービス・アプリケーションをホストするサーブレットの監視情報を表示します。詳細は、WebLogic Server MBean リファレンスのServletRuntimeMBeanに関する項を参照してください。

WLSTを使用してRESTful Webサービスを監視するには、次のプロシージャで提供される手順を実行します。

このプロシージャでは、手順の例により、WebLogic Serverのサンプル・サーバーとともに提供されるRESTful Webサービス・サンプルの監視方法を示します。『Oracle WebLogic Serverの理解』のサンプル・アプリケーションとコード例に関する項を参照してください。

1. 『WebLogic Scripting Toolの理解』のWLSTの呼出しに関する項の説明に従って、WLSTを呼び出します。
以下に例を示します。

c:\> java weblogic.WLST

2. 『WebLogic Server WLSTコマンド・リファレンス』のconnectに関する項の説明に従って、管理サーバー・インスタンスに接続します。
以下に例を示します。

wls:/offline> connect('weblogic','password','t3://localhost:8001')

3. 『WebLogic Server WLSTコマンド・リファレンス』のserverRuntimeに関する項の説明に従って、サーバー・ランタイムMBeanに移動します。
以下に例を示します。

wls:/wl_server/serverConfig> serverRuntime()
Location changed to serverRuntime tree. This is a read-only tree
with ServerRuntimeMBean as the root.
For more help, use help('serverRuntime')
wls:/wl_server/serverRuntime>

4. Webアプリケーション・コンポーネント・ランタイムMBeanに移動します。
たとえば、jaxrsという名前のアプリケーションのランタイムMBeanに移動するには、次を実行します。

wls:/wl_server/serverRuntime> cd('ApplicationRuntimes/jaxrs')
wls:/wl_server/serverRuntime/ApplicationRuntimes/jaxrs> cd('ComponentRuntimes')
wls:/wl_server/serverRuntime/ApplicationRuntimes/jaxrs/ComponentRuntimes> cd('examplesServer_/jaxrs')

5. RESTful Webサービス・サーブレットのアプリケーション・ランタイムMBeanに移動します。
以下に例を示します。

wls:/wl_server/serverRuntime/ApplicationRuntimes/jaxrs/ComponentRuntimes/examplesServer_/jaxrs> cd('JaxRsApplications/RestServlet')

6. RESTful Webサービス・アプリケーションについて表示される監視情報を確認します。詳細は、WebLogic Server MBean リファレンスのJaxRsApplicationRuntimeBeanに関する項を参照してください。
以下に例を示します。

wls:/wl_server/serverRuntime/ApplicationRuntimes/jaxrs/ComponentRuntimes/example
sServer_/jaxrs/JaxRsApplications/RestServlet> ls()
dr--   ResourceConfig
dr--   RootResources
dr--   Servlet

-r--   ErrorCount                                   0
-r--   ExecutionTimeAverage                         0
-r--   ExecutionTimeHigh                            0
-r--   ExecutionTimeLow                             0
-r--   ExecutionTimeTotal                           0
-r--   HttpMethodCounts                             {}
-r--   InvocationCount                              0
-r--   LastErrorDetails                             null
-r--   LastErrorMapper                              null
-r--   LastErrorTime                                0
-r--   LastHttpMethod                               null
-r--   LastInvocationTime                           0
-r--   LastResponseCode                             -1
-r--   Name                                         RestServlet
-r--   ResponseCodeCounts                           {}
-r--   StartTime                                    1321907929703
-r--   Type                                         JaxRsApplicationRuntime

-r-x   preDeregister                                Void :

wls:/wl_server/serverRuntime/ApplicationRuntimes/jaxrs/ComponentRuntimes/example
sServer_/jaxrs/JaxRsApplications/RestServlet>

7. 次のいずれかのランタイムMBeanに移動して、追加の監視情報を表示します。MBeanに関する詳細は、表7-2またはWebLogic Server MBean リファレンスを参照してください。

- ResourceConfig

- RootResources

- Servlet

8. 『WebLogic Scripting Toolの理解』のWLSTの終了に関する項の説明に従って、WLSTを終了します。
以下に例を示します。

wls:/wl_server/serverRuntime/ApplicationRuntimes/jaxrs/ComponentRuntimes/example
sServer_/jaxrs/JaxRsApplications/RestServlet> exit()
Exiting WebLogic Scripting Tool ...
c:\>

トレース機能の有効化

Jerseyトレース機能は、リクエストが処理されJersey JAX-RS RIコンポーネントにディスパッチされる状況を説明する有用な情報を提供します。トレース・メッセージは発生順に出力されるので、その番号はトレース順序を再構成するのに役立ちます。

次にトレース・メッセージの例を示します。このメッセージは、リクエスト・パスと、一致する最初の正規表現のセットを、左から右の順序で示します。

例7-1 トレース・メッセージの例

Trace 001:
X-Jersey-Trace-001  match path "/items/3/tracks/2/" -> "/application\\.wadl(/.\*)?", "/happy(/.\*)?", "(/.\*)?"

この機能は、サーバー全体またはリクエストごとに有効にできます。次の項を参照してください。

- サーバー全体のトレース機能の有効化方法

- リクエストごとのトレース機能の有効化方法

サーバー全体のトレース機能の有効化方法

サーブレットにパッケージ化されたRESTful Webサービス・アプリケーション(「サーブレットとのパッケージ化」を参照)に対してサーバー全体のトレース機能を有効化できます。web.xmlファイルには次の要素が存在します。

- 次のように定義されたサーブレットクラス。

<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>

- Trueに設定された次のいずれかの<init-param>。

- com.sun.jersey.config.feature.TracePerRequest

- com.sun.jersey.config.feature.Trace

サーバー全体のトレース機能を有効にするには:

- アプリケーションとパッケージ化されたweb.xmlデプロイメント記述子を更新し、次の<init-param>要素を追加します。

<init-param>
<param-name>com.sun.jersey.config.feature.Trace</param-name>
<param-value>true</param-value>
</init-param>

<init-param要素の詳細は、『Oracle WebLogic Server Webアプリケーション、サーブレット、JSPの開発』のサーブレットに関する項を参照してください。

- com.sun.jersey.api.core.ResourceConfig.FEATURE_TRACEプロパティを有効化します。詳細は、https://jersey.java.net/apidocs/1.13/jersey/index.html?com/sun/jersey/api/core/ResourceConfig.html#FEATURE_TRACEを参照してください。

リクエストごとのトレース機能の有効化方法

サーブレットにパッケージ化されたRESTful Webサービス・アプリケーション(「サーブレットとのパッケージ化」を参照)に対してリクエストごとのトレース機能を有効化できます。web.xmlファイルには次の要素が存在します。

- 次のように定義されたサーブレットクラス。

<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>

- Trueに設定された次のいずれかの<init-param>。

- com.sun.jersey.config.feature.TracePerRequest

- com.sun.jersey.config.feature.Trace

リクエストごとのトレースでは、リクエスト・ヘッダーがX-Jersey-Trace-Acceptという名前で存在する場合に、トレース・メッセージが出力されます。

トレース・メッセージは主にX-Jersey-Trace-XXX形式のヘッダー名のレスポンス・ヘッダーとして出力され、このXXXはトレース・メッセージ番号に対応する整数値で、ヘッダー値がトレース・メッセージです。メッセージが長すぎる場合など、レスポンス・ヘッダーにトレース・メッセージを含むことができない場合、トレース・メッセージがサーバーのログに記録されることがあります。

リクエストごとのトレース機能を有効にするには:

- アプリケーションとパッケージ化されたweb.xmlデプロイメント記述子を更新し、次の<init-param>要素を追加します。

<init-param>
<param-name>com.sun.jersey.config.feature.TracePerRequest</param-name>
<param-value>true</param-value>
</init-param>

<init-param要素の詳細は、『Oracle WebLogic Server Webアプリケーション、サーブレット、JSPの開発』のサーブレットに関する項を参照してください。

- Ecom.sun.jersey.api.core.ResourceConfig.FEATURE_TRACE_PER_REQUESTプロパティを有効化します。詳細は、https://jersey.java.net/apidocs/1.13/jersey/index.html?com/sun/jersey/api/core/ResourceConfig.html#FEATURE_TRACEを参照してください。

A Jersey JAX-RS RIのバージョンの更新

この付録は、RESTful Webサービス・アプリケーションで使用するJersey JAX-RS Reference Implementation (RI)のバージョンの更新方法について説明します。

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

- Jersey JAX-RS RIのバージョンの更新について

- アプリケーション・レベルでのJersey JAX-RS RIのバージョンの更新

Jersey JAX-RS RIのバージョンの更新について

WebLogic Serverは、JSR-311 JAX-RS 1.1仕様(https://jcp.org/en/jsr/summary?id=311で定義)の製品レベル品質を実装したJersey 1.13 JAX-RS Reference Implementation (RI)をサポートしています。必要に応じて、アプリケーション・レベルでさらに新しいバージョンのJersey JAX-RS RIを使用できます。

WebLogic Serverでは、システム・クラスパスにあるJARファイルはWebLogic Serverのシステム・クラスローダーによってロードされます。サーバー・インスタンスの内部で実行されるすべてのアプリケーションは、システム・クラスローダーの子であるアプリケーション・クラスローダー内にロードされます。サード・パーティのJARがシステム・クラスローダーに存在する場合、アプリケーションはフィルタ・クラス・ローダーを使用して異なるバージョンをロードおよび使用します。

フィルタ・クラスローダーは、デプロイメント記述子を構成することで、特定のパッケージがシステム・クラスローダーによってロードされるのではなく、常にアプリケーションからロードされるように明示的に指定するメカニズムです。フィルタ・クラスローダーの使用の詳細は、『Oracle WebLogic Serverアプリケーションの開発』のフィルタ・クラスローダーの使用に関する項を参照してください。

アプリケーション・レベルでのJersey JAX-RS RIのバージョンの更新

アプリケーション・レベルでJersey JAX-RS RIのバージョンを更新するには、EARまたはWARファイルのどちらを更新するかに応じて、次のいずれかの手順を使用します。

- EARファイルでのJersey JAX-RS RIのバージョンの更新方法

- WARファイルでのJersey JAX-RS RIのバージョンの更新方法

EARファイルでのJersey JAX-RS RIのバージョンの更新方法

EARファイルでのJersey JAX-RS RIのバージョンを更新するには:

1. 優先Jersey JAX-RS RIパッケージをデプロイ済Webアプリケーションに含めます。

2. アプリケーションのEARファイルとパッケージ化されたweblogic-application.xmlデプロイメント記述子を編集し、<prefer-application-packages要素を、リストされた優先ライブラリ・パッケージに含めます。<prefer-application-packages要素をweblogic-application.xmlに追加する詳細は、『Oracle WebLogic Serverアプリケーションの開発』のweblogic-application.xmlデプロイメント記述子要素に関する項を参照してください。
例A-1に、weblogic-application.xmlファイルを更新する方法の例を示します。

例A-1 weblogic-application.xmlファイルでのJersey JAX-RS RIのバージョンの更新方法

<weblogic-web-app
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation=
"http://www.oracle.com/technology/weblogic/weblogic-web-app/1.1/weblogic-web-app.xsd"
xmlns="http://xmlns.oracle.com/weblogic/weblogic-web-app">
<prefer-application-packages>
<!-- jersey-bundle-*.jar -->
<package-name>com.sun.jersey.*</package-name>
<package-name>com.sun.research.ws.wadl.*</package-name>
<package-name>com.sun.ws.rs.ext.*</package-name>

<!-- Jackson-*.jar -->
<package-name>org.codehaus.jackson.*</package-name>

<!-- jettison-*.jar -->
<package-name>org.codehaus.jettison.*</package-name>

<!-- jsr311*.jar -->
<package-name>javax.ws.rs.*</package-name>

<!-- asm.jar -->
<package-name>org.objectweb.asm.*</package-name>
</prefer-application-packages>
...
</weblogic-web-app>

WARファイルでのJersey JAX-RS RIのバージョンの更新方法

WARファイルでのJersey JAX-RS RIのバージョンを更新するには(パッケージ化されたスタンドアロンまたはEARファイル内):

1. 優先Jersey JAX-RS RIパッケージをデプロイ済Webアプリケーションに含めます。

2. アプリケーションのWARファイルとパッケージ化されたweblogic.xmlデプロイメント記述子を編集し、<prefer-application-packages要素を、リストされた優先ライブラリ・パッケージに含めます。<prefer-application-packages要素をweblogic.xmlに追加する詳細は、『Oracle WebLogic Server Webアプリケーション、サーブレット、JSPの開発』のprefer-application-packagesに関する項を参照してください。
例A-2に、weblogic.xmlファイルを更新する方法の例を示します。

例A-2 weblogic.xmlファイルでのJersey JAX-RS RIのバージョンの更新方法

<?xml version="1.0" encoding="UTF-8"?>

<wls:weblogic-web-app
xmlns:wls="http://xmlns.oracle.com/weblogic/weblogic-web-app"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd
http://xmlns.oracle.com/weblogic/weblogic-web-app
http://xmlns.oracle.com/weblogic/weblogic-web-app/1.5/weblogic-web-app.xsd">

...
<wls:container-descriptor>
<wls:prefer-application-packages>
<!-- jersey-bundle-*.jar -->
<wls:package-name>com.sun.jersey.*</wls:package-name>
<wls:package-name>com.sun.research.ws.wadl.*</wls:package-name>
<wls:package-name>com.sun.ws.rs.ext.*</wls:package-name>

<!-- Jackson-*.jar -->
<wls:package-name>org.codehaus.jackson.*</wls:package-name>

<!-- jettison-*.jar -->
<wls:package-name>org.codehaus.jettison.*</wls:package-name>

<!-- jsr311*.jar -->
<wls:package-name>javax.ws.rs.*</wls:package-name>

<!-- asm.jar -->
<wls:package-name>org.objectweb.asm.*</wls:package-name>
</wls:prefer-application-packages>
</wls:container-descriptor>
</wls:weblogic-web-app>

オラクル社の法律上の注意点について

コピーライトについて

Copyright © 1994-2014, Oracle and/or its affiliates.All rights reserved.

商標と登録商標について

OracleおよびJavaはOracle Corporationおよびその関連企業の登録商標です。その他の名称は、それぞれの所有者の商標または登録商標です。

Intel、Intel Xeonは、Intel Corporationの商標または登録商標です。すべてのSPARCの商標はライセンスをもとに使用し、SPARC International, Inc.の商標または登録商標です。AMD、Opteron、AMDロゴ、AMD Opteronロゴは、Advanced Micro Devices, Inc.の商標または登録商標です。UNIXは、The Open Groupの登録商標です。

ライセンス制約の保証と結果的に生じる損害の免責

このソフトウェアおよび関連ドキュメントの使用と開示は、ライセンス契約の制約条件に従うものとし、知的財産に関する法律により保護されています。ライセンス契約で明示的に許諾されている場合もしくは法律によって認められている場合を除き、形式、手段に関係なく、いかなる部分も使用、複写、複製、翻訳、放送、修正、ライセンス供与、送信、配布、発表、実行、公開または表示することはできません。このソフトウェアのリバース・エンジニアリング、逆アセンブル、逆コンパイルは互換性のために法律によって規定されている場合を除き、禁止されています。

保証免責

ここに記載された情報は予告なしに変更される場合があります。また、誤りが無いことの保証はいたしかねます。誤りを見つけた場合は、オラクル社までご連絡ください。

制限付権利

このソフトウェアまたは関連ドキュメントを、米国政府機関もしくは米国政府機関に代わってこのソフトウェアまたは関連ドキュメントをライセンスされた者に提供する場合は、次の通知が適用されます。

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations.As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs.No other rights are granted to the U.S. Government.

危険な用途への使用について

このソフトウェアもしくはハードウェアは様々な情報管理アプリケーションでの一般的な使用のために開発されたものです。このソフトウェアもしくはハードウェアは、危険が伴うアプリケーション（人的傷害を発生させる可能性があるアプリケーションを含む）への用途を目的として開発されていません。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用する際、安全に使用するために、適切な安全装置、バックアップ、冗長性（redundancy）、その他の対策を講じることは使用者の責任となります。このソフトウェアもしくはハードウェアを危険が伴うアプリケーションで使用したことに起因して損害が発生しても、オラクル社およびその関連会社は一切の責任を負いかねます。

第三者のコンテンツ、製品、サービスに対する免責事項

このソフトウェアまたはハードウェア、そしてドキュメントは、第三者のコンテンツ、製品、サービスへのアクセス、あるいはそれらに関する情報を提供することがあります。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスに関して一切の責任を負わず、いかなる保証もいたしません。オラクル社およびその関連会社は、第三者のコンテンツ、製品、サービスへのアクセスまたは使用によって損失、費用、あるいは損害が発生しても一切の責任を負いかねます。

ドラフトのアルファ版およびベータ版ドキュメントについて

このドキュメントが試作版の場合:

このドキュメントは試作版であり、デモおよび暫定使用のみを目的としたものです。このソフトウェアを使用するハードウェアに限定するものではありません。オラクル社およびその関連会社は、このドキュメントに関して一切の責任を負わず、いかなる保証もいたしません。また、このドキュメントを使用したことによって損失、費用、あるいは損害が発生しても、一切の責任を負いかねます。