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 the message
}
注意上述方法返回void，表示没有内容，此时给客户端返回204（No Content）
2. 参数注解（@*Param)
参数注解用于从请求中提取参数，例如上面的@PathParam用于提取路径中的参数。
2.1 @QueryParam
@QueryParam注解用于提取查询参数：
@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) {
...
}如果请求参数无法被正确地转化为相应的类型，返回404. 参数类型可以自定义：
public class ColorParam extends Color {
public ColorParam(String s) {
super(getRGB(s));
}
private static int getRGB(String s) {
if (s.charAt(0) == '#') {
try {
Color c = Color.decode("0x" + s.substring(1));
return c.getRGB();
} catch (NumberFormatException e) {
throw new WebApplicationException(400);
}
} else {
try {
Field f = Color.class.getField(s);
return ((Color)f.get(null)).getRGB();
} catch (Exception e) {
throw new WebApplicationException(400);
}
}
}
}对这个类的约束就是要有一个接收字符串的构造函数。如果没有@DefaultValue注解，并且请求中未包含该参数，则方法的参数为各类型的“空值”。
2.2 @MatrixParam
从url片段中提取参数，即url中冒号后面的参数。
2.3 @HeaderParam
从请求的头部提取Header。
2.4 @CookieParam
提取cookie。
2.5 @FormParam
用于提取请求中媒体类型为”application/x-www-form-urlencoded” 的参数，根据相应的表单类型提取其中的参数。
@POST
@Consumes("application/x-www-form-urlencoded")
public void post(@FormParam("name") String name) {
// Store the message
}
2.6 @BeanParam
该注解用于从请求的各部分中提取参数，并注入到对应的Bean中，例如我们有如下定义的Bean：
public class MyBeanParam {
@PathParam("p")
private String pathParam;
@MatrixParam("m")
@Encoded
@DefaultValue("default")
private String matrixParam;
@HeaderParam("header")
private String headerParam;
private String queryParam;
public MyBeanParam(@QueryParam("q") String queryParam) {
this.queryParam = queryParam;
}
public String getPathParam() {
return pathParam;
}
...
}这个Bean的各个属性都是使用前面的参数注解注解的，然后我们可以在resource class类的方法中使用这个类：
@POST
public void post(@BeanParam MyBeanParam beanParam, String entity) {
final String pathParam = beanParam.getPathParam(); // contains injected path parameter "p"
...
}当接到请求时，RS实现将从查询参数、头部、Cookie等各处提取参数，并注入到beanParam的各个属性中。
可以组合使用多种参数注解：
@POST
public void post(@BeanParam MyBeanParam beanParam, @BeanParam AnotherBean anotherBean, @PathParam("p") pathParam,
String entity) {
// beanParam.getPathParam() == pathParam
...
}3. 子资源（Sub-resources)
sub-resources的概念类似于Spring MVC框架中Controller的二级映射，及类级别上有一个@RequestMapping，方法上也有一个二级的@RequestMapping。 @Path注解可以用在类上，表示根资源（root resource），也可以用在类的方法上，这里的方法就叫sub-resource method，对应的资源叫sub-resource。
@Singleton
@Path("/printers")
public class PrintersResource {
@GET
@Produces({"application/json", "application/xml"})
public WebResourceList getMyResources() { ... }
@GET @Path("/list")
@Produces({"application/json", "application/xml"})
public WebResourceList getListOfPrinters() { ... }
@GET @Path("/jMakiTable")
@Produces("application/json")
public PrinterTableModel getTable() { ... }
@GET @Path("/jMakiTree")
@Produces("application/json")
public TreeModel getTree() { ... }
@GET @Path("/ids/{printerid}")
@Produces({"application/json", "application/xml"})
public Printer getPrinter(@PathParam("printerid") String printerId) { ... }
@PUT @Path("/ids/{printerid}")
@Consumes({"application/json", "application/xml"})
public void putPrinter(@PathParam("printerid") String printerId, Printer printer) { ... }
@DELETE @Path("/ids/{printerid}")
public void deletePrinter(@PathParam("printerid") String printerId) { ... }
}此例中，如果url为printers，则对应到getMyResources方法，其他二级url分别对应各方法。
@Path的另一种使用场景是用来表示资源嵌套，此时@Path不与@GET之类的HTTP方法注解一起使用，例如：
@Path("/item")
public class ItemResource {
@Context UriInfo uriInfo;
@Path("content")
public ItemContentResource getItemContentResource() {
return new ItemContentResource();
}
@GET
@Produces("application/xml")
public Item get() { ... }
}
}
public class ItemContentResource {
@GET
public Response get() { ... }
@PUT
@Path("{version}")
public void put(@PathParam("version") int version,
@Context HttpHeaders headers,
byte[] in) {
...
}
}
这里的@Path(“content”)没有指定方法注解，因此如果URL为/item/content，此时会继续往上递归，找到ItemContentResource这个资源类，然后针对该类使用URL匹配规则，所以/item/content将映射ItemContentResource的get方法，’/item/content/1.0’将映射到相应的put方法。
这里的getItemContentResource()方法因此也叫子资源定位器（sub-resource locator）
单例资源
正常情况下，资源的scope都是针对每个请求的，也就是说每个请求都会创建不同的资源实例，如果想要每个请求都返回一样的资源，此时需要使用单例注解@Singleton：
@Path("/item")
public class ItemResource {
@Path("content")
public Class<ItemContentSingletonResource> getItemContentResource() {
return ItemContentSingletonResource.class;
}
}
@Singleton
public class ItemContentSingletonResource {
// this class is managed in the singleton life cycle
}
4. Root Resource Classes的生命周期
root resource默认的生命周期是请求范围的，也就是器生命周期在一个请求内有效。另外Jersey支持两种不同生命周期：
| Scope | 注解 | 类全称 | 说明 |
|---|---|---|---|
| Request | @RequestScoped或者空 | org.glassfish.jersey.process.internal.RequestScoped | 默认的生命周期 |
| Per-lookup | @PerLookup | org.glassfish.hk2.api.PerLookup | |
| Singleton | @Singleton | javax.inject.Singleton | 一个JAX-RS应用只有一个实例，可以在类上使用@Singleton注解或者使用Application注册 |
5. 注入规则（Rules of Injection)
正常情况下，可以将请求的各种值注入到参数注解注解的对象，例如属性，方法参数，构造函数等。但是有一些特别的注入规则，会根据注入资源的生命周期有所不同，例如有些参数无法注入单例资源：
@Path("resource")
@Singleton
public static class MySingletonResource {
@QueryParam("query")
String param; // WRONG: initialization of application will fail as you cannot
// inject request specific parameters into a singleton resource.
@GET
public String get() {
return "query param: " + param;
}
}事实上，所以跟某个特定请求相关的参数，都不能被注入到单例资源中，这些规则的验证会在应用启动的时候进行。
一些特殊的对象可以被注入到单例的构造函数或者属性中，此时RS运行时会注入对应的代理类，要使用这些特殊的注入，需要使用@Context注解：
@Path("resource")
@Singleton
public static class MySingletonResource {
@Context
Request request; // this is ok: the proxy of Request will be injected into this singleton
public MySingletonResource(@Context SecurityContext securityContext) {
// this is ok too: the proxy of SecurityContext will be injected
}
@GET
public String get() {
return "query param: " + param;
}
}总结一下注入类型，有：
- Class fields: 注入类的域中
- 构造函数：注入的值将用于调用构造函数
- Resource Method：资源的各方法中注入
- sub resource locator：不带方法注解的@Path
- setter方法：只能使用@Context注解
下面是一个综合的例子：
@Path("resource")
public static class SummaryOfInjectionsResource {
@QueryParam("query")
String param; // injection into a class field
@GET
public String get(@QueryParam("query") String methodQueryParam) {
// injection into a resource method parameter
return "query param: " + param;
}
@Path("sub-resource-locator")
public Class<SubResource> subResourceLocator(@QueryParam("query") String subResourceQueryParam) {
// injection into a sub resource locator parameter
return SubResource.class;
}
public SummaryOfInjectionsResource(@QueryParam("query") String constructorQueryParam) {
// injection into a constructor parameter
}
@Context
public void setRequest(Request request) {
// injection into a setter method
System.out.println(request != null);
}
}
public static class SubResource {
@GET
public String get() {
return "sub resource";
}
}6. @Context的使用
Context注解一般用于获取request或者response相关的上下文，例如UriInfo。对于那些Java类型可以使用@Context注解，请看参考JAX-RS规范第5章。
7. 编程式的资源模型
资源可以通过类或者实例构建，但是也可以从编程式的资源模型构建。所有使用resource class创建的资源都可以通过编程式的资源构建api来完成。通过代码编程式创建资源的方法，请参考这里。
参考
https://jersey.java.net/documentation/latest/jaxrs-resources.html