Jersey 2.X 注解 （二）

一、资源注解

1、@Path

@PATH 是一个URI的相对路径，比如@Path("helloworld")，内容是否以"/"开头都没有区别，同样是否以"/"结尾也没有什么区别；

甚至可以嵌入变量到路径中，比如：

@Path("helloworld/{username}")

那么变量在运行时就会被匹配到的 URI 的那部分代替 ，如请求：http://example.com/helloworld/wzy，那么就可以使用@PathParam接收该变量，如：

@Path("/helloworld")
public class HelloRestController {

	@GET
	@Path("{username}")
	public String getUser(@PathParam("username") String name) {
		return "get user by name: " + name;
	}
}

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

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

这个正则表达式匹配由大小写字符、横杠和数字组成的字符串，如果正则校验不通过，则返回404。

 

2、HTTP方法

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

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

 

3、@Consumes 和 @Produces (请求和返回的MIME类型)

两者都可以作用在类和方法上，同时可以定义多个类型。比如：

@Produces({"text/html",MediaType.TEXT_XML})
@Consumes("text/plain")

@Produces({"application/xml; qs=0.9", "application/json"})

二、参数注解

1、@*Param

主要有：@QueryParam,@PathParam, @MatrixParam, @HeaderParam,@CookieParam, @FormParam

（1）@QueryParam: 从请求 URL 的查询组件中提取查询参数

（2）@PathParam：从请求URL的的路径中获取参数

（3）@MatrixParam：从请求URL的路径中获取特殊资源

（4）@HeaderParam：从header中获取参数

（5）@CookieParam：从cookie中获取参数

（6）@FormParam：从form表单中获取参数，类型必须为 application/x-www-form-urlencoded

        @FormParam 可以获取form表单中的数据，也可以通过MultivaluedMap获取：

	@POST
	@Path("/add/user")
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	@Produces(MediaType.TEXT_HTML)
	public String testForm(MultivaluedMap<String,String>  request) {
		return request.toString();
	}

    

如果参数名称重复，则可以通过list获取，比如 http://localhost/rest/user/math;id=3;id=10;id=19

	@GET
	@Path("/user/math/")
	public Object getUsers(@MatrixParam("id") List ids) {
		return ids.size();
	}

例子：get请求：http://locahost/rest/user/math/6;num=10;score=90?sex=0

获取10条数学成绩大于90的6年级男生

则：num和score都可以通过@MatrixParam获取，6年级学生通过@PathParam获取，性别通过@QueryParam获取

	@GET
	@Path("/user/math/{level}")
	public String getUsers(@MatrixParam("num") int num, @QueryParam("sex") int sex, @MatrixParam("score") int score,
			@PathParam("level") int level) {
		return String.format("获取%d个，数学成绩大于%d的%d年级%s", num, score, level, sex == 0 ? "男生" : "女生");
	}

AX-RS不支持@MatrixParam捕获位于中间的参数，而是为我们提供了访问矩阵参数的另一种方法，即PathSegment。

请求：http://localhost/rest/user;num=10/math;score=90/6?sex=0

	@GET
	@Path("/{nums:user}/{scores:math}/{level}")
	public String martixTest(@PathParam("nums") PathSegment nums, @PathParam("scores") PathSegment scores,
			@PathParam("level") Integer level) {
		MultivaluedMap<String, String> nums_map = nums.getMatrixParameters();
		MultivaluedMap<String, String> scores_map = scores.getMatrixParameters();
		System.out.println(nums_map);
		System.out.println(nums.getPath());
		System.out.println(scores_map);
		System.out.println(scores.getPath());
		return "matrix test";
	}

可以参考：https://www.logicbig.com/tutorials/java-ee-tutorial/jax-rs/jaxrs-matrix-param.html

 

2、@DefaultValue

默认值，如果参数不存在，则使用@DefaultValue定义的默认值

 

3、@Context 和 @BeanParam注入

（1）@Context

将Container中的context注入到POJO中，用于获得一个Java类型关联请求或响应的上下文。

可以参考：https://blog.csdn.net/qq_31156277/article/details/86687934 讲的很详细

