JAX-RS基本概念理解

JAX-RS,全称为Java API for RESTful Web Services.的核心概念是resource，即面向资源。

JAX-RS的JavaDoc可以在这里找到。
JAX-RS的标准可以在这里找到。

1. Root Resource Classes

满足下列2个条件的POJO类被称为Root Resource Class：

• 使用@Path注解
• 至少有一个方法使用@Path或者资源方法注解（如@GET，@DELETE）

下面的HelloworldResource就是这样一样例子：

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

@Path("helloworld") // 条件1
public class HelloWorldResource {
   
    public static final String CLICHED_MESSAGE = "Hello World!";

    @GET // 条件2
    @Produces("text/plain")
    public String getHello() {
        return CLICHED_MESSAGE;
    }
}

1.1. @Path

@Path注解的值是一个相对的URI路径。@Path的有没有/开头是一样的，同理，结尾有没有包含/也是一样的。上面例子中的/helloworld是最简单的一个例子，但是JAX-RS允许我们在路径中嵌入各种变量。

路径模板在路径中嵌入了以{}包含的变量，这个变量在运行时（资源被请求时）替换成实际的值。例如：

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

参数的实际值在资源方法中使用@PathParam提取:

@Path("/users/{username}")
public class UserResource{
   
    @GET
    @Produces("text/xml")
    public String getUser(@PathParam("username") String username){
        ...
    }
}

我们还可以对模板参数的格式做约束，例如我们只允许大小写字符以及数字，则可以使用下面的正则表达式来限制模板参数：

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

如果请求路径不符合要求，将会返回404.

1.2 @GET, @PUT, @POST, @DELETE, … (HTTP Methods)

@GET, @PUT, @POST, @DELETE, @HEAD这些注解称为resource method designator,与HTTP规范中定义的方法一致。这些方法决定资源的行为。

1.3 @Produce

@Produce注解指定返回给客户端的MIME媒体类型。可以用于注解类或者注解方法。

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

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

如果类中的方法没有指定，则默认使用类级别的@Produce值。@Produce注解可以指定多个值，同时可以指定quality factor：

@GET
@Produces({
  "application/xml; qs=0.9", "application/json"})
public String doGetAsXmlOrJson() {
    ...
}

@Consumes

该注解用于指定可以接受的客户端请求的MIME媒体类型：

@POST
@Consumes("text/plain")
public void postClichedMessage(String message) {
    // Store