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解压缩。
RESTEasy项目是JAX-RS的一个实现，集成的一些亮点：
1. 不需要配置文件，只要把JARs文件放到类路径里面，添加@Path注解就可以了。
2. 完全的把RESTEeasy配置作为Seam组件来看待。
3. HTTP请求由Seam来提供，不需要一个额外的Servlet。Resources和providers可以作为Seam components (JavaBean or EJB)，具有全面的Seam injection,lifecycle, interception, 等功能支持。
4. 支持在客户端与服务器端自动实现GZIP解压缩。

名词解释:

JAX-RS: Java API for RESTful Web Services是一个Java编程语言的应用程序接口,支持按照 表象化状态转变 (REST)架构风格创建Web服务Web服务[1]. JAX-RS使用了Java SE 5引入的Java 标注来简化Web服务客户端和服务端的开发和部署。

规范内容

JAX-RS提供了一些标注将一个资源类，一个POJOJava类，封装为Web资源。标注包括：
@Path，标注资源类或方法的相对路径
@GET，@PUT，@POST，@DELETE，标注方法是用的HTTP请求的类型
@Produces，标注返回的MIME媒体类型
@Consumes，标注可接受请求的MIME媒体类型
@PathParam，@QueryParam，@HeaderParam，@CookieParam @MatrixParam，@FormParam,分别标注方法的参数来自于HTTP请求的不同位置，例如@PathParam来自于URL的路径，@QueryParam来自于URL的查询参数，@HeaderParam来自于HTTP请求的头信息，@CookieParam来自于HTTP请求的Cookie。

环境准备

开发工具：Eclipse Mars4.5.2
服务容器：Tomcat 7.0.69
JDK：1.7.0.17
Maven：3.3.3

构建步骤

第一步 构建一个web项目

