JAX-RS入门

JAX-RS入门

第一节、基础

简介

JAX-RS是一套用java实现REST服务的规范，提供了一些标注将一个资源类，一个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。

目前JAX-RS的实现包括：

Apache CXF，开源的Web服务框架。

Jersey，由Sun提供的JAX-RS的参考实现。

RESTEasy，JBoss的实现。

Restlet，由Jerome Louvel和Dave Pawson开发，是最早的REST框架，先于JAX-RS出现。Apache Wink，一个Apache软件基金会孵化器中的项目，其服务模块实现JAX-RS规范(以上来自：https://www.doczj.com/doc/dd3338296.html,/wiki/JAX-RS)

装备

本文使用的工具有：

Eclipse-jee-helios

Java-1.6.0_26

apache-tomcat-6.0.30

SoapUI-3.6

使用到的外部jar包有(必须的部分，需要加到Web容器中)

neethi-3.0.2.jar

jsr311-api-1.1.1.jar

cxf-bundle-2.6.0.jar

使用到的外部jar包有(可选的部分，当且仅当作为一个独立的application运行时)

jetty-http-7.5.4.v20111024.jar

jetty-io-7.5.4.v20111024.jar

jetty-server-7.5.4.v20111024.jar

jetty-util-7.5.4.v20111024.jar

jetty-continuation-7.5.4.v20111024.jar

wsdl4j-1.6.2.jar

准备

(以下例子来自：Oreilly - RESTful Java with JAX-RS (12-2009) (A TTiCA).pdf)

创建工程

为了后续顺利进行，首先在eclipse上先创建一个Dynamic Web Project，完成以后，一个符

合war结构的工程目录会自动生成，之后可以很简单的导出为war文件，其中需要把以下jar 包放到/WebContent/WEB-INF/lib 里：

neethi-3.0.2.jar

jsr311-api-1.1.1.jar

cxf-bundle-2.6.0.jar

另外，在工程目录下，新建一个lib 文件夹用来存放以下可选的jar包：

jetty-http-7.5.4.v20111024.jar

jetty-io-7.5.4.v20111024.jar

jetty-server-7.5.4.v20111024.jar

jetty-util-7.5.4.v20111024.jar

jetty-continuation-7.5.4.v20111024.jar

wsdl4j-1.6.2.jar

最后一步就是把所有这9个jar都加到工程的build path里去，这样工程就准备好了。

定义服务

这里要实现一个简单的REST服务用于对客户进行管理，包括：

创建客户

查看客户

更新客户

首先给出对应的于这些操作的服务接口：

Java代码

import java.io.InputStream;

import javax.ws.rs.Consumes;

import javax.ws.rs.GET;

import javax.ws.rs.POST;

import javax.ws.rs.PUT;

import javax.ws.rs.Path;

import javax.ws.rs.PathParam;

import javax.ws.rs.Produces;

import javax.ws.rs.core.Response;

import javax.ws.rs.core.StreamingOutput;

@Path("/customers")

public interface CustomerResource {

@POST

@Consumes("application/xml")

public Response createCustomer(InputStream is);

@GET

@Path("{id}")

@Produces("application/xml")

public StreamingOutput getCustomer(@PathParam("id") int id);

@PUT

@Path("{id}")

@Consumes("application/xml")

public void updateCustomer(@PathParam("id") int id, InputStream is) ;

}

令人惊奇的是，这个接口已经包含了所有实现我们既定目标的关键部分：

@Path: 定义服务路径，接口中定义的整个服务的顶级路径为"/customers "，方法对应的服务路径为接口路径加方法定义的Path值，如果未定义，则用接口路径，例如getCustomer()的服务路径为：" /customers/{id} "。所以此REST对外服务路径都是服务的上下文路径/customers/ 子级目录，

@POST，@GET，@PUT：标注方法所支持HTTP请求的类型(参考上面的说明)

@Produces，@Consumes：标注方法支持或返回的请求MIME类型。

由上可以看到，每个方法被调用的条件如下：

createConsumer()：请求HTTP方法为POST；请求MIME类型为application/xml；请求路径为：上下文路径/customers

getCustomer()：请求的HTTP方法为GET；请求的MIME类型为application/xml；请求的路径为：上下文路径/customers/{id}

注：{id}为某个存在(或不存在)customer的编号

updateCustomer()：请求的HTTP方法为PUT；请求的MIME类型为application/xml；请求的路径：上下文路径/customers/{id}

注：{id}为某个存在(或不存在)customer的编号

一个好的实现方法是将REST服务的定义和实现分开，这样代码的结构简洁、清晰，在后期也可以很方便的进行实现的替换和服务定义的修改。

下面就是添加实现部分：

Java代码

public class CustomerResourceService implements CustomerResource{

private Map customerDB = new ConcurrentHashMap();

private AtomicInteger idCounter = new AtomicInteger();

public Response createCustomer(InputStream is) {

Customer customer = readCustomer(is);

customer.setId(idCounter.incrementAndGet());

customerDB.put(customer.getId(), customer);

System.out.println("Created customer " + customer.getId());

return Response.created(URI.create("/customers/" + customer.getId()))

.build();

}

public StreamingOutput getCustomer(int id) {

final Customer customer = customerDB.get(id);

if (customer == null) {

throw new WebApplicationException(Response.Status.NOT_FOUND);

}

return new StreamingOutput() {

public void write(OutputStream outputStream) throws IOException,

WebApplicationException {

outputCustomer(outputStream, customer);

}

};

}

public void updateCustomer(int id, InputStream is) {

Customer update = readCustomer(is);

Customer current = customerDB.get(id);

if (current == null)

throw new WebApplicationException(Response.Status.NOT_FOUND);

current.setFirstName(update.getFirstName());

current.setLastName(update.getLastName());

current.setStreet(update.getStreet());

current.setState(update.getState());

current.setZip(update.getZip());

current.setCountry(update.getCountry());

}

protected void outputCustomer(OutputStream os, Customer cust)

throws IOException {

PrintStream writer = new PrintStream(os);

writer.println("");

writer.println(" " + cust.getFirstName() + "");

writer.println(" " + cust.getLastName() + "");

writer.println(" " + cust.getStreet() + "");

writer.println(" " + cust.getCity() + "");

writer.println(" " + cust.getState() + "");

writer.println(" " + cust.getZip() + "");

writer.println(" " + cust.getCountry() + "");

writer.println("");

}

protected Customer readCustomer(InputStream is) {

try {

DocumentBuilder builder = DocumentBuilderFactory.newInstance()

.newDocumentBuilder();

Document doc = builder.parse(is);

Element root = doc.getDocumentElement();

Customer cust = new Customer();

if (root.getAttribute("id") != null

&& !root.getAttribute("id").trim().equals("")) {

cust.setId(Integer.valueOf(root.getAttribute("id")));

}

NodeList nodes = root.getChildNodes();

for (int i = 0; i < nodes.getLength(); i++) {

Node item = nodes.item(i);

if(!(item instanceof Element)){

continue;

}

Element element = (Element) nodes.item(i);

if (element.getTagName().equals("first-name")) {

cust.setFirstName(element.getTextContent());

} else if (element.getTagName().equals("last-name")) {

cust.setLastName(element.getTextContent());

} else if (element.getTagName().equals("street")) {

cust.setStreet(element.getTextContent());

} else if (element.getTagName().equals("city")) {

cust.setCity(element.getTextContent());

} else if (element.getTagName().equals("state")) {

cust.setState(element.getTextContent());

} else if (element.getTagName().equals("zip")) {

cust.setZip(element.getTextContent());

} else if (element.getTagName().equals("country")) {

cust.setCountry(element.getTextContent());

}

}

return cust;

} catch (Exception e) {

throw new WebApplicationException(e, Response.Status.BAD_REQUEST);

}

}

}

这些方法的实现都很直接，不细说，不过有一点需要特别注意的是：

最好不要在实现中混杂有服务的定义部分，例如@Path标签，@PathParam标签等等，如果想修改定义，最好是在接口中修改；或者如果想覆盖某个接口方法的某个annotation，则所有该接口方法的annotation定义都需要重写，而不能仅修改变化的。

第二节、运行

上一节，已经成功的定义了一个REST服务，并且提供了具体的实现，不过我们还需要把它运行起来。

在上一节的装备部分，列举了必须的jar(在tomcat中运行)和可选的jar(作为一个独立的应用程序运行)。这一节将分别介绍如何做为一个独立的应用程序运行和如何在tomcat里运行。

Tomcat(或者其他Web容器)中运行

要在tomcat之类的容器里运行，首先需要定义一个Application类：

Java代码

import java.util.HashSet;

import java.util.Set;

import javax.ws.rs.core.Application;

public class CustomerApplication extends Application {

private Set