转载：使用JAX-RS创建RESTful WebServices

原文：http://blog.csdn.net/huxiweng/article/details/7349795

本章介绍REST架构、RESTful web service和JAX-RS（Java API for RESTful WebService，JSR 311）。
    JAX-RS的参考实现Jersey实现了对JSR311中定义的注解的支持，使得使用Java编程语言开发RESTful webservice变得简单。
    如果是使用galssFish服务器，可以使用Updatetool安装Jersey例子和文档。使用Update Tool的教程见第62页的“Java EE6教程组件”。Jersey例子和文档位于Update Tool的AvailableAdd-ons中。


什么是RESTful WebServices
    RESTful webservice是创建来能在web更好的运行的web service。REST是一种架构类型，指定了如统一的接口等应用于webservice的约束。REST提供了如性能、可扩展性和可变性等特性，使得service能够更好的在web上工作。在REST框架中，数据和功能被认为是资源，是通过URI来访问的，通常是web链接。资源是通过使用一组简单的、定义良好的操作来生效。REST的架构方式限定了客户/服务器架构，是设计来使用无状态的通信协议的，通常是HTTP。在REST框架类型中，客户端和服务器使用标准的接口和协议交换资源的representation。
   下面的原则使得RESTful的应用程序简单、轻量并快捷：
   通过URI确定资源：一个RESTful的webservice会公开一组资源，这组资源确定了和客户端互动的目标。资源是通过URI来确定的，URI为service和资源提供了全球的地址空间。更多的信息见第239页的“@Path注解和URI路径模版”。
   统一的接口：资源是通过固定的操作PUT，GET，POST和DELETE来创建、读取、修改和删除的。PUT会创建一个新的资源，DELETE会删除一个资源。GET会获取资源的当前状态。POST将资源的状态转变成新的值。更多信息见底241页的“对HTTP资源的响应”。
   自描述的消息：资源和它们的表现是解耦的，因此可以以不同的格式来访问，如HTML，XML，纯文本，PDF，JPEG，JSON等。关于资源的元数据是有效的并且用来完成控制缓存、检测传输错误、商讨合适的表现格式、执行身份验证和访问控制等。更多信息见第241页的“对HTTP资源的响应”和第243页的“使用实体提供者来映射HTTPresponse和request的实体段”。
   使用超链接的无状态的互动：和资源的互动都是无状态的，也就是说，request消息是自包含的。无状态的互动是基于显示状态转换的概念的。如URI重写、cookies和隐藏的表单字段等技术是为了交换状态而存在的。状态可以被嵌套在response消息中来指向互动的将来有效的状态。更多信息见“使用实体提供者来映射HTTPresponse和request的实体段”和JAX-RS Overview文档中的“BuildingURIs”。

创建RESTful的Web根资源类
    根资源类（Root resourceclasses）是由@Path注解标记的POJO或者至少有一个方法有@Path注解或请求方法指示符注解（@GET，@PUT，@POST或@DELETE）的POJO。
    资源方法（resourcemethod）是资源类中含有请求方法指示符注解的方法。
   本节中将会解释怎样使用JAX-RS来注解java类来创建RESTful的web service。
使用JAX-RS来开发RESTful webservice
   JAX-RS是一个Java编程语言接口，被设计用来简化使用REST架构的应用程序的开发。
    JAX-RSAPI使用Java编程语言的注解来简化RESTful webservice的开发。开发人员使用JAX-RS的注解修饰Java编程语言的类文件来定义资源和能够应用在资源上的行为。JAX-RS的注解是运行时的注解，因此运行时的映射会为资源生成辅助类和其他的辅助文件。包含JAX-RS资源类的JavaEE应用程序中资源是被配置好的，辅助类和辅助文件是生成的，资源通过被发布到JavaEE服务器上来公开给客户端。
   下表列出了JAX-RS定义的一些Java注解以及怎样使用它们的简要的描述。更进一步的JAX-RS的API见 http://download.oracle.com/javaee/6/api 。

注解	描述
@Path	@Path注解的值是一个相对的URI路径，这个路径指定了该Java类的位置，例如/helloworld。在这个URI中可以包含变量，例如可以获取用户的姓名然后作为参数传入URI中：/helloworld/{username}。
@GET	@GET注解是请求方法指示符，这个指示符注解的Java方法会处理HTTPGET请求。资源的行为由资源回应的HTTP方法决定。
@POST	@POST注解是请求方法指示符，这个指示符注解的HTTPPOST请求。资源的行为由资源回应的@PUT	@PUT注解是请求方法指示符，这个指示符注解的HTTPPUT请求。资源的行为由资源回应的@DELETE	@DELETE注解是请求方法指示符，这个指示符注解的HTTPDELETE请求。资源的行为由资源回应的@HEAD	@HEAD注解是请求方法指示符，这个指示符注解的HTTPHEAD请求。资源的行为由资源回应的@PathParam	@PathParam注解是可以抽取并用在资源类中的一类参数。URIpath参数是从请求的URI中抽取的，而且参数的名称和@Path注解中定义的变量名对应。
@QueryParam	@QueryParam注解是可以抽取并在资源类中使用的一类参数。Query参数是从请求URI的查询参数中抽取的。
@Consumes	@Consumes注解是用来指定资源能够接受的客户发送的MIME媒体类型。
@Produces	@Produces注解用来指定资源能够生成并发送给客户端的MIME媒体类型，例如“text/plain”.
@Provider	@Provider注解用在任何对JAX-RS运行时（如MessageBodyReader和MessageBodyWriter）有意义的事物上。对HTTP请求，MessageBodyReader用来将HTTP请求实体段映射为方法参数。在响应的时候，返回的值使用MessageBodyWriter来映射成HTTP响应实体段。如果应用程序需要提供其他的元数据，如HTTP头或不同的状态代码，方法可以返回一个打包了实体的Response，该Response可以使用Response.ResponseBuilder创建。

