RESTEasy详解

RESTEasy 是 JBoss 的一个开源项目，提供各种框架帮助你构建 RESTful Web Services 和 RESTful Java 应用程序。它是 JAX-RS 规范的一个完整实现并通过 JCP 认证。

作为一个 JBOSS 的项目，它当然能和 JBOSS 应用服务器很好地集成在一起。 但是，它也能在任何运行 JDK5 或以上版本的 Servlet 容器中运行。RESTEasy 还提供一个 RESTEasy JAX-RS 客户端调用框架，能够很方便与 EJB、Seam、Guice、Spring 和 Spring MVC 集成使用，支持在客户端与服务器端自动实现 GZIP 解压缩。

常见的注解

@Path and @GET, @POST

@Path("/library")
public class Library {

   @GET
   @Path("/books")
   public String getBooks() {...}

   @GET
   @Path("/book/{isbn}")
   public String getBook(@PathParam("isbn") String id) {
      // search my database and get a string representation and return it
   }

   @PUT
   @Path("/book/{isbn}")
   public void addBook(@PathParam("isbn") String id, @QueryParam("name") String name) {...}

   @DELETE
   @Path("/book/{id}")
   public void removeBook(@PathParam("id") String id {...}

}

类或方法是存在 @Path 注解或者 HTTP 方法的注解
如果方法上没有 HTTP 方法的注解，则称为 JAXRSResourceLocators
@Path 注解支持正则表达式映射

@Path("/resources")
public class MyResource {

   @GET
   @Path("{var:.*}/stuff")
   public String get() {...}
}

例如， @Path(“/resources/{var}/stuff”)` 将会匹配下面请求：
GET /resources/foo/stuff
GET /resources/bar/stuff
而不会匹配：
GET /resources/a/bunch/of/stuff

@PathParam

@PathParam 是一个参数注解，可以将一个 URL 上的参数映射到方法的参数上，它可以映射到方法参数的类型有基本类型、字符串、或者任何有一个字符串作为构造方法参数的 Java 对象、或者一个有字符串作为参数的静态方法 valueOf 的 Java 对象。

@GET
@Path("/book/{isbn}")
public String getBook(@PathParam("isbn") ISBN id) {...}


public class ISBN {
  public ISBN(String str) {...}
}

public class ISBN {
 public static ISBN valueOf(String isbn) {...}
}

@Path 注解中可以使用 @PathParam 注解对应的参数。

@GET
@Path("/aaa{param:b+}/{many:.*}/stuff")
public String getIt(@PathParam("param") String bs, @PathParam("many") String many) {...}

@PathParam 注解也可以将 URL 后面的多个参数映射到内置的 javax.ws.rs.core.PathSegment 对象

@QueryParam

@GET
public String getBooks(@QueryParam("num") int num) {
...
}

@HeaderParam

@HeaderParam 注解用于将 HTTP header 中参数映射到方法的调用上，例如从 http header 中获取 From 变量的值映射到 from 参数上：

@GET
public String getBooks(@HeaderParam("From") String from) {
...
}

@PUT
public void put(@HeaderParam("Content-Type") MediaType contentType, ...)

@MatrixParam

@GET
public String getBook(@MatrixParam("name") String name, @MatrixParam("author") String author) {...}

@CookieParam

@GET
public String getBooks(@CookieParam("sessionid") int id) {
...
}

@GET
publi cString getBooks(@CookieParam("sessionid") javax.ws.rs.core.Cookie id) {...}

@FormParam

@Path("/")
public class NameRegistry {

    @Path("/resources/service")
    @POST
    public void addName(@FormParam("firstname") String first, @FormParam("lastname") String last) {...}
}    

@Path("/")
public class NameRegistry {

   @Path("/resources/service")
   @POST
   @Consumes("application/x-www-form-urlencoded")
   public void addName(@FormParam("firstname") String first, MultivaluedMap form) {...}
}       

@Form

@FormParam 只是将表单字段绑定到方法的参数上，而 @Form 可以将表单绑定到一个对象上。

public static class Person{
   @FormParam("name")
   private String name;

   @Form(prefix = "invoice")
   private Address invoice;

   @Form(prefix = "shipping")
   private Address shipping;
}

public static class Address{

   @FormParam("street")
   private String street;
}

@Path("person")
public static class MyResource{

   @POST
   @Produces(MediaType.TEXT_PLAIN)
   @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
   public String post(@Form Person p){
      return p.toString();
   }
 }

@DefaultValue

用于设置默认值。

@GET
public String getBooks(@QueryParam("num") @DefaultValue("10") int num) {...}

@Encoded 和 @Encoding

对 @*Params 注解的参数进行编解码。

@Context

该注解允许你将以下对象注入到一个实例：

javax.ws.rs.core.HttpHeaders,
javax.ws.rs.core.UriInfo
javax.ws.rs.core.Request
javax.servlet.HttpServletRequest
javax.servlet.HttpServletResponse
javax.servlet.ServletConfig
javax.servlet.ServletContext
javax.ws.rs.core.SecurityContext

@Produces 和 @Consumes

@Consumes 注解定义对应的方法处理的 content-type 请求类型。

@GZIP

@Path("/")
public interface MyProxy {

   @Consumes("application/xml")
   @PUT
   public void put(@GZIP Order order);
}

CORS

CorsFilter filter = new CorsFilter();
filter.getAllowedOrigins().add("http://localhost");

Content-Range Support

@Path("/")
public class Resource {
  @GET
  @Path("file")
  @Produces("text/plain")
  public File getFile()
  {
     return file;
  }
}

Response response = client.target(generateURL("/file")).request()
      .header("Range", "1-4").get();
Assert.assertEquals(response.getStatus(), 206);
Assert.assertEquals(4, response.getLength());
System.out.println("Content-Range: " + response.getHeaderString("Content-Range"));