JAX-RS学习笔记

WEB资源

@PATH标注的类或者方法作为一个Resource,@PATH指定一个相对路径用来标识资源在WEB站点的位置

根 Resource 类和子 Resource 类

在Class上加了@PATH注解的是根Resource类,只在方法上加了@PATH注解的是子Resource类

Resource 方法或子 Resource 定位器

Resource 定位器上没有任何 @GET、@POST、@PUT、@DELETE 或者自定义的@HttpMethod

Resource 方法参数

@PathParam,@MatrixParam,@QueryParam,@FormParam,@HeaderParam,@CookieParam,@DefaultValue和@Encoded

实体参数

Resource方法只允许存在一个没有注解的参数,这个参数叫做实体参数,用于映射请求体

Resource 方法参数与返回值类型

  1. 合法的参数类型

    • 原生类型
    • 构造函数接收单个字符串参数或者包含接收单个字符串参数的静态List,Set,SortedSet(T 为以上的 2 种类型)
    • 用于映射请求体的实体参数
  2. 合法的返回值类型

    • void:状态码 204 和空响应体
    • Response:Response 的 status 属性指定了状态码,entity 属性映射为响应体
    • GenericEntity:GenericEntity 的 entity 属性映射为响应体,entity 属性为空则状态码为 204,非空则状态码为 200
    • 其它类型:返回的对象实例映射为响应体,实例为空则状态码为 204,非空则状态码为 200

异常处理

Resource方法可以抛出非受控异常 WebApplicationException或者返回包含了适当的错误码集合的 Response 对象

Context标注

该注解将HTTP请求中的对象注入到参数中,总共有12个实例可以注入到参数中.Resource类的实例字段可以被注入如下类型的上下文资源:

  • Request、UriInfo、HttpHeaders、Providers、SecurityContext
  • HttpServletRequest、HttpServletResponse、ServletContext、ServletConfig

CRUD操作

@POST、@GET、@PUT、@DELETE

内容协商与数据绑定

  1. 内容协商机制(Content Negotiation)
  • @Produces用于注解响应体的数据格式(MIME类型)
  • @Consumes用于注解请求体的数据格式(MIME类型)
  • @Accept请求头用于选择响应体的数据格式
  • @Content-Type请求头用于标识请求体的数据格式
  1. 数据绑定
  • 序列化和反序列化由MessageBodyReader和MessageBodyWriter自动完成
  • XML 格式的请求/响应数据与 Java对象的自动绑定依赖于JAXB的实现
  • @Provider注解用来注册自定义的MessageBodyProvider
@Provider
@Produces("application/json")
@Consumes("application/json")
public class GsonProvider implements MessageBodyWriter<Object>,
   MessageBodyReader<Object> {

   private final Gson gson;

   public GsonProvider() {
       gson = new GsonBuilder().excludeFieldsWithoutExposeAnnotation().setDateFormat(
               "yyyy-MM-dd").create();
   }

   public boolean isReadable(Class<?> type, Type genericType, Annotation[] annotations,
           MediaType mediaType) {
       return true;
   }

   public Object readFrom(Class<Object> type, Type genericType,
           Annotation[] annotations, MediaType mediaType,
           MultivaluedMap<String, String> httpHeaders, InputStream entityStream)
           throws IOException, WebApplicationException {
       return gson.fromJson(new InputStreamReader(entityStream, "UTF-8"), type);
   }

   public boolean isWriteable(Class<?> type, Type genericType, Annotation[] annotations,
           MediaType mediaType) {
       return true;
   }

   public long getSize(Object obj, Class<?> type, Type genericType,
           Annotation[] annotations, MediaType mediaType) {
       return -1;
   }

   public void writeTo(Object obj, Class<?> type, Type genericType,
           Annotation[] annotations, MediaType mediaType,
           MultivaluedMap<String, Object> httpHeaders, OutputStream entityStream)
           throws IOException, WebApplicationException {
       entityStream.write(gson.toJson(obj, type).getBytes("UTF-8"));
   }
}