Jersey 2.22.2 官方文档第3章学习笔记

3.2  参数注解 (@*Param)

资源方法参数可以通过使用注解来从request对象中获取信息。

@QueryParam 用来从请求URL中获取查询参数。下面是使用@QueryParam的例子。

如果请求中包含查询参数step，则step对应的值将被获取，然后解析为32位值，并赋给smooth方法中的step参数。如果请求中不包含查询参数，则step的默认值为2,默认值通过@DefaultValue注解指定。如果step的值无法被解析为一个32位整数，那么会返回HTTP 404错误。完整的例子如下。

@Path("learn")
public class JerseyLearn {
	@Path("smooth")
	@GET
	public Response smooth(
	@DefaultValue("2") @QueryParam("step") int step,
	@DefaultValue("true") @QueryParam("max-m") boolean hasMax)
	{
		System.out.println(hasMax);
		return Response.status(200).entity(step).build();
	}
}

//http://localhost:9998/learn/smooth?step=1  response body 返回1，控制台打印true

// http://localhost:9998/learn/smooth?step      返回默认值2, 控制台打印true

上述例子中，方法参数的Java类型可以下面的5种情况之一。

1)  原生类型，如int,boolean等，例子如上所示。

2)  Java 对象，这个对象需要有一个构造器，以String作为参数。

public class POJO {
	private String str;
	public POJO(String str){
		this.str = str;
	}
	@Override
	public String toString() {
		return "POJO [str=" + str + "]";
	}
}

@Path("learn")
public class JerseyLearn {	
	@Path("smooth2")
	@GET
	public Response smooth(
			@DefaultValue("test") @QueryParam("pojo") POJO pojo
			)
	{
		System.out.println(pojo);
		return Response.status(200).build();
	}	
}

//http://localhost:9998/learn/smooth2 发出请求，打印POJO [str=test]

//http://localhost:9998/learn/smooth2?pojo=xyzk 发出请求，打印POJO [str=xyzk]

3) Java 对象，并有一个名为valueOf或fromString的静态方法，这个方法接受一个类型为String的参数。

public class POJO {
	private String str = "POJO";
	@Override
	public String toString() {
		return "POJO [str=" + str + "]";
	}
	
	public  static POJO valueOf(String str){
		return new POJO();
	}
}

@Path("learn")
public class JerseyLearn {	
	@Path("smooth2")
	@GET
	public Response smooth(
			@DefaultValue("test") @QueryParam("pojo") POJO pojo
			)
	{
		System.out.println(pojo);
		return Response.status(200).build();
	}	
}//发出请求http://localhost:9998/learn/smooth2?pojo=xyzk 打印POJO [str=POJO]

4) 创建一个实现javax.ws.rs.ext.ParamConverterProvider接口的类，并返回javax.ws.rs.ext.ParamConverter实例，能够完成String 到 Java对象的转换。随后通过@Provider注解标注该类。

@Provider
public class ParamConvert implements ParamConverterProvider{

	public <T> ParamConverter<T> getConverter(final Class<T> rawType, Type genericType, Annotation[] annotations) {
		if(rawType.getName().equals(POJO.class.getName())){
			return new ParamConverter<T>(){

				public T fromString(String value) {
					POJO pojo = new POJO();
					pojo.setStr(value);
					return rawType.cast(pojo);
				}

				public String toString(T value) {
					if(value == null){
						return null;
					}
					return value.toString();
				}
				
			};
		}
		return null;
	}
}//发送请求http://localhost:9998/learn/smooth2?pojo=xyzk 打印结果 POJO [str=xyzk]

5) 方法参数为List <T>,Set<T> 或SortedSet<T>，而T满足上面的条件2或条件3。有时参数有可能包含多个同名参数，这种情况下情况5）下的方法将获得所有的值。

下面是一组同名查询参数值的获取。

@Path("learn")
public class JerseyLearn {	
	@Path("smooth2")
	@GET
	public Response smooth(@QueryParam("pojoList") List<POJO> pojo)
	{
		for(POJO pj: pojo){
			System.out.println(pj);
		}
		return Response.status(200).build();
	}	
}

