JAX-RS RESTで使用するアノテーション

※間違って消しちゃったので日付が変わって復旧

クラスに付与するアノテーション

• @Path
  • リクエストで受け付けるURIを指定する。コンテキストパスからの続き。
  • 例）「http://FQDN/ContextPath/hoge/foo/」の場合、「@Path("hoge")」と設定する。
• @Encoded
  • HTTPの仕様にしたがい、URI template, matrix, query, form の各パラメータはエンコードされる。
  • デフォルトで、JAX-RSはJavaの型に変換するときに、これらの値をデコードする。
  • 生のエンコードされた値を扱いたい場合にこのアノテーションを使用する。
  • このアノテーションを付与することにより、デフォルトのデコードをオフすることができる。
  • クラス、メソッド、メソッド引数に使用できる。
  • ★Apache、AJP、Tomcatへの設定が必要な場合がある！！
• @Provider
  • 下記のインターフェースの実装クラスに付与することによりJAX-RSランタイムに認識される
    • javax.ws.rs.ext.MessageBodyReader
    • javax.ws.rs.ext.MessageBodyWriter
    • javax.ws.rs.ext.ContextResolver
    • javax.ws.rs.ext.ExceptionMapper
  • また、javax.ws.rs.ext.Providersを使用すると@Provider付与クラスを全て取得することができる
    • @Contextアノテーションを使用すると実装クラスをインジェクションしてくれる

■例

// フィールド変数
@Context
protected Providers _providers;

フィールド変数に付与するアノテーション

• @Context
  • 下記のインターフェースの実装クラスをインジェクションしてくれる
    • javax.ws.rs.core.Application
    • javax.ws.rs.core.UriInfo
    • javax.ws.rs.core.Request
    • javax.ws.rs.core.HttpHeaders
    • javax.ws.rs.core.SecurityContext
    • javax.ws.rs.ext.Providers

メソッドに付与するアノテーション

• @Path
  • 使用方法はクラスに付与する場合と同様。ただし、クラスに付与したパスの続きから記述する。
  • 例）「http://FQDN/ContextPath/hoge/foo/」の場合、「@Path("foo")」と設定する。
• @GET、@POST、@PUT、@DELETE、@HEAD
  • リクエストのHTTPメソッドに対応する。
• @HttpMethod
  • HTTPメソッドを直接指定する。GET, POST, PUT, DELETE, HEAD等を指定する。
  • 例）「@GET」と「@HttpMethod("GET")」は同じ意味。
• @Consumes
  • クライアントから送信されたMIMEメディアタイプを指定する。
  • メディアタイプの種類は「http://jackson.codehaus.org/javadoc/jax-rs/1.0/javax/ws/rs/core/MediaType.html」を参照。
  • 例）@Consumes("application/json")、@Consumes({"application/json", "application/xml"})
• @Produces
  • "text/plain"など、リソースが生成してクライアントに返すことのできるMIMEメディアタイプを指定する。
• @Provider
  • MessageBodyReaderやMessageBodyWriterなど、JAX-RSランタイムに関連するものすべてに使用する。

メソッド引数に付与するアノテーション

• @PathParam
  • URIテンプレートパラメータから値を抽出する。URIテンプレートパラメータとは@Pathで指定したURI中の中括弧「{}」で囲まれた部分である。
  • 例）クラスやメソッドに「@Path("/hoge/{num}")」とある場合、「method(@QueryParam("num") int num)」で実際のURIの「{num}」にある値が引数numに渡される。
• @MatrixParam
  • URIのマトリックスパラメータから値を抽出する。@PathParamと使用方法は同じ。
  • マトリックスパラメータはURLのパスの中にセミコロン(;)で区切って入れられるパラメータの事。
  • 例）「/hoge/foo;num=1/hoo」の場合、マトリックスパラメータは「num=1」。
• @QueryParam
  • URIのクエリパラメータから値を抽出する。@PathParamと使用方法は同じ。
  • クエリパラメータはURLのパスの最後にはてな(?)から始まってアンド(&)で区切って入れられるパラメータの事。
  • URIの例）「/hoge/foo?num=1&size=2」の場合、クエリパラメータは「num=1」と「size=2」。
  • メソッドの例）method(@QueryParam("num") String num, @QueryParam("size") String size)
  • ★RESTリソースクラスをインターフェースにする場合、実装クラスにアノテーションを付与する必要はない！！
• @FormParam
  • ポストされた（POSTメソッドでリクエストを受けた）フォームデータから値を抽出する。@PathParamと使用方法は同じ。
• @HeaderParam
  • HTTPリクエストヘッダから値を抽出する。@PathParamと使用方法は同じ。
• @CookieParam
  • クライアントによって設定されたHTTP Cookieから値を抽出する。@PathParamと使用方法は同じ。
• @Context
  • JAX-RS APIによって提供される各種ヘルパーおよび情報オブジェクトをインジェクトする。@PathParamと使用方法は同じ。
  • 以下のオブジェクトに対応する。
    • javax.ws.rs.core.HttpHeaders
    • javax.ws.rs.core.UriInfo
    • javax.ws.rs.core.Request
    • javax.ws.rs.core.SecurityContext
    • javax.servlet.HttpServletRequest
    • javax.servlet.HttpServletResponse
    • javax.servlet.ServletConfig
    • javax.servlet.ServletContext
• @DefaultValue
  • @PathParam等を使用してバインドされるリクエスト・メタデータのデフォルト値を定義する。
  • 例）method(@DefaultValue("2") @QueryParam("num") int num)