RESTEasy入门

RESTEasy是JBoss的开源项目之一，是一个RESTful Web Services框架。RESTEasy的开发者Bill Burke同时也是JAX-RS的J2EE标准制定者之一。JAX-RS是一个JCP制订的新标准，用于规范基于HTTP的RESTful Web Services的API。

我们已经有SOAP了，为什么需要Restful WebServices？用Bill自己的话来说："如果是为了构建SOA应用，从技术选型的角度来讲，我相信REST比SOAP更具优势。开发人员会意识到使用传统方式有进行SOA架构有多复杂，更不用提使用这些做出来的接口了。这时他们就会发现Restful Web Services的光明之处。"

说了这么多，我们使用RESTEasy做一个项目玩玩看。首先创造一个maven¹的web项目

mvnarchetype:create-DgroupId=org.bluedash\

-DartifactId=try-resteasy-DarchetypeArtifactId=maven-archetype-webapp

准备工作完成后，我们就可以开始写代码了，假设我们要撰写一个处理客户信息的Web Service，它包含两个功能：一是添加用户信息；二是通过用户Id，获取某个用户的信息，而交互的方式是标准的WebService形式，数据交换格式为XML。假设一条用户包含两个属性：Id和用户名。那么我们设计交换的XML数据如下:

<user>
<id>1</id>
<name>liweinan</name>
</user>

首先要做的就是把上述格式转换成XSD²，网上有在线工具可以帮助我们完成这一工作³，在此不详细展开。使用工具转换后，生成如下xsd文件：

<?xmlversion="1.0"encoding="utf-8"?>
<xsd:schemaattributeFormDefault="unqualified"elementFormDefault="qualified"
version="1.0"xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<xsd:elementname="user"type="userType"/>
<xsd:complexTypename="userType">
<xsd:sequence>
<xsd:elementname="id"type="xsd:int"/>
<xsd:elementname="name"type="xsd:string"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>

有了xsd文件，我们便可以使用JDK自带工具的xjc将xsd转换成为Java的Class。将上述xsd文件存为 user.xsd，并使用如下命令进行转换：

xjcuser.xsd

执行结束后我们会得到一系列的类文件：

Li-Weinans-MacBook-Pro:Desktopliweinan$xjcuser.xsd
parsingaschema...
compilingaschema...
generated/ObjectFactory.java
generated/UserType.java

这样，我们的XML格式的交换数据便转化为面向对像的Java类了，是不是感觉有点像Hibernate的ORM理念？没错，将XML映射成成面向对象的数据类，这个过程叫做XML Binding，即XML绑定。这个过程也有J2EE标准，叫做JAXB⁴。而RESTEasy是全面支持JAXB的。可以说RESTEasy所支持的JAX-RS标准，当与JAXB标准结合在一起使用时，就可以发挥出最大优势，让程序员少写一堆一堆的代码。有关JAXB标准，会在独立的篇章中 详细讨论，在此先不展开。总之我们将生成的Java类放进项目中等候使用。我们可以看一下UserType类的内容：

packageorg.bluedash.resteasy;

importjavax.xml.bind.annotation.XmlAccessType;
importjavax.xml.bind.annotation.XmlAccessorType;
importjavax.xml.bind.annotation.XmlElement;
importjavax.xml.bind.annotation.XmlType;

@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name="userType",propOrder={
"id",
"name"
})
publicclassUserType{

protectedintid;
@XmlElement(required=true)
protectedStringname;

/**
*Getsthevalueoftheidproperty.
*
*/
publicintgetId(){
returnid;
}

/**
*Setsthevalueoftheidproperty.
*
*/
publicvoidsetId(intvalue){
this.id=value;
}

/**
*Getsthevalueofthenameproperty.
*
*@return
*possibleobjectis
*{@linkString}
*
*/
publicStringgetName(){
returnname;
}

/**
*Setsthevalueofthenameproperty.
*
*@paramvalue
*allowedobjectis
*{@linkString}
*
*/
publicvoidsetName(Stringvalue){
this.name=value;
}

}

