JERSEY中文翻译（第三章、JAX-RS Application, Resources and Sub-Resources）

JAX-RS Application Resource and Sub-Resource

本章要介绍的是JAX-RS的核心概念——Resouce、Sub-Resource

JAX-RS的2.0的java在线文档链接是：http://jax-rs-spec.java.net/nonav/2.0/apidocs/index.html

JAX-RS的2.0的规范草案文档链接是：http://jcp.org/en/jsr/summary?id=339

3.1 Root Resource Classes

Root Resource Classes是一个至少包含@PATH注解或者方法带有@GET, @PUT, @POST, @DELETE注解的POJOS。这一节就是展示如何使用Java对象内的注解创建一个Jersey的Restful服务器。

下面这段代码就是一个带有JAX-RS注解的简单事例，可以从这里下载，https://maven.java.net/content/repositories/releases/org/glassfish/jersey/examples/helloworld/2.2/

package org.glassfish.jersey.examples.helloworld;

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

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

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

让我们分析一下上面这段程序的注释。

3.1.1 @PATH

@PATH是这事URI的相对路径，在上面的例子中，设置的是本地的URI的/helloworld。这事一个非常简单的关于@PATH的例子，更牛逼的是你可以嵌入变量到URIs里面

URI的路径模版有URIS和嵌入URI语法的变量组成。变量将会被匹配到的URI的那部分多代替。例如下面的@Path注解

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

按照这种类型的例子，一个用户会方便的填写他的名字，那么Jersey服务器也会按照这个Path规则匹配到这个请求。例如：http://example.com/users/Galileo

@Path("/users/{username}")
public class UserResource {

    @GET
    @Produces("text/xml")
    public String getUser(@PathParam("username") String userName) {
        ...
    }
}

它规定匹配正则表达式式要精确到大小写的，如果填写的话会覆盖默认的表达式"[^/]+?"，例如

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

这个正则表达式匹配由大小写字符、横杠和数字组成的字符串，如果不匹配的花，那么会返回404错误页面。

一个@Path的内容是否以"/"开头都没有区别，同样是否以"/"结尾也没有什么区别

3.1.2 @GET, @PUT, @POST, @DELETE

@GET, @PUT, @POST, @DELETE 是JAX-RS定义的注解，它非常类似与HTTP的方法名。在上面的例子中，这些注解是通过HTTP的GET方法实现的。资源的相应就是HTTP的相应。

下面这个例子是存储服务的一个片段，是使用PUT方法处理创建或者修改存储容器

事例 3.3 PUT

@PUT
public Response putContainer() {
    System.out.println("PUT CONTAINER " + container);

    URI uri = uriInfo.getAbsolutePath();
    Container c = new Container(container, uri.toString());

    Response r;
    if (!MemoryStore.MS.hasContainer(c)) {
        r = Response.created(uri).build();
    } else {
        r = Response.noContent().build();
    }

    MemoryStore.MS.createContainer(c);
    return r;
}

如果没有明确的定义的话，JAX-RS运行的时候默认支持HEAD和OPTIONS方法。

3.1.3 @Produces

@Produces是定义返回值的媒体类型的。在下面这个例子里面，将会返回一个"text/plain"类型的相应。@Produces既可以应用在类的水平上，也可以作用与方法的水平。这里是一个例子：

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

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

这个doGetAsPlainText方法默认使用类水平的@Produces注解内容，也就是text/plain。而doGetAsHtml方法使用方法水平上的@Produces，也就是text/html。也就是说方法水平层面的@Products会覆盖类层面的@Produces。

@Produces可以定义多个返回类型，例如：

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

无论application/xml或者application/json那个匹配上了，都会出发doGetAsXmlOrJson，如果两个都匹配了，那么会选择首先匹配的那个

3.2 Parameter Annotations(@Param)

资源函数的参数可以通过带有注解参数的注解来获取请求的信息。前面的一个例子就是在匹配了@Path之后，通过@PathParam获取URL请求参数的例子。

@QueryParam是获取URL的参数的，例如：

@Path("smooth")
@GET
public Response smooth(
    @DefaultValue("2") @QueryParam("step") int step,
    @DefaultValue("true") @QueryParam("min-m") boolean hasMin,
    @DefaultValue("true") @QueryParam("max-m") boolean hasMax,
    @DefaultValue("true") @QueryParam("last-m") boolean hasLast,
    @DefaultValue("blue") @QueryParam("min-color") ColorParam minColor,
    @DefaultValue("green") @QueryParam("max-color") ColorParam maxColor,
    @DefaultValue("red") @QueryParam("last-color") ColorParam lastColor) {
    ...
}

上面的代码比较好理解，如果step的参数存在的话，那么附值给它，否则默认是2。如果step的内容不是int类型的，那么会返回404错误。