使用 JSR311(JAX-RS) 规范快速的构建 REST 应用

Tony Denghttp://friendfeed.com/tonydeng

http://twitter.com/wolfdenghttp://delicious.com/wolf.denghttp://wolfchina.blogbus.com

分享内容• JSR311(JAX-RS) 规范介绍• 常用的 JAX-RS API 介绍• JAX-RS 框架介绍• ROA （面向资源架构）• 如何使用 JAX-RS 框架快速的构建 REST 应用• 代码演示

JSR311 （ JAX-RS ）项目介绍• JSR311 正式称呼 JAX-RS:Java API for RESTful

Web Services• JSR311 是 Sun 在 2007 年 2 月发布的一个基

于 annotation 的 API• JSR311 项目地址 https://jsr311.dev.java.net/• 版本：– jsr311-1.0 （稳定版）已经通过了 JCP 的投票同

意– jsr311-1.1 （草稿版）

JAX-RS 的特性• 提供 annotation 的 API 规范• 提出 WADL （ Web Application Description Language ）规范来

描述 REST 应用– https://wadl.dev.java.net

• JSR-311 提供一组注释，相关类和接口都可以用来将 Java 对象作为 Web 资源展示。该规范假定 HTTP 是底层网络协议。

• 它使用注释提供 URI 和相应资源类之间的清晰映射，以及 HTTP 方法与 Java 对象方法之间的映射。

• API 支持广泛的 HTTP 实体内容类型，包括 HTML 、 XML 、 JSON 、 GIF 、 JPG 等。

• 它还将提供所需的插件功能，以允许使用标准方法通过应用程序添加其他类型。

常用的 JAX-RS API 介绍• @Context

– Resource的上下文内容，比如URI，HttpRequest• @Provider

– 扩展自己的MediaType支持• @path

– 定义Resource的URI• @GET

– http get method• @POST

– http post method• @PUT

– http put method• @DELETE

– http delete method• @Produces

– 定义Resource返回的MediaType• @Consumes

– 定义Resource接受的MediaType• @PathParam

– 定义URI中的变量• @FormParam

– 定义form表单中的变量

JAX-RS 框架介绍

实现 JAX-RS 规范的框架• Restlet

– 应该是最早的 REST 框架，在 JAX-RS 之前就已经有了。– http://www.restlet.org/

• Jersey– Sun 提供的实现参考– https://jersey.dev.java.net/

• RESTEasy– Jboss 的项目– http://www.jboss.org/resteasy/

• CXF– Apache 的一级项目– 由 Xfire 项目和 Celtix 项目 ( 一个开源的 ESB 项目 ) 合并后演变过来– http://cxf.apache.org

Restlet 介绍• 项目地址

– http://www.restlet.org– http://www.noelios.com/

• Restlet可以说是最早的REST框架 ,JAX-RS规范出来之前 ,它就已经存在了。• Restlet是在Servlet的之上发展的这套框架

– http://www.restlet.org/about/introduction• Restlet并不是完全按照 JAX-RS规范来实现• Restlet有自己的一套API• 稳定版本1.1.5,jax-rs 1.0的实现• 最新版本2.0-m4,jax-rs 1.0的实现• 特性：

– http://www.restlet.org/about/features– Native REST support– Available editions– Complete Web Server– Available Connectors– Available Representations– Flexible configuration– Security– Scalability– Upcoming features

Jersey 介绍• 项目地址：

– https://jersey.dev.java.net• Jersey 是 Sun 提供的实现参考。由 JAX-RS 项目的成员来实现。• 从某种意义上说，最符合 JAX-RS 规范• Jersey 项目名称的来由 : 由于 Jersey 项目的主管非常喜欢自行车运动，而且当时正是环

法自行车赛期间，所以起了这个名称。同时也透露出对 Jersey 这个项目的期望。• 稳定版本为 1.0.3 ， jax-rs 1.0 的实现• 最新版本 1.1.2-ea ， jax-rs 1.1 的实现• 特性：

