快速了解RESTEasy

2015.03.10 | Comments

什么是 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 解压缩。

官方网站:http://resteasy.jboss.org/

特性

直接抄自官网说明:

  • Fully certified JAX-RS implementation
  • Portable to any app-server/Tomcat that runs on JDK 6 or higher
  • Embeddedable server implementation for junit testing
  • Client framework that leverages JAX-RS annotations so that you can write HTTP clients easily (JAX-RS only defines server bindings)
  • Client “Browser” cache. Supports HTTP 1.1 caching semantics including cache revalidation
  • Server in-memory cache. Local response cache. Automatically handles ETag generation and cache revalidation
  • Rich set of providers for: XML, JSON, YAML, Fastinfoset, Multipart, XOP, Atom, etc.
  • JAXB marshalling into XML, JSON, Jackson, Fastinfoset, and Atom as well as wrappers for maps, arrays, lists, and sets of JAXB Objects.
  • GZIP content-encoding. Automatic GZIP compression/decompression suppport in client and server frameworks
  • Asynchronous HTTP (Comet) abstractions for JBoss Web, Tomcat 6, and Servlet 3.0
  • Asynchronous Job Service.
  • Rich interceptor model.
  • OAuth2 and Distributed SSO with JBoss AS7
  • Digital Signature and encryption support with S/MIME and DOSETA
  • EJB, Seam, Guice, Spring, and Spring MVC integration

安装和配置

如果你在 Servlet3.0 容器中使用 Resteasy,则需要添加如下依赖:

<dependency>
    <groupId>org.jboss.resteasy</groupId>
    <artifactId>resteasy-servlet-initializer</artifactId>
    <version>3.0.9.Final</version>
</dependency>

否则,如果你在 Servlet3.0 之前的容器中使用 Resteasy,则 WEB-INF/web.xml 中需要包括如下内容:

<servlet>
    <servlet-name>Resteasy</servlet-name>
    <servlet-class>
        org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher
    </servlet-class>
    <init-param>
        <param-name>javax.ws.rs.Application</param-name>
        <param-value>com.restfully.shop.services.ShoppingApplication</param-value>
    </init-param>
</servlet>

<servlet-mapping>
    <servlet-name>Resteasy</servlet-name>
    <url-pattern>/*</url-pattern>
</servlet-mapping>

另外,还可以在 <context-param> 节点配置如下参数:

  • resteasy.servlet.mapping.prefix
  • resteasy.scan
  • resteasy.scan.providers
  • resteasy.scan.resources
  • resteasy.providers
  • resteasy.use.builtin.providers
  • resteasy.resources
  • resteasy.jndi.resources
  • javax.ws.rs.Application
  • resteasy.media.type.mappings
  • resteasy.language.mappings
  • resteasy.document.expand.entity.references
  • resteasy.document.secure.processing.feature
  • resteasy.document.secure.disableDTDs
  • resteasy.wider.request.matching
  • resteasy.use.container.form.params

以上参数在需要使用的时候查阅官方文档的说明即可。

在 Servlet3.0 之前,你可以将 RESTEasy 配置为 ServletContextListener:

<listener>
  <listener-class>
     org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap
  </listener-class>
</listener>

同样,在 Servlet3.0 之前,你可以将 RESTEasy 配置为 Servlet Filter:

<filter>
    <filter-name>Resteasy</filter-name>
    <filter-class>
        org.jboss.resteasy.plugins.server.servlet.FilterDispatcher
    </filter-class>
    <init-param>
        <param-name>javax.ws.rs.Application</param-name>
        <param-value>com.restfully.shop.services.ShoppingApplication</param-value>
    </init-param>
</filter>

<filter-mapping>
    <filter-name>Resteasy</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

常见的注解

@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() {...}
}

下面的 GETs 请求会映射到 get() 方法:

GET /resources/stuff
GET /resources/foo/stuff
GET /resources/on/and/on/stuff

表达式的格式是:

"{" variable-name [ ":" regular-expression ] "}"

当正则表达式不存在时,类似于:

"([]*)"

例如, @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) {...}

对于下面的请求,对应的 param 和 many 变量如下:

Request param many
GET /aaabb/some/stuff bb some
GET/aaab/a/lot/of/stuff b a/lot/of

另外,@PathParam 注解也可以将 URL 后面的多个参数映射到内置的 javax.ws.rs.core.PathSegment 对象,该对象定义如下:

public interface PathSegment {

    /**
     * Get the path segment.
     * <p>
     * @return the path segment
     */
    String getPath();
    /**
     * Get a map of the matrix parameters associated with the path segment
     * @return the map of matrix parameters
     */
    MultivaluedMap<String, String> getMatrixParameters();
    
}

使用 PathSegment 作为参数类型:

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

则下面请求会映射到 getBook 方法:

GET http://host.com/library/book;name=EJB 3.0;author=Bill Burke

@QueryParam

对于下面的请求:

GET /books?num=5

可以使用 @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) {
...
}

同 PathParam 注解一样,方法的参数类型可以是基本类型、字符串、或者任何有一个字符串作为构造方法参数的 Java 对象、或者一个有字符串作为参数的静态方法 valueOf 的 Java 对象,例如,MediaType 对象有个 valueOf() 方法:

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

@MatrixParam

对于 URL 中的多参数,也可以使用 @MatrixParam 注解,例如对下面的请求,

GET http://host.com/library/book;name=EJB 3.0;author=Bill Burke

可以使用下面代码来处理:

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

@CookieParam

获取 Cookie 参数:

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

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

