Menu Close

46.2. 基本的な JAX-RS アノテーション

概要

RESTful Web サービスの実装に必要な最も基本的な情報は次のとおりです。

  • サービスのリソースの URI
  • クラスのメソッドが HTTP 動詞にマップされる方法

JAX-RS は、この基本情報を提供するアノテーションのセットを定義します。すべてのリソースクラスには、少なくともこれらのアノテーションの 1 つが必要です。

パスの設定

@Path アノテーションは、リソースの URI を指定します。アノテーションは javax.ws.rs.Path インターフェースによって定義され、リソースクラスまたはリソースメソッドのいずれかにアノテーションを付けるために使用できます。文字列の値を唯一のパラメーターとして取ります。文字列値は、実装されたリソースの場所を指定する URI テンプレートです。

URI テンプレートは、リソースの相対的な場所を指定します。例46.2「URI テンプレートの構文」 で示されているように、テンプレートには以下を含めることができます。

  • 処理されていないパスコンポーネント
  • { } で囲まれたパラメーター識別子

    注記

    パラメータ識別子には、デフォルトのパス処理を変更するための正規表現を含めることができます。

例46.2 URI テンプレートの構文

@Path("resourceName/{param1}/../{paramN}")

たとえば、URI テンプレート widgets/{color}/{number}widgets/blue/12 にマップされます。color パラメーターの値は blue に割り当てられます。number パラメーターの値には 12 が割り当てられます。

URI テンプレートが完全な URI にマップされる方法は、@Path アノテーションが付けられたものによって異なります。URI テンプレートは、ルートリソースクラスに置かれると、ツリー内のすべてのリソースのルート URI であり、サービスが公開される URI に直接追加されます。アノテーションがサブリソースに付けられた場合、これはルートリソース URI に対して相対的になります。

HTTP 動詞の指定

JAX-RS は、メソッドに使用される HTTP 動詞を指定するために 5 つのアノテーションを使用します。

  • javax.ws.rs.DELETE は、メソッドが DELETE にマップすることを指定します。
  • javax.ws.rs.GET は、メソッドが GET にマップすることを指定します。
  • javax.ws.rs.POST は、メソッドが POST にマップすることを指定します。
  • javax.ws.rs.PUT は、メソッドが PUT にマップすることを指定します。
  • javax.ws.rs.HEAD は、メソッドが HEAD にマップすることを指定します。

メソッドを HTTP 動詞にマップするときは、マッピングが理にかなっていることを確認する必要があります。たとえば、発注書を送信する目的のメソッドをマップする場合、PUTまたは POSTにマッピングします。GET または DELETE にマッピングすると、予期しない動作が発生します。