我们使用maven构建一个web应用，具体步骤默认各位读者都会，实在不会自行百度。
web应用创建完毕之后，根据下文描述的配置进行调整。
WEB-INF/web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://java.sun.com/xml/ns/javaee"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    version="2.5">
    <display-name>rest-easy application</display-name>

        <!-- resteasy扫描开关 Automatically scan WEB-INF/lib jars and WEB-INF/classes directory for both @Provider and JAX-RS resource classes 
    (@Path, @GET, @POST etc..) and register them -->
    <context-param>
        <param-name>resteasy.scan</param-name>
        <param-value>true</param-value>
    </context-param>

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

    <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>

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.mrcsj.study</groupId>
    <artifactId>rest</artifactId>
    <packaging>war</packaging>
    <version>0.0.1-SNAPSHOT</version>
    <name>rest Maven Webapp</name>
    <url>http://maven.apache.org</url>


    <properties>
        <jackson-version>2.2.3</jackson-version>
        <resteasy-version>3.0.4.Final</resteasy-version>
        <httpcomp-version>4.2.5</httpcomp-version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>javax.servlet-api</artifactId>
            <version>3.1.0</version>
        </dependency>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-jaxrs</artifactId>
            <version>${resteasy-version}</version>
            <exclusions>
                <exclusion>
                    <groupId>org.slf4j</groupId>
                    <artifactId>slf4j-simple</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.apache.httpcomponents</groupId>
            <artifactId>httpclient</artifactId>
            <version>${httpcomp-version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.httpcomponents</groupId>
            <artifactId>httpcore</artifactId>
            <version>${httpcomp-version}</version>
        </dependency>
        <dependency>
            <groupId>org.apache.httpcomponents</groupId>
            <artifactId>httpcore-nio</artifactId>
            <version>${httpcomp-version}</version>
        </dependency>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-spring</artifactId>
            <version>${resteasy-version}</version>
            <exclusions>
                <exclusion>
                    <groupId>org.jboss.resteasy</groupId>
                    <artifactId>resteasy-jettison-provider</artifactId>
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-jackson2-provider</artifactId>
            <version>${resteasy-version}</version>
        </dependency>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-jaxb-provider</artifactId>
            <version>${resteasy-version}</version>
        </dependency>
        <dependency>
            <groupId>org.jboss.resteasy</groupId>
            <artifactId>resteasy-servlet-initializer</artifactId>
            <version>${resteasy-version}</version>
        </dependency>
    </dependencies>

    <build>
        <finalName>rest</finalName>
    </build>
</project>

Resource.java

package com.example;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;

@Path("/resource")
public class Resource {

        @GET
        @Path("/list")
        public String list() {
            return "success";
        }

        @GET
        @Path("/say/{msg}")
        public void putTest(@PathParam(value = "msg") String msg) {
            System.out.println("receive success : " + msg);
        }

}

第二步 测试

根据我们上文的Resource.java中的配置来看，我们可以使用如下两个路径进行测试。由于我们配置的都是GET，所以直接使用浏览器打卡键入如下地址，即可测试。
http://IP:PORT/rest/resource/list
http://IP:PORT/rest/resource/say/msg

resteasy配置

配置开关

Resteasy采用 元素来配置,参数如下:

参数名	默认值	描述
resteasy.servlet.mapping.prefix	no default	If the url-pattern for the Resteasy servlet-mapping is not /*
resteasy.scan	FALSE	Automatically scan WEB-INF/lib jars and WEB-INF/classes directory for both @Provider and JAX-RS resource classes (@Path, @GET, @POST etc..) and register them
resteasy.scan.providers	FALSE	Scan for @Provider classes and register them
resteasy.scan.resources	FALSE	Scan for JAX-RS resource classes
resteasy.providers	no default	A comma delimited list of fully qualified @Provider class names you want to register
resteasy.use.builtin.providers	TRUE	Whether or not to register default, built-in @Provider classes. (Only available in 1.0-beta-5 and later)
resteasy.resources	no default	A comma delimited list of fully qualified JAX-RS resource class names you want to register
resteasy.jndi.resources	no default	A comma delimited list of JNDI names which reference objects you want to register as JAX-RS resources
javax.ws.rs.Application	no default	Fully qualified name of Application class to bootstrap in a spec portable way
resteasy.media.type.mappings	no default	Replaces the need for an Accept header by mapping file name extensions (like .xml or .txt) to a media type. Used when the client is unable to use a Accept header to choose a representation (i.e. a browser). See JAX-RS Content Negotiation chapter for more details.
resteasy.language.mappings	no default	Replaces the need for an Accept-Language header by mapping file name extensions (like .en or .fr) to a language. Used when the client is unable to use a Accept-Language header to choose a language (i.e. a browser). See JAX-RS Content Negotiation chapter for more details

resteasy其他集成方式

Spring

<web-app>
   <display-name>rest-server</display-name>
   <listener>
      <listener-
class>org.jboss.resteasy.plugins.server.servlet.ResteasyBootstrap</listener-class>
   </listener>

   <listener>
      <listener-
class>org.jboss.resteasy.plugins.spring.SpringContextLoaderListener</listener-class>
   </listener>

   <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>

扩展知识

我们针对主要的几个标签做一下详细介绍
1. @Path
@Path不仅仅接收简单的路径表达式,也可以使用正则表达式:

@GET
@path("{var:.*}/list")
public String list() {
    return "success";
}

GET http://IP:PORT/rest/resource/list
GET http://IP:PORT/rest/resource/another/list
GET http://IP:PORT/rest/resource/a/b/c/list
以上三种访问方式都可以获取到资源。
正则表达式部分是可选的,当未提供时,则会匹配一个默认的表达式
@Path(“/resources/{var}/list”)会匹配如下路径
GET http://IP:PORT/rest/resource/b/list
GET http://IP:PORT/rest/resource/a/list
而下面的则不会匹配：
GET http://IP:PORT/rest/resource/a/b/c/list
2. @PathParam
@PathParam　参数标注是用来获取映射路径上的变量值供方法使用

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

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

}

GET http://IP:PORT/rest/libraty/book/123 就会调用到getBook方法，id的值会自动映射为123。
@Path中的变量名要和@PathParam中的变量名一致,参数类型可以是任意类型,一个String,一个Java对象,注意如果是Java对象时,这个对象要拥有一个带String类型参数的构造器或者一个返回值为String的静态valueOf方法,例如:
构造器方式

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

ValueOf方式

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

这样做的目的是底层会把请求的参数通过String的方式传递的前端,构造对象的方式由业务层来自己构建。
3. @PathParam高级使用
允许指定一个或多个路径参数在一个URI段中。例如：
a: @Path(“/aaa{param}bbb”)
“/aaa111bbb”则能匹配上，其中param的值为111
b: @Path(“/{name}-{zip}”)
“/bill-02115”会匹配,其中name=bill,zip=02115
c: @Path(“/foo{name}-{zip}bar”)
“/foobill-02115bar”会匹配,其中name=bill,zip=02115
4. 正则表达式的一些例子

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

GET /aaabb/some/stuff bs=bb,many=some
GET /aaab/a/lot/of/stuff bs= b,many=a/lot/of
5. @QueryParam
@QueryParam这个标注是给通过?的方式传参获得参数值的,如:
GET /books?num=5&index=1

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

这里同上面的@PathParam,参数类型可以是任意类型。
6. @HeaderParam
这个标注时用来获得保存在HttpRequest头里面的参数信息的,如:

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

这里同上面的@PathParam,参数类型可以是任意类型。
7. @CookieParam
这个标注是用来获得保存在cookie里面的参数，如：

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

这里同上面的@PathParam,参数类型可以是任意类型。
8. @FormParam
用来获取Form中的参数值,如:
页面代码:

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

后台代码:

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

标注了@FormParam,会把表达里面的值自动映射到方法的参数上去。
如果要取得Form里面的所有属性,可以通过在方法上增加一个MultivaluedMap

满足JAX-RS规范的 Resource Locators和子资源

资源处理类定义的某个方法可以处理某个请求的一部分,剩余部分由子资源处理类来处理,如:

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

当我们发起GET /customer/123这样的请求的时候,程序会先调用 ShoppingStore的getCustomer这个方法,然后接着调用Customer里面的 get方法。当我们发起GET /customer/123/address这样的请求的时候,程序会先调用ShoppingStore的getCustomer这个方法,然后接着调用Customer里面的getAddress方法。

JAX-RS Content Negotiation

1. @Consumes
   我们从页面提交数据到后台的时候,数据的类型可以是text的,xml的,json的,但是我们在请求资源的时候想要请求到同一个资源路径上面去,此时怎么来区分处理呢?使用@Consumes标注,下面的例子将说明:

   @Consumes("text/*")
   @Path("/library")
   public class Library {
   @POST
   public String stringBook(String book) {...}
   @Consumes("text/xml")
   @POST
   public String jaxbBook(Book book) {...}
   

当客户端发起请求的时候,系统会先找到所有匹配路径的方法,然后根据content-type找到具体的处理方法,比如:
POST /library
content-type: text/plain
就会执行上面的stringBook这个方法,因为这个方法上面没有标注@Consumes,程序找了所有的方法没有找到标注 @ Consumes(“text/plain”)这个类型的,所以就执行这个方法了.如果请求的content-type=xml,比如:
POST /library
content-type: text/xml
此时就会执行jaxbBook这个方法。
2. @Produces
当服务器端实行完成相关的逻辑需要返回对象的时候,程序会根据@Produces返回相应的对象类型

@Produces("text/*")
@Path("/library")
public class Library {
@GET
@Produces("application/json")
public String getJSON() {...}
@GET
public String get() {...}

如果客户端发起如下请求
GET /library
那么则会调用到get方法并且返回的格式是json类型的
这些标注能不能写多个呢?答案是可以的,但是系统只认第一个。

Content Marshalling/Providers

这个东西是用来根据消息题格式来组装对象或者根据对象生成相应的消息体的,默认的对应关系如下

Media Types	Java Type
application/+xml, text/+xml, application/+json, application/+fastinfoset, application/atom+*	JaxB annotated classes
application/+xml, text/+xml	org.w3c.dom.Document
/	java.lang.String javax.activation.DataSource java.io.File byte[]
application/x-www-form-urlencoded	javax.ws.rs.core.MultivaluedMap
text/plain	primtives, java.lang.String, or any type that has a String constructor, or static valueOf(String) method for input, toString() for output

1. 生成JavaScript API
RESTEasy能够生成JavaScript API使用AJAX来执行JAX-RS操作,比如:

@Path("orders")
public interface Orders {
 @Path("{id}")
 @GET
 public String getOrder(@PathParam("id") String id){
  return "Hello "+id;
 }
}

以上代码可以在js里面通过var order = Orders.getOrder({id: 23});这种方式来调用,很酷吧,这里应该是跟Google的一项技术类似的Java代码可以通过js方式来调用。
2. 通过JavaApi调用资源
上面介绍了生成jsapi的方式调用,另外如果别的应用需要通过Java的方式调用资源该怎么处理呢,下面的例子将说明:

ClientRequest request = new ClientRequest
    ("http://localhost:8080/rest/services/demoservice/child/22222");
// request.header("custom-header", "value");
// We're posting XML and a JAXB object
// request.body("application/xml", someJaxb);
// we're expecting a String back
ClientResponse<Object> response = request.get(Object.class);
if (response.getStatus() == 200){ // OK!
    Object str = response.getEntity();
    System.out.println(str);
}

把资源当做一个标准servlet接收处理方法。我们可以把一个资源url当做一个接收servlet请求的处理类或者处理方法。
3. jaxb介绍
对@PathParam, @QueryParam, @MatrixParam, @FormParam, and @HeaderParam参数的处理。
@PathParam, @QueryParam, @MatrixParam, @FormParam, and @HeaderParam标注传递的参数类型是String型的,对于这些参数我们的方法可能希望接收的参数是经过转换后的对象类型的参数,比如如下的方法:

public void put(@QueryParam("pojo")POJO q, @PathParam("pojo")POJO pp,@MatrixParam ("pojo")POJO mp,@HeaderParam("pojo")POJO hp) {}；

这里的Put方法需要的是一个Pojo类型的参数,但是@PathParam, @QueryParam, @MatrixParam, @FormParam, and @HeaderParam传递的都是String类型的,怎么是怎么转换为对象的呢?
可以使用StringConverter或者StringParamUnmarshaller
StringConverter

package org.jboss.resteasy.spi;
public interface StringConverter<T>{
   T fromString(String str);
   String toString(T value);
}

实现类如下:

@Provider
public static class POJOConverter implements StringConverter<POJO>{
    public POJO fromString(String str){
        System.out.println("FROM STRNG: " + str);
        POJO pojo = new POJO();
        pojo.setName(str);
        return pojo;
    }
    public String toString(POJO value){
        return value.getName();
    }
}

FromString就是你自己需要实现的如何把接收的String参数转换为Pojo类,toString方法是用来把Pojo对象转换为String。现在已经能够把String参数转换为对象了,我们更进一步的想使用一些自定义的标注来做一些逻辑,比如说日期的格式化,就要使用下面的StringParamUnmarshaller

package org.jboss.resteasy.spi;
public interface StringParameterUnmarshaller<T> {
    void setAnnotations(Annotation[] annotations);
    T fromString(String str);
}

实现类

public class DateFormatter implements StringParameterUnmarshaller<Date> {
    private SimpleDateFormat formatter;
    public void setAnnotations(Annotation[] annotations){
        DateFormat format = FindAnnotation.findAnnotation(annotations, 
DateFormat.class);
        formatter = new SimpleDateFormat(format.value());
    }

    public Date fromString(String str){
        try{
            return formatter.parse(str);
        }catch (ParseException e){
            throw new RuntimeException(e);
        }
    }
}

使用方式:

@Path("/datetest")
public class Service{
    @GET
    @Produces("text/plain")
    @Path("/{date}")
    public String get(@PathParam("date") @DateFormat("MM-dd-yyyy") Date date){
        System.out.println(date);
        Calendar c = Calendar.getInstance();
        c.setTime(date);
        Assert.assertEquals(3, c.get(Calendar.MONTH));
        Assert.assertEquals(23, c.get(Calendar.DAY_OF_MONTH));
        Assert.assertEquals(1977, c.get(Calendar.YEAR));
        return date.toString();
    }
}

在实际使用中,我们有些参数值并不是通过以上方式来传递的,比如说我们要对session进行操作,那么应该怎么办呢,resteasy并没有直接提供使用自定义标注的方法,所以我们可以使用以上的StringParamUnmarshaller来变通的实现。
首先定义自定义标注

@Retention(RetentionPolicy.RUNTIME)
@StringParameterUnmarshallerBinder(SessionOperator.class)
public @interface Session {
    public String value();
}

@StringParameterUnmarshallerBinder(SessionOperator.class)是用来指明这个自定义标注是哪个具体的类来处理, SessionOperator这个类就是Session这个自定义标注的处理类。

public class SessionOperator implements StringParameterUnmarshaller{
    public void setAnnotations(Annotation[] annotations) {
    }
    public Object fromString(String str) {
        return null;
    }
}