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<String, String> 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(), );
Assert.assertEquals(, response.getLength());
System.out.println("Content-Range: " + response.getHeaderString("Content-Range"));