JAX-RS应用程序概况
   下面的代码例子是一个非常简单的根资源类，使用了JAX-RS注解：

1. package com.sun.jersey.samples.helloworld.resources;
   
2. import javax.ws.rs.GET;
   
3. import javax.ws.rs.Produces;
   
4. import javax.ws.rs.Path;
   
5. // The Java class will be hosted at the URI path"/helloworld"
   
6. @Path("/helloworld")
   
7. public class HelloWorldResource {
   
8.        // The Javamethod will process HTTP GET requests
   
9.        @GET
   
10.        // The Javamethod will produce content identified by the MIME Media
    
11.        // type"text/plain"
    
12.        @Produces("text/plain")
    
13.        public StringgetClichedMessage() {
    
14.              // Returnsome cliched textual content
    
15.              return"Hello World";
    
16.        }
    
17. }

   随后的几节中我们会详细描述这个例子中使用的注解。
   @Path注解的值是一个相对的URI路径。在上面的例子中，这个java类会放在/helloworld这个路径下。上面的例子中使用的是静态的URI路径，是最简单的例子。在URI中，我们可以包含变量，对于这样的包含变量的URI我们称为URI路径模板。
   @GET注解是一个请求方法指示符。在上面的例子中，被注解的Java方法会处理HTTP GET请求。
   @Produces注解用来指定资源能够生产和发送回客户端的MIME媒体类型。在上面的例子中，Java方法会生成MIME媒体类型“text/plain”。
   @Consumes注解用来指定资源能够消费的客户端发送的MIME媒体类型。我们可以将上面的例子中的代码修改为

1. @POST
   
2. @Consumes("text/plain")
   
3. public void postClichedMessage(String message) {
   
4. // Store the message
   
5. }

@Path注解和URI路径模板
   @Path注解指定了URI资源会响应的路径模板，是指定在资源的类级别或方法级别上。@Path注解的值是一个相对URI路径模板，这个路径是相对于资源发布的服务器的基础URI路径、应用程序的上下文根路径和JAX-RS运行时响应的URL。URI路径模板是包含变量的URI。这些变量在运行时会被取代，这样资源就能够根据被取代的URI来响应请求。变量是用花括号{}表示的，例如下面的例子

1. @Path annotation:
   
2. @Path("/users/{username}")

    在这个例子中，用户会被提示输入自己的名字，然后一个被配置来响应这个URI路径模板的JAX-RSweb service会响应该请求。例如，如果用户输入的名字是galileo，这个webservice会响应下面的URL http://example.com/users/Galileo.
要获取用户的名字，可以在请求方法的参数中使用@PathParam注解，如下面的代码所示：

1. @Path("/users/{username}")
   
2. public class UserResource {
   
3.        @GET
   
4.        @Produces("text/xml")
   
5.        public StringgetUser(@PathParam("username") String userName) {
   
6.        ...
   
7.        }
   
8. }

  缺省的，URI变量必须符合正则表达式“[^/]+?”。开发人员也可以通过在变量名称后指定不同的正则表达式来指定客户化的变量模式。例如，如果用户名字必须是由大写或小写字母组成，可以在变量的定义中指定：

1.        @Path("users/{username:[a-zA-Z][a-zA-Z_0-9]}")

  在这个例子中，username这个变量只能匹配由大写或小写字母开头，后跟0个或多个字母、数字和下划线的用户名。如果用户名不匹配这个模板，那么一个404（NotFound）响应会被发送给客户端。
   @Path的值并不要求必须以/开始。无论是否以/开头或者开头是否有空格，JAX-RS运行时会一样的解析。
   一个URI路径模板可以包含一个或多个变量名，每个变量名都以前花括号{开始，以后花括号}结束。在上面的例子中，变量名是username。在运行时，被配置为响应上面的URI路径模板的资源会处理URI数据，将URI中对应{username}的部分作为username的变量数据。
   例如，如果你想要发布一个资源来响应URI路径模板 http://example.com/myContextRoot/resources/ {name1}/{name2}/，你需要将应用程序发布在一个JavaEE服务器上，该服务器要响应对URI  http://example.com/myContextRoot 的请求，并使用如下的@Path注解来修饰你的资源：

1. @Path annotation:
   
2. @Path("/{name1}/{name2}/")
   
3. public class SomeResource {
   
4. ...
   
5. }