JAX-RS入门 一 :基础
2013-12-16 21:54
387 查看
简介
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规范
(以上来自:http://zh.wikipedia.org/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) (ATTiCA).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代码
![](http://liugang594.iteye.com/images/icon_star.png)
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代码
![](http://liugang594.iteye.com/images/icon_star.png)
public class CustomerResourceService implements CustomerResource{
private Map<Integer, Customer> customerDB = new ConcurrentHashMap<Integer, Customer>();
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("<customer id=\"" + cust.getId() + "\">");
writer.println(" <first-name>" + cust.getFirstName() + "</first-name>");
writer.println(" <last-name>" + cust.getLastName() + "</last-name>");
writer.println(" <street>" + cust.getStreet() + "</street>");
writer.println(" <city>" + cust.getCity() + "</city>");
writer.println(" <state>" + cust.getState() + "</state>");
writer.println(" <zip>" + cust.getZip() + "</zip>");
writer.println(" <country>" + cust.getCountry() + "</country>");
writer.println("</customer>");
}
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定义都需要重写,而不能仅修改变化的。
相关文章推荐