可以看到，XML格式就是通过一些JAXB的标记被映射成了Java类。我们没写什么代码，已经把数据模型定义清楚了。接下来我们撰写最核心的WebService API。我们的WebService包含两个接口：一个是添加用户接口createUser，另一个是获取用户接口getUser：

packageorg.bluedash.resteasy;

importjava.net.URI;
importjava.util.Map;
importjava.util.concurrent.ConcurrentHashMap;
importjava.util.concurrent.atomic.AtomicInteger;

importjavax.ws.rs.Consumes;
importjavax.ws.rs.GET;
importjavax.ws.rs.POST;
importjavax.ws.rs.Path;
importjavax.ws.rs.PathParam;
importjavax.ws.rs.Produces;
importjavax.ws.rs.WebApplicationException;
importjavax.ws.rs.core.Response;

@Path("/users")
publicclassUserServlet{

privateMap<Integer,UserType>userStore=
newConcurrentHashMap<Integer,UserType>();
privateAtomicIntegeridGenerator=newAtomicInteger();

@POST
@Consumes("application/xml")
publicResponsecreateUser(UserTypeuser){
user.setId(idGenerator.incrementAndGet());
userStore.put(user.getId(),user);
System.out.println(user.getName()+"created:"
+user.getId());
returnResponse.created(URI.create("/users/"
+user.getId())).build();
}

@GET
@Path("{id}")
@Produces("application/xml")
publicUserTypegetUser(@PathParam("id")intid){
UserTypeu=userStore.get(id);
if(u==null){
thrownewWebApplicationException(
Response.Status.NOT_FOUND);
}
returnu;
}

}

用几个简单的JAX-RS标记，便把普通的函数变成了WebService接口。而这些标记将由RESTEasy支持生效。接下来我们将要进行RESTEasy的配置工作。RESTEasy的配置方法有多种多样，可以和Spring等容器集成，也可以独立运行，因为我们用的Servlet的形式使RESTEasy进行工作，这也是最主流的方式，因此在这里使用web容器来加载它，首先定义一个配置类:

packageorg.bluedash.resteasy;

importjava.util.HashSet;
importjava.util.Set;

importjavax.ws.rs.core.Application;

publicclassBluedashResteasyApplicationextendsApplication{
privateSet<Object>singletons=newHashSet<Object>();
privateSet<Class<?>>classes=newHashSet<Class<?>>();

publicBluedashResteasyApplication(){
//classes.add(UserServlet.class);
singletons.add(newUserServlet());
}

@Override
publicSet<Class<?>>getClasses(){
returnclasses;
}

@Override
publicSet<Object>getSingletons(){
returnsingletons;
}
}

这个类扩展JAX-RS的Application接口，用于封装我们的WebService API方法。我们可以看到JAX-RS支持两种封装方法，一种是classes封装，由容器管理WebServices类的实例化和销毁等动作，一个线程一个实例，开发者不需要关心线程安全问题。但这种方法可能比较浪费资源。如果开发者想自己管理线程安全，共线程共用一个WebServices实例，那么就用singletons封装。我们在这里用的singletons封装，这也就解释了为什么我们在 UserServlet中使用了ConcurrentHashMap和AtomicInteger这些保障线程安全的类。接下来就是在web.xml中启动RESTEasy：

<!DOCTYPEweb-appPUBLIC
"-//SunMicrosystems,Inc.//DTDWebApplication2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">

<web-app>
<display-name>ArchetypeCreatedWebApplication</display-name>

<context-param>
<param-name>javax.ws.rs.core.Application</param-name>
<param-value>org.bluedash.resteasy.
BluedashResteasyApplication</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>

没错，就是这么简单，这样，我们的WebService就完成了！还差点什么呢？嗯，还差一个Test Case来使用我们的WebService接口，并验证它的正确性，让我们来写一个TestUserAPI

packageorg.bluedash.resteasy.test.integration.test;

importjava.io.IOException;
importjava.io.OutputStream;
importjava.net.HttpURLConnection;
importjava.net.URL;

importjunit.framework.TestCase;

