使用 Spring 3 来创建 RESTful Web Services

标签: spring restful web | 发表时间:2014-10-17 22:59 | 作者:yjph83
出处:http://www.iteye.com

       转载注明: 说个啥CTO-图书馆

http://lib.cto.shuogesha.net/40.html

 

       通过 REST 风格体系架构,请求和响应都是基于资源表示的传输来构建的。资源是通过全局 ID 来标识的,这些 ID 一般使用的是一个统一资源标识符(URI)。客户端应用使用 HTTP 方法(如,GET、POST、PUT 或 DELETE)来操作一个或多个资源。通常,GET 是用于获取或列出一个或多个资源,POST 用于创建,PUT 用于更新或替换,而 DELETE 则用于删除资源。

 

       例如, GET http://host/context/employees/12345 将获取 ID 为 12345 的员工的 表示。这个响应表示可以是包含详细的员工信息的 XML 或 ATOM,或者是具有更好 UI 的 JSP/HTML 页面。您看到哪种表示方式取决于服务器端实现和您的客户端请求的 MIME 类型。

 

       RESTful Web Service 是一个使用 HTTP 和 REST 原理实现的 Web Service。通常,一个 RESTful Web Service 将定义基本资源 URI、它所支持的表示/响应 MIME,以及它所支持的操作。

本文将介绍如何使用 Spring 创建 Java 实现的服务器端 RESTful Web Services。这个例子将使用浏览器、curl 和 Firefox 插件 RESTClient 作为发出请求的客户端

Spring 3 的 REST 支持

在 Spring 框架支持 REST 之前,人们会使用其他几种实现技术来创建 Java 的 RESTful Web Services,如 Restlet、RestEasy 和 Jersey。Jersey 是其中最值得注意的,它是 JAX-RS(JSR 311)的参考实现。

Spring 是一个得到广泛应用的 Java EE 框架,它在版本 3 以后就增加了 RESTful Web Services 开发的支持。虽然,对 REST 的支持并不是 JAX-RS 的一种实现,但是它具有比标准定义更多的特性。REST 支持被无缝整合到 Spring 的 MVC 层,它可以很容易应用到使用 Spring 构建的应用中。

Spring REST 支持的主要特性包括:

  • 注释,如 @RequestMapping@PathVariable,支持资源标识和 URL 映射
  • ContentNegotiatingViewResolver 支持为不同的 MIME/内容类型使用不同的表示方式
  • 使用相似的编程模型无缝地整合到原始的 MVC 层

创建一个示例 RESTful Web Service

本节中的例子将演示 Spring 3 环境的创建过程,并创建一个可以部署到 Tomcat 中的 “Hello World” 应用。然后我们再完成一个更复杂的应用来了解 Spring 3 REST 支持的重要概念,如多种 MIME 类型表示支持和 JAXB 支持。另外,本文还使用一些代码片断来帮助理解这些概念。

Hello World:使用 Spring 3 REST 支持

要创建这个例子所使用的开发环境,您需要:

  • IDE:Eclipse IDE for JEE (v3.4+)
  • Java SE5 以上
  • Web 容器:Apache Tomcat 6.0(Jetty 或其他容器也可)
  • Spring 3 框架(v3.0.3 是本文编写时的最新版本)
  • 其他程序库:JAXB 2、JSTL、commons-logging

在 Eclipse 中创建一个 Web 应用,然后设置 Tomcat 6 作为它的运行环境。然后,您需要设置 web.xml 文件来激活 Spring WebApplicationContext。这个例子将 Spring bean 配置分成两个文件:rest-servlet.xml 包含与 MVC/REST 有关的配置,rest-context.xml 包含服务级别的配置(如数据源 beans)。清单 1 显示了 web.xml 中的 Spring 配置的部分。

清单 1. 在 web.xml 中激活 Spring WebApplicationContext
<context-param>
<param-name>contextConfigLocation</param-name>
<param-value>
	/WEB-INF/rest-context.xml
</param-value>
</context-param>
	
<!-- This listener will load other application context file in addition to 
            rest-servlet.xml -->
<listener>
<listener-class>
	org.springframework.web.context.ContextLoaderListener
</listener-class>
</listener>
	