– 提供 Client,Service/Grizzly,WADL&JSON– Test Framework– Spring integration– Guice integration– MIME multipart– Client & Apache HTTP Client– Atom & Apache Abdera Simple HTTP server– Oautch support

RESTEasy 介绍• 项目地址：

– http://www.jboss.org/resteasy/• RESTEasy是有 JBOSS提供的实现。• 顾名思义，这个项目的初衷就是如何更好的让使用者很方便容易的创建 REST应用• 最新稳定版本为1.1.GA,jax-rs 1.0 的实现• 特性：

– Fully certified JAX-RS implementation – Portable to any app-server/Tomcat that runs on JDK 5 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. – EJB, Seam, Guice, Spring, and Spring MVC integration

CXF 介绍• 项目地址 :

– http://cxf.apache.org– Apache 的一级项目

• 由 Xfire 项目和 Celtix 项目 ( 一个开源的 ESB 项目 ) 合并后演变过来• 更加偏向 SOA• 稳定版本： 2.2.3 ， jax-rs 1.0 的实现。• 最新版本： 2.3-SNAPSHOT ， jax-rs 1.0 的实现• 支持标准：

– JAX-WS, JSR-181, SAAJ, JAX-RS– SOAP 1.1, 1.2, WS-I BasicProfile, WS-Security, WS-Addressing, WS-RM,

WS-Policy– WSDL 1.1– MTOM

ROA 面向资源的架构

ROA （面向资源架构）• 世间万物皆为资源• REST 对信息的核心抽象就是资源• 资源并不是具体的存储对象，它是对事物概

念上的一个抽象• Resource 是有层次的• Resource 的定义是一门大学问• 面向资源的建模– DDD(Domain-Driven Design) ，面向对象建模， ER

建模

如何规划 Resource URI

• 使用 URI Template 来描述 Resource URI 的定义– http://bitworking.org/projects/URI-Templates/spe

c/draft-gregorio-uritemplate-03.html

URI 对比• 家族话题– /familyBBS?method=GET&json={“familyId”:19

3 ，” bbsId”:412}– /family/193/topic/412

• 家族投票• /familyVote?

method=GET&json={“familyId”:193,”bbsId”:412}• /family/193/topic/412/vote

例子：社区家族 URI 规划• 家族

– /familys– /familys/@self/{uid}/{page},{pageSize}– /familys/@friends/{uid}/{page},{pageSize}

• 家族分类– /familys/type

• 家族标签– /familys/tags– /familys/tags/@hot/{num}

• 家族重名– /familys/names/@userd/{fname}

• 单个家族信息– /family/{fid}

• 家族图标– /family/{fid}/icon

• 家族设置– /family/{fid}/setting

• 家族成员– /family/{fid}/members– /family/{fid}/members/@manager

• 家族转让– /family/{fid}/transfer

例子：社区家族 URI 规划• 家族话题

– /family/{fid}/topics– /family/{fid}/topics/{page},{pageSize}– /family/{fid}/topics/@elite /{page},{pageSize}– /family/{fid}/topics/@vote /{page},{pageSize}

• 家族话题– /family/{fid}/topic/{tid}– /family/{fid}/topic/{tid}/vote– /family/{fid}/topic/{tid}/vote/members– /family/{fid}/topic/{tid}/ {page},{pageSize}– /family/{fid}/topic/{tid}/reply– /family/{fid}/topic/{tid}/reply/{rid}

如何使用 JAX-RS 框架快速的构建 REST 应用

选用框架• Build Tools

– Maven 2.2.0• Jersey

– jsr311 1.0– jersey-server 1.0.3– jersey-json 1.0.3– jersey-spring 1.0.3

• JAXB– jaxb-api 2.1– Sun jaxb-impl 2.1.6

• Spring– spring 2.5.6

代码演示

谢谢