同 PathParam 注解一样,方法的参数类型可以是基本类型、字符串、或者任何有一个字符串作为构造方法参数的 Java 对象、或者一个有字符串作为参数的静态方法 valueOf 的 Java 对象。

@FormParam

将表单中的字段映射到方法调用上,例如,对于下面的表单:

<form method="POST" action="/resources/service">
First name: 
<input type="text" name="firstname">
<br>
Last name: 
<input type="text" name="lastname">
</form>

通过 post 方法提交,处理该请求的方法为:

@Path("/")
public class NameRegistry {

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

你也可以添加 application/x-www-form-urlencoded 来反序列化 URL 中的多参数:

@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();
   }
 }

客户端可以提交下面的参数:

name=bill
invoice.street=xxx
shipping.street=yyy

另外,也可以设置 prefix 参数,映射到 map 和 list:

public static class Person {
    @Form(prefix="telephoneNumbers") List<TelephoneNumber> telephoneNumbers;
    @Form(prefix="address") Map<String, Address> addresses;
}

public static class TelephoneNumber {
    @FormParam("countryCode") private String countryCode;
    @FormParam("number") private String number;
}

public static class Address {
    @FormParam("street") private String street;
    @FormParam("houseNumber") private String houseNumber;
}

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

    @POST
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED)
    public void post (@Form Person p) {}
}    

然后,提交下面的参数:

request.addFormHeader("telephoneNumbers[0].countryCode", "31");
request.addFormHeader("telephoneNumbers[0].number", "0612345678");
request.addFormHeader("telephoneNumbers[1].countryCode", "91");
request.addFormHeader("telephoneNumbers[1].number", "9717738723");
request.addFormHeader("address[INVOICE].street", "Main Street");
request.addFormHeader("address[INVOICE].houseNumber", "2");
request.addFormHeader("address[SHIPPING].street", "Square One");
request.addFormHeader("address[SHIPPING].houseNumber", "13");

@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 请求类型。

@Consumes("text/*")
@Path("/library")
public class Library {

    @POST
    public String stringBook(String book) {...}

    @Consumes("text/xml")
    @POST
    public String jaxbBook(Book book) {...}
}

当客户端发送下面请求时,stringBook() 方法会调用:

 POST /library
 content-type: text/plain

 thsi sis anice book

当客户端发送下面请求时,jaxbBook() 方法会调用:

POST /library
content-type: text/xml

<book name="EJB 3.0" author="Bill Burke"/> 

@Produces 用于映射客户端的请求并匹配客户端请求的 Accept header。

例如,对下面的代码:

@Produces("text/*")
@Path("/library")
public class Library {

    @GET
    @Produces("application/json")
    public String getJSON() {...}

    @GET
    public String get() {...}
}    

则,客户端发送下面请求时,getJSON() 会被调用。

GET /library
Accept: application/json

可以修改 web.xml 中的配置,对 Accept 和 Accept-Language 做一些映射。例如:

<web-app>
    <display-name>Archetype Created Web Application</display-name>
    <context-param>
        <param-name>resteasy.media.type.mappings</param-name>
        <param-value>html : text/html, json : application/json, xml : application/xml</param-value>
    </context-param>

   <context-param>
        <param-name>resteasy.language.mappings</param-name>
        <param-value>en : en-US, es : es, fr : fr</param-value>
   </context-param>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

如果你调用 /foo/bar.xml.en 的 GET 请求,则等同于发送下面的请求:

GET /foo/bar
Accept: application/xml
Accept-Language: en-US

另外,你也可以设置参数映射,通过参数指定 content-type。修改 web.xml:

<web-app>
    <display-name>Archetype Created Web Application</display-name>
    <context-param>
        <param-name>resteasy.media.type.param.mapping</param-name>
        <param-value>someName</param-value>
    </context-param>

    <servlet>
        <servlet-name>Resteasy</servlet-name>
        <servlet-class>org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher</servlet-class>
    </servlet>

    <servlet-mapping>
        <servlet-name>Resteasy</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
</web-app>

然后,可以通过调用 http://service.foo.com/resouce?someName=application/xml 来得到一个 application/xml 的返回结果。

@GZIP

配置请求输出内容为 Gzip 压缩,例如:

@Path("/")
public interface MyProxy {

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

JAX-RS Resource Locators and Sub Resources

前面提到当方法上只有 @Path 注解没有 HTTP 方法的注解时,则该方法为资源定位器,该方法可以返回一个子资源,然后由资源来定义映射路径和对应的 HTTP 方法。

例如:

@Path("/")
public class ShoppingStore {

   @Path("/customers/{id}")
   public Customer getCustomer(@PathParam("id") int id) {
      Customer cust = ...; // Find a customer object
      return cust;
   }
}


public class Customer {
    @GET
    public String get() {...}

    @Path("/address")
    public String getAddress() {...}

}

public class CorporateCustomer extends Customer {
   
    @Path("/businessAddress")
    public String getAddress() {...}
}

访问下面的请求时,会调用 ShoppingStore 类的 getCustomer 方法,然后调用 Customer 类的 get() 方法。

GET /customer/123

类似地,下面的请求会返回 Customer 类的 getAddress() 方法的值。

GET /customer/123/address

CORS

在 Application 类中,注册一个单例的提供者类:

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"));

原创文章,转载请注明: 转载自JavaChen Blog,作者:JavaChen
本文链接地址:http://blog.javachen.com/2015/03/10/quick-start-of-resteasy.html
本文基于署名2.5中国大陆许可协议发布,欢迎转载、演绎或用于商业目的,但是必须保留本文署名和文章链接。 如您有任何疑问或者授权方面的协商,请邮件联系我。