JAX-RS 简介

JAX-RS——Java API for RESTful Web Services，是为 Java 程序员提供的一套固定的接口（Java API），用于开发表述性状态转移（REST）架构风格的 WEB 服务应用，避免了依赖第三方框架。同时，JAX-RS 使用 POJO 编程模型和基于标注（标签）的配置，并集成了 JAXB，从而可以有效缩短 REST 应用的开发周期。REST 作为一种轻量级的 Web 服务架构被原来越多的开发者所使用，JAX-RS 的发布则规范了 REST 应用开发的接口。

常见的 JAX-RS 实现方法有：

• Jersey——伴随 JSR311的发布，SUN 公司发布的 JSR311的参考实现；

• CXF——XFire 与 Celtix 的合并；

• RESTEasy——JBoss 的 JAX-RS 项目。

其中，Jersey 是由 SUN 公司开发的产品级质量的 JSR-311的实现，Jersey 实现了 JSR-311中对标注的支持，使得开发人员使用 Java 开发 RESTful 的 Web 服务更加容易。在 SUN 的支持下，目前 Jersey 的易用性较之其他两种方法更高，应用也更为广泛。SuperMap iServer 参考 Jersey 进行资源实现。

简单示例

构建根资源 HelloWorldResource，HelloWorldResource 是一个很简单的 Web 资源，其 URI 路径为/helloworld，支持 GET 方法和文本表述格式"text/plain"。资源 URI 路径、HTTP 请求方法和表述格式构成了 JSR311的三个主要元素。把资源部署为相应的 Web 服务后，打开 http://localhost:8090/helloworld，即可访问已发布的资源。

package com.sun.ws.rest.samples.helloworld.resources;

import javax.ws.rs.GET;

import javax.ws.rs.Produces;

import javax.ws.rs.Path;

//此 Java 类可以通过 URI"/helloworld"来定位，如 http://localhost:8090/helloworld

@Path("/helloworld")

public class HelloWorldResource {

   //使用 HTTP 请求方法 GET

   @GET

   // Java 方法将返回此处的媒体类型所对应的值

   //返回值类型为"text/plain"

   @Produces("text/plain")

   public String getClichedMessage() {

       //返回字符串

       return "Hello World";

   }

}

主要标注介绍

JAX-RS 提供了一系列的标注（annotation），将资源类及其对应的方法，封装为 Web 资源，主要标注包括：

• @Path，标注资源类或方法的相对路径；

• @GET、@PUT、@POST、@DELETE，标注方法使用的 HTTP 请求方法的类型；

• @Produce，标注返回的数据格式（MIME 类型），即方法的返回值类型；

• @Consumes，标注可接受请求的数据格式（MIME 类型），即资源所能解析的参数类型；

• @PathParam、@QueryParam、@HeaderParam、@CookieParam、@MatrixParam、@FormParam，分别标注方法的参数来自 HTTP 请求的位置，如：@PathParam 来自 URL 路径、@QueryParam 来自 URL 的查询参数、@HeaderParam 来自 HTTP 请求的请求头、@CookieParam 来自 HTTP 请求的 Cookie。

其中，类级别的@Path、@Produces 注记适用于每个方法，除非该方法自己有@Path、@Produces。

参数的传递方法

资源的参数包括两种，URI 中传递的参数和请求体中的参数。其中，URI 中传递的参数通过@PathParam 来标注，请求体中传递的参数通过@FormParam 来标注。

1. URI 中参数通过@PathParam 来标注，其定义方法如下所示，此处 userName 为定义的 URI 参数名。

  1 @Path("/users/{username}")

  2 public class UserResource {

  3

  4     @GET

  5     @Produces("text/xml")

  6     public String getUser(@PathParam("username") String userName) {

  7         ...

  8     }

  9 }

2. 请求体中传递的参数通过@FormParam 来标注，以 POST 请求为例，其定义方法如下所示，此处 name 即为定义的请求体参数名。

  1 @POST

  2 @Consumes("application/x-www-form-urlencoded")

  3 public void post(@FormParam("name") String name) {

  4     //请求信息

  5     }