public class POJO {
	private String str = "POJO";
	public POJO(String s){
		this.str = s;
	}
	@Override
	public String toString() {
		return "POJO [str=" + str + "]";
	}
	public String getStr() {
		return str;
	}
	public void setStr(String str) {
		this.str = str;
	}
}//发出请求http://localhost:9998/learn/smooth2?pojoList=xyzk&pojoList=aaa&pojoList=bbb 将打印结果 POJO [str=xyzk] POJO [str=aaa] POJO [str=bbb]

如果在方法中没有使用@DefaultValue注解，而且查询参数也并不在request对象之中，那么对于List,set,sortedSet等参数类型，结果将为空集合 ，而对于其它对象类型，方法参数将为null，。而Java中的原生类型(int,boolean)的值将为默认值。

@PathParam 以及@MatrixParam, @HeaderParam, @CookieParam, @FormParam 与@QueryParam 遵循同样的规则。

 @CookieParam 获取Cookie

@FormParam 获取表单参数

@HeaderParam 获取Http请求头参数

下面是@FormParam的演示。

//HTML表单
	<form  action = "http://localhost:9998/learn/form" method="post" enctype="application/x-www-form-urlencoded">
		<input  type="text" name="name" />
		<input type="submit" value="submit" />
	</form>

//处理方法获取表单参数后将打印name的值。
	@Path("form")
	@POST
	@Consumes("application/x-www-form-urlencoded")
	public void post(@FormParam("name") String name){
		System.out.println(name);
	}

若希望获取查询或路径参数的(名，值）对，则可以使用@Context注解，演示如下。

@GET
public String get(@Context UriInfo ui) {
    MultivaluedMap<String, String> queryParams = ui.getQueryParameters();
    MultivaluedMap<String, String> pathParams = ui.getPathParameters();
}

上面的代码会获得查询参数与路径参数中 name,value集合，并存放于map中。

对于Header与Cookie参数可以通过如下方式获取。

@GET
public String get(@Context HttpHeaders hh) {
    MultivaluedMap<String, String> headerParams = hh.getRequestHeaders();
    Map<String, Cookie> pathParams = hh.getCookies();
}

Jersey中，@Context能够用来获取与request 或 response相关的上下文Java类型参数。

//获取表单参数map，由于表单参数是消息实体的一部分，因此可以不使用@Context注解。
	@Path("map")
	@POST
	@Consumes("application/x-www-form-urlencoded")
	public void post(MultivaluedMap<String, String> formParams){
		Set<String> sets = formParams.keySet();
		for(String key : sets){
			System.out.println(formParams.get(key));
		}
	}

//HTML表单
<form  action = "http://localhost:9998/learn/map" method="post" enctype="application/x-www-form-urlencoded">
		<input  type="text" name="name" />
		<input  type="text" name="value" />
		<input type="submit" value="submit" />
</form>

另一种类型的注入 @BeanParam ，通过这个注解可以将上述描述的参数注入到一个bean中。通过@BeanParam 的bean，并包含 *param注解的变量，将会被相应request的值注入到变量中。 下面是代码演示。

public class MyBeanParam {
	@PathParam("p")
	private String pathParam;


	public String getPathParam() {
		return pathParam;
	}

	public void setPathParam(String pathParam) {
		this.pathParam = pathParam;
	}
}

@Path("rs")
public class Resource {
	
	@GET
	@Path("{p}")
	public void test1(@BeanParam MyBeanParam beanParam){
		System.out.println(beanParam.getPathParam());
	}
	
	@GET
	public void test2(@BeanParam MyBeanParam beanParam){
		System.out.println(beanParam.getQueryParam());
	}
}//http://localhost:9998/rs?q=12345   //绑定查询参数到bean成员中，并打印12345

//http://localhost:9998/rs/pathPara // 程序将会绑定路径参数，并打印pathParam</p>

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

通过对3.2节学习，通过参数注解，可以简化获取http请求中的相关参数的工作。

官方文档地址：https://jersey.java.net/documentation/latest/jaxrs-resources.html#d0e2001