publicclassTestUserAPIextendsTestCase{
publicstaticfinalStringUSER_API=
"http://127.0.0.1:8080/try-resteasy/users";

publicvoidtestCreateUserAndGetUser()throwsIOException{
URLurl=
newURL(USER_API);
HttpURLConnectionconnection=
(HttpURLConnection)url.openConnection();
connection.setRequestMethod("POST");
connection.setRequestProperty("Content-Type","application/xml");
connection.setDoOutput(true);
connection.setInstanceFollowRedirects(false);
connection.setConnectTimeout(1000);

StringuserXML="<user><name>liweinan</name></user>";
OutputStreamos=connection.getOutputStream();
os.write(userXML.getBytes());
os.flush();

assertEquals(HttpURLConnection.HTTP_CREATED,connection
.getResponseCode());
connection.disconnect();

}
}

一切都已经准备就绪，最后我们要配置一下Maven，让它下载所需的RESTEasy等库，然后配置Maven使用Jetty Web服务器，来把我们的服务和测试跑起来：

<projectxmlns="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>org.bluedash</groupId>
<artifactId>try-resteasy</artifactId>
<packaging>war</packaging>
<version>1.0-SNAPSHOT</version>
<name>try-resteasyMavenWebapp</name>
<url>http://maven.apache.org</url>
<repositories>
<repository>
<id>JBossMavenRepo</id>
<name>JBossMaven2repo</name>
<url>http://repository.jboss.org/maven2</url>
<releases>
<enabled>true</enabled>
</releases>
<snapshots>
<enabled>false</enabled>
</snapshots>
</repository>
</repositories>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.4</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jaxrs</artifactId>
<version>1.2.RC1</version>
</dependency>
<dependency>
<groupId>org.jboss.resteasy</groupId>
<artifactId>resteasy-jaxb-provider</artifactId>
<version>1.2.RC1</version>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>servlet-api</artifactId>
<version>2.4</version>
</dependency>
</dependencies>
<build>
<finalName>try-resteasy</finalName>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<source>1.6</source>
<target>1.6</target>
<encoding>UTF-8</encoding>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-surefire-plugin</artifactId>
<configuration>
<excludes>
<exclude>**/integration/**</exclude>
</excludes>
</configuration>
<executions>
<execution>
<id>integration-tests</id>
<phase>integration-test</phase>
<goals>
<goal>test</goal>
</goals>
<configuration>
<skip>false</skip>
<excludes>
<exclude>none</exclude>
</excludes>
<includes>
<include>**/integration/**</include>
</includes>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.mortbay.jetty</groupId>
<artifactId>maven-jetty-plugin</artifactId>
<version>6.1.15</version>
<configuration>
<scanIntervalSeconds>5</scanIntervalSeconds>
<stopKey>foo</stopKey>
<stopPort>9999</stopPort>
</configuration>
<executions>
<execution>
<id>start-jetty</id>
<phase>pre-integration-test</phase>
<goals>
<goal>run</goal>
</goals>
<configuration>
<scanIntervalSeconds>5</scanIntervalSeconds>
<daemon>true</daemon>
</configuration>
</execution>
<execution>
<id>stop-jetty</id>
<phase>post-integration-test</phase>
<goals>
<goal>stop</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

有关Maven的配置就不详细展开了。配置完成后我们便可以运行单元测试，看看WebServices是否正确运行。执行下述命令

mvnintegration-test

执行结果如下：

-------------------------------------------------------
TESTS
-------------------------------------------------------
Runningorg.bluedash.resteasy.test.integration.test.TestUserAPI
liweinancreated:1
Testsrun:1,Failures:0,Errors:0,Skipped:0,Timeelapsed:0.372sec

Results:

Testsrun:1,Failures:0,Errors:0,Skipped:0

可以看到，我们的测试按预期执行成功了。这篇文章中，我简单向大家介绍了RESTEasy的初步使用方法，希望对大家在架构SOA应用时，有所帮助。JAX-RS标准做为J2EE家庭中相对较新的一员，其应用前景是十分广阔的。