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 にマッピングすると、予期しない動作が発生します。