比如：UriInfo、Request、HttpHeaders等，在servlet容器中还能获取servlet相关的对象：HttpServletRequest等

	@GET
	@Path("/get/{level}")
	@Produces(MediaType.TEXT_HTML)
	public String get(@Context UriInfo info) {
		MultivaluedMap<String, String> map = info.getQueryParameters();
		MultivaluedMap<String, String> pathParams = info.getPathParameters();
		System.out.println(pathParams);
		return "hello jersey restful";
	}

（2）@BeanParam

@BeanParam允许上述的参数注入到bean，

可以包含所有的注入参数(@PathParam, @QueryParam,@MatrixParam, @HeaderParam , @CookieParam, @FormParam )

	@POST
	@Path("/add/user/{id}")
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	@Produces(MediaType.TEXT_HTML)
	public String testForm(@BeanParam User request, @BeanParam Student student, @FormParam("name") String name) {
		return String.format("user:%s, student:%s, name:%s", request.toString(), student.toString(), name);
	}

class User {
	@PathParam("id")
	private int id;

	@FormParam("name")
	private String name;

	@MatrixParam("age")
	@DefaultValue("20")
	private int age;

	//get、set

	@Override
	public String toString() {
		return "User [id=" + id + ", name=" + name + ", age=" + age + "]";
	}
}

class Student {
	@FormParam("name")
	private String name;

	//get、set

	@Override
	public String toString() {
		return "Student [name=" + name + "]";
	}
}

一个方法可以注入多个bean，每个bean可以拥有相同的请求参数。比如User和Student都注入了name参数。

 

4、@Encoded

JAX-RS方法参数默认解码从请求中获得的值，@Encoded帮助我们保持值的编码，也就是禁止解码。@Encoded可以应用于类级、方法级和参数级。

	@POST
	@Path("/add/user/{id}")
	@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
	@Produces(MediaType.TEXT_HTML)
	public String testForm(@BeanParam User request, @BeanParam Student student, @FormParam("name") @Encoded String name,
			@QueryParam("test") @Encoded String test) {
		System.out.println(test);
		return String.format("user:%s, student:%s, name:%s", request.toString(), student.toString(), name);
	}

如果请求：http://localhost/rest/add/user/123?test=wzy%40123%E4%B8%AD 

则因为test有@Encoded参数级修饰，则输出仍然是wzy%40123%E4%B8%AD ，否则为wzy@123中

 

三、子资源

@Path如果用在没有@GET、@Post等方法上，则该方法是子资源定位器。比如在UserResource中对某一类特殊的群体做一些特殊的请求，则可以把该特殊群体抽象出来组成新的子资源单独管理。

创建主资源：

@Path("/user")
public class UserResource {

	@Path("child")
	public ChildResource getChild() {
		return new ChildResource();
	}

	@GET
	@Path("{userid}")
	@Produces({ "text/html", MediaType.TEXT_XML })
	@Consumes("text/plain")
	public String getUser(@PathParam("userid") String id) {
		return "get user by id " + id;
	}

}

抽象子资源，比如vip用户：

public class ChildResource {

	@GET
	public String get(@QueryParam("name") String name) {
		return name;
	}
	
	@GET
	@Path("level")
	public String getUser(@QueryParam("name") String name) {
		return name;
	}
}

当请求：

      A. http://localhost/rest/user/1，则请求的是UserResource中的getUser方法； 

      B. http://localhost/rest/user/child?name=wzy，则请求的是ChildResource中的get方法；

      C. http://localhost/rest/user/child/level?name=wzy，则请求的是ChildResource中的getUser方法；

 

如果子资源需要单例模式，则子资源添加@Singleton注释，主资源使用Class或者资源模型Resource:

//子资源
@Singleton
public class ChildResource {
	//....
}


//主资源改为
	@Path("child")
	public Resource getChild() {
		return Resource.from(ChildResource.class);
	}

//或者
	@Path("child")
	public Class<ChildResource> getChild() {
		return  ChildResource.class;
	}

 

四、生命周期

Scope	注解	类路径	说明
Request	@RequestScoped (or none)	org.glassfish.jersey.process.internal.RequestScoped	默认，为每个请求创建 一个实例
Per-lookup	@PerLookup	org.glassfish.hk2.api.PerLookup	待补充
Singleton	@Singleton	javax.inject.Singleton	单例模式，可以在类上 使用@Singleton注解或 者使用Application注册

 

五、