<servlet>
<servlet-name>rest</servlet-name>
<servlet-class>
	org.springframework.web.servlet.DispatcherServlet
</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>

<servlet-mapping>
<servlet-name>rest</servlet-name>
<url-pattern>/service/*</url-pattern>
</servlet-mapping>

在 rest-servlet.xml 文件中创建 Spring MVC 的相关配置(Controller、View、View Resolver)。清单 2 显示了其中最重要的部分。

清单 2. 在 rest-servlet.xml 文件中创建 Spring MVC 配置
<context:component-scan base-package=    "dw.spring3.rest.controller" />

<!--To enable @RequestMapping process on type level and method level-->
<bean class=    "org.springframework.web.servlet.mvc.annotation    .DefaultAnnotationHandlerMapping" />
<bean class=    "org.springframework.web.servlet.mvc.annotation    .AnnotationMethodHandlerAdapter" />

<!--Use JAXB OXM marshaller to marshall/unmarshall following class-->
<bean id=    "jaxbMarshaller"
class=    "org.springframework.oxm.jaxb.Jaxb2Marshaller">
<property name=    "classesToBeBound">
	<list>
	    <value>dw.spring3.rest.bean.Employee</value>
	    <value>dw.spring3.rest.bean.EmployeeList</value>
	</list>
</property>
</bean>

<bean id=    "employees" class=
	    "org.springframework.web.servlet.view.xml.MarshallingView">
<constructor-arg ref=    "jaxbMarshaller" />
</bean>

<bean id=    "viewResolver" class=
    "org.springframework.web.servlet.view.BeanNameViewResolver" />
Component-scan 启用对带有 Spring 注释的类进行自动扫描
在实践中,它将检查控制器类中所定义的 @Controller 注释。 DefaultAnnotationHanlderMappingsAnnotationMethodHandlerAdapter 使用 @ReqeustMapping 注释的类或函数的 beans 由 Spring 处理
这个注释将在下一节进行详细介绍。 Jaxb2Mashaller 定义使用 JAXB 2 进行对象 XML 映射(OXM)的编组器(marshaller)和解组器(unmarshaller MashallingView 定义一个使用 Jaxb2Mashaller 的 XML 表示 view BeanNameViewResolver 使用用户指定的 bean 名称定义一个视图解析器
本例将使用名为 “employees” 的 MarshallingView

这样就完成了 Spring 的相关配置。下一步是编写一个控制器来处理用户请求。清单 3 显示的是控制器类。

清单 3. dw.spring3.rest.controller.EmployeeController
@Controller
    public    class EmployeeController {
@RequestMapping(method=RequestMethod.    GET, value="/employee/{id}")
    public ModelAndView getEmployee(@PathVariable String id) {
	Employee e = employeeDS.get(Long.    parseLong(id));
	    return    new ModelAndView(    XML_VIEW_NAME, "object", e);
}
}

RequestMapping 注释是 Spring REST 特性的关键所在。它指定所注释的方法将处理哪个 HTTP 方法( RequestMethod.GET)和哪个 URI( /employee/{id})。注意:

  • 对于 {id} 占位符,使用 @PathVariable 注释可以将 {} 内的值注入到函数的参数。
  • XML_VIEW_NAME 为 employees,这是 rest-servlet.xml 中定义的视图名称。
  • employeeDS 是一个基于内存的数据源,它的实现已经超出本文写作范围。

将 Web 应用发布到您的 Tomcat 上。这时,您可以打开浏览器,然后输入 http://<host>:<port>/<appcontext>/service/employee/1。浏览器就会显示一个 ID 为 1 的员工信息的 XML 视图。

请继续阅读以了解更多关于 Spring REST 支持的特性。

方法

资源操作是通过 HTTP 方法实现的,如 GET、POST、PUT 和 DELETE。您在前面已经了解了如何使用 GET 方法查询员工信息。现在我们将介绍 POST、PUT 和 DELETE。

通过使用 @RequestMapping 注释的功能,处理不同方法的代码是非常相似的。清单 4 显示了 EmployeeController 的代码片断。

清单 4. dw.spring3.rest.controller.EmployeeController
@RequestMapping(method=RequestMethod.    POST, value="/employee")
    public ModelAndView addEmployee(@RequestBody String body) {
	Source source =     new StreamSource(    new StringReader(body));
	Employee e = (Employee) jaxb2Mashaller.unmarshal(source);
	employeeDS.add(e);
	    return    new ModelAndView(    XML_VIEW_NAME, "object", e);
}

@RequestMapping(method=RequestMethod.    PUT, value="/employee/{id}")
    public ModelAndView updateEmployee(@RequestBody String body) {
	Source source =     new StreamSource(    new StringReader(body));
	Employee e = (Employee) jaxb2Mashaller.unmarshal(source);
	employeeDS.update(e);
	    return    new ModelAndView(    XML_VIEW_NAME, "object", e);
}

@RequestMapping(method=RequestMethod.    DELETE, value="/employee/{id}")
    public ModelAndView removeEmployee(@PathVariable String id) {
	employeeDS.remove(Long.    parseLong(id));
	List<Employee> employees = employeeDS.getAll();
	EmployeeList list =     new EmployeeList(employees);
	    return    new ModelAndView(    XML_VIEW_NAME, "employees", list);
}

在上面的代码中:

  • RequestMethod.<Method> 的值确定所注释的函数应该处理哪个 HTTP 方法。
  • 通过 @RequestBody,HTTP 请求的主体内容可以作为一个参数注入。在本例中,主体内容是表示员工信息的 XML 数据。我们使用 JAXB 2 来将 XML 解组为 Java Bean,然后将它存储。一个示例请求主体可以是:
    <employee><id>3</id><name>guest</name></employee>
  • 其他可以注入到函数参数的有用的注释有 @PathVariable@RequestParm 等等。Spring 文档有完整列表的注释

 

资源集合

通常,您还需要操作批量的资源。例如,您可能希望获取所有员工的信息而不只是一个员工的信息。您可以采取类似于之前情况的方法实现;您所需要做的修改就是将 URI 从 /employee 修改成 /employees。员工的复数形式能够正确反映批量的语义。清单 5 显示了这种实现方法。

清单 5. EmployeeController 的 getAllEmployees
@RequestMapping(method=RequestMethod.    GET, value="/employees")
    public ModelAndView getEmployees() {
	List<Employee> employees = employeeDS.getAll();
	EmployeeList list =     new EmployeeList(employees);
	    return    new ModelAndView(    XML_VIEW_NAME, "employees", list);
}

您需要为 Employee 集合声明一个包装类。这个包装类是 JAXB 2 所需要的,因为它无法正确地编组 java.util.List 类。清单 6 显示了 EmployeeList 类。

清单 6. dw.spring3.rest.bean.EmployeeList
@XmlRootElement(name="employees")
    public    class EmployeeList {
	    private    int count;
	    private List<Employee> employees;

	    public EmployeeList() {}
	
	    public EmployeeList(List<Employee> employees) {
		    this.employees = employees;
		    this.count = employees.size();
	}

	    public    int getCount() {
		    return count;
	}
	    public    void setCount(    int count) {
		    this.count = count;
	}
	
	@XmlElement(name="employee")
	    public List<Employee> getEmployees() {
		    return employees;
	}
	    public    void setEmployees(List<Employee> employees) {
		    this.employees = employees;
	}
	
}

内容协商

REST 服务的另一个常用特性是它们能够根据请求产生不同的表示。例如,如果客户端请求所有员工的 HTML/text 表示方式,那么服务器就应该为用户产生一个符合语法规则的 HTML 页面。如果客户端请求的是员工的 application/XML 表示方式,那么服务器就应该产生一个 XML 结果。其他受欢迎的表示方式还有 ATOM 和 PDF。

Spring 3 引入了一个名为 ContentNegotiatingViewResolver 的新视图解析器。它可以根据请求的内容类型(请求头中的 Accept 属性)或 URI 后缀来切换视图解析器。下面的例子使用 ContentNegotiatingViewResolver 来实现多种表示方式的支持。

在 rest-servlet.xml 文件中,用注释去掉原来定义的 viewResolver。而使用 ContentNegotiatingViewResolver 来替代它,如 清单 7 所示。

清单 7. 定义内容协商
<bean class=    "org.springframework.web.servlet.view    .ContentNegotiatingViewResolver">
<property name=    "mediaTypes">
	<map>
	<entry key=    "xml" value=    "application/xml"/>
	<entry key=    "html" value=    "text/html"/>
	</map>
</property>
<property name=    "viewResolvers">
	<list>
	<bean class=    "org.springframework.web.servlet.view    .BeanNameViewResolver"/>
	<bean class=    "org.springframework.web.servlet.view    .UrlBasedViewResolver">
		<property name=    "viewClass" value=
		    "org.springframework.web.servlet.view.JstlView"/>
		<property name=    "prefix" value=    "/WEB-INF/jsp/"/>
		<property name=    "suffix" value=    ".jsp"/>
	</bean>
	</list>
</property>
</bean>

这个定义显示了处理两种请求内容的支持: application/xmltext/html。这段代码也定义了两个视图解析器:其中 BeanNameViewResolver 是负责处理 application/xml 的,而另一个 UrlBasedViewResolver 则负责处理 text/html。

在实践中,当您在浏览器上输入 http://<host>:<port>/<appcontext>/service/employees,那么它就会请求 text/html 形式的所有员工信息。然后 UrlBasedViewResolver 会进行解析,而 Spring 将会选择 /WEB-INF/jsp/employees.jsp 作为返回的视图。当您添加请求头 Accept:application/xml 并再发起请求时,那么 BeanNameViewResolver 就会进行解析。如 清单 5 中的代码,它将使用一个名为 employees 的视图来表示,它就是所定义的 JAXB 2 编组器视图。

getAllEmployees() 的控制器代码不需要修改。employees.jsp 将会使用名为 employees 的模型对象来渲染。清单 8 显示了 employees.jsp 的代码片断。

清单 8. /WEB-INF/jsp 中的 employees.jsp
<table border=    1>
	<thead><tr>
		<th>ID</th>
		<th>Name</th>
		<th>Email</th>
	</tr></thead>
	<c:forEach var=    "employee" items="${employees.employees}">
	<tr>
		<td>${employee.id}</td>
		<td>${employee.name}</td>
		<td>${employee.email}</td>
	</tr>
	</c:forEach>
</table>
 

回页首

与 REST 服务通信的客户端

现目前为止,您已经开发一个简单的支持对员工信息的 CRUD(增删查改)操作的 RESTful Web Service。接下来这一节将介绍如何与这个服务进行通信。您将使用 curl 来测试这个 REST 服务。

您也可以使用名为 RESTClient 的 Firefox 插件来测试 REST 服务。它很容易使用且带有良好的 UI。 参考资料 有关于它的下载信息。

使用 curl

Curl 是一个流行的能以 HTTP 和 HTTPS 协议向服务器发送请求的命令行工具。Curl 是 Linux® 和 Mac® 上的一个内置工具。对于 Windows® 平台,您可以另外下载这个工具(见 参考资料)。

要初始化查询所有员工信息的第一个 curl 命令,您可以输入:

curl –HAccept:application/xml 

http://localhost:8080/rest/service/employees

它的响应将是 XML 格式的,并且包含所有的员工信息,如图 1 所示。

图 1. XML 方式表示的所有员工信息

包含员工姓名、ID 和电子邮件的 XML 输出

您也可以在浏览器上尝试访问相同的 URL。这时,头信息中的 Accept 为 text/html,所以浏览器会显示 employees.jsp 中定义的一个表格。图 2 显示的是这种情况。

图 2. HTML 方式表示的所有员工信息

有一些数据与图 1 相同,但是这些数据是显示在表格中的

要将一个新的员工信息 POST 到服务器上,我们可以使用下面的代码。 清单 4 中的 addEmployee() 代码将会使用请求体并将它解组为 Employee 对象。

curl -X POST -HContent-type:application/xml --data
"<employee><id>3</id><name>guest</name><email>[email protected]</employee>"

http://localhost:8080/rest/service/employee

这样就添加了一个新的员工信息。您可以使用第一个例子来验证员工列表。

PUT 方法类似于 POST。

curl -X PUT -HContent-type:application/xml --data
"<employee><id>3</id><name>guest3</name><email>[email protected]</employee>" 

http://localhost:8080/rest/service/employee/3

上面的代码修改了 ID 为 3 的员工数据。



已有 0 人发表留言,猛击->> 这里<<-参与讨论


ITeye推荐



相关 [spring restful web] 推荐:

使用 Spring 3 来创建 RESTful Web Services

- - Web前端 - ITeye博客
       转载注明: 说个啥CTO-图书馆.        通过 REST 风格体系架构,请求和响应都是基于资源表示的传输来构建的. 资源是通过全局 ID 来标识的,这些 ID 一般使用的是一个统一资源标识符(URI). 客户端应用使用 HTTP 方法(如,GET、POST、PUT 或 DELETE)来操作一个或多个资源.

Spring MVC中发布Restful Web服务

- - 企业架构 - ITeye博客
对于企业应用来说,数据是许多业务的命脉,软件通常是可替换的,但是多年积累的数据是永远不能替换的. 近些年来,以信息为中心的表述性状态转移(Representational State Transfer, REST)已成为替换传统SOAP Web服务的流行方案,为了帮助Spring开发人员,Spring3.0以上的版本中封装了对REST的良好支持.

Restful 和 Jersey介绍(Web Service )

- - CSDN博客架构设计推荐文章
REST 2000 年由 Roy Fielding 在博士论文中提出,他是 HTTP 规范 1.0 和 1.1 版的首席作者之一. REST 中最重要的概念是资源(resources) ,使用全球 ID(通常使用 URI)标识. 客户端应用程序使用 HTTP 方法(GET/ POST/ PUT/ DELETE )操作资源或资源集.

Spring MVC 与 web开发

- - 码蜂笔记
项目组用了 Spring MVC 进行开发,觉得对里面的使用方式不是很满意,就想,如果是我来搭建开发环境,我会怎么做. 下面就是我的想法,只关注于 MVC 的 View 层. 现在基本上都是用 ajax 来调用后台接口,拿到 json格式的数据再展示,有的人直接返回数据,却没有考虑异常的情况,我觉得返回的报文里必须包含表示可能的异常信息的数据和业务响应数据.

使用Spring Security Oauth2完成RESTful服务password认证的过程 - 王安琪

- - 博客园_首页
        摘要:Spring Security与Oauth2整合步骤中详细描述了使用过程,但它对于入门者有些重量级,比如将用户信息、ClientDetails、token存入数据库而非内存. 配置过程比较复杂,经过几天时间试验终于成功,下面我将具体的使用Spring Security Oauth2完成password认证的过程记录下来与大家分享.

使用Spring Boot开发Web项目

- - ImportNew
前面两篇博客中我们简单介绍了spring Boot项目的创建、并且也带小伙伴们来DIY了一个Spring Boot自动配置功能,那么这些东西说到底最终还是要回归到Web上才能体现出它的更大的价值,so,今天我们就来看一下如何使用Spring Boot来开发Web项目. 当然,如果小伙伴对Spring Boot尚不熟悉的话,可以先参考一下这两篇博客:.

[Java][web]利用Spring随时随地获得Request和Session

- - CSDN博客推荐文章
利用Spring随时随地获得Request和Session. 在web.xml中添加  . 1、方法一:通过代码实现. 2、方法二:通过注解实现:. 三、关于RequestContextListener的背景知识:. 基于LocalThread将HTTP request对象绑定到为该请求提供服务的线程上.

Web项目中获取SpringBean——在非Spring组件中获取SpringBean

- - 编程语言 - ITeye博客
转自:http://www.cnblogs.com/Johness/archive/2012/12/25/2833010.html.  最近在做项目的时候我发现一个问题:Spring的IOC容器不能在Web中被引用(或者说不能被任意地引用). 我们在配置文件中让Spring自动装配,但并没有留住ApplicationContext的实例.

理解RESTful架构

- InterMa - 阮一峰的网络日志
越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式,建立在分布式体系上,通过互联网通信,具有高延时(high latency)、高并发等特点. 网站开发,完全可以采用软件开发的模式. 但是传统上,软件和网络是两个不同的领域,很少有交集;软件开发主要针对单机环境,网络则主要研究系统之间的通信.