使用Jersey开发RESTful的webservice服务

REST基础概念：

在REST中的一切都被认为是一种资源。

每个资源由URI标识。

使用统一的接口。处理资源使用POST，GET，PUT，DELETE操作类似创建，读取，更新和删除（CRUD）操作。

无状态。每个请求是一个独立的请求。从客户端到服务器的每个请求都必须包含所有必要的信息，以便于理解。

通信都是通过展现。例如XML，JSON

RESTful Web服务由于其简单替代了基于SOAP的Web服务，并大型服务提供商所接受。这篇文章使用Jersey框架延伸JAX-RS API将展示如何创建一个REST风格的Web服务和客户端。

1，创建一个普通的web服务

在Eclipse中，创建一个新的动态Web项目名为"RESTfulWS"：



导入jar包：

asm-3.1.jar
jersey-client-1.17.1.jar
jersey-core-1.17.1.jar
jersey-server-1.17.1.jar
jersey-servlet-1.17.1.jar
jsr311-api-1.1.1.jar

创建Web服务类：

package com.eviac.blog.restws;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.PathParam;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

/**
*
* @author pavithra
*
*/

// @Path here defines class level path. Identifies the URI path that
// a resource class will serve requests for.
@Path("UserInfoService")
public class UserInfo {

// @GET here defines, this method will method will process HTTP GET
// requests.
@GET
// @Path here defines method level path. Identifies the URI path that a
// resource class method will serve requests for.
@Path("/name/{i}")
// @Produces here defines the media type(s) that the methods
// of a resource class can produce.    也可使用json@Produces(MediaType.APPLICATION_JSON)
@Produces(MediaType.TEXT_XML)
// @PathParam injects the value of URI parameter that defined in @Path
// expression, into the method.
public String userName(@PathParam("i") String i) {

String name = i;
return "<User>" + "<Name>" + name + "</Name>" + "</User>";
}

@GET
@Path("/age/{j}")
@Produces(MediaType.TEXT_XML)
public String userAge(@PathParam("j") int j) {

int age = j;
return "<User>" + "<Age>" + age + "</Age>" + "</User>";
}
}

配置web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" id="WebApp_ID" version="2.5">
<display-name>RESTfulWS</display-name>
<servlet>
<servlet-name>Jersey REST Service</servlet-name>
<servlet-class>com.sun.jersey.spi.container.servlet.ServletContainer</servlet-class>
<init-param>
<param-name>com.sun.jersey.config.property.packages</param-name>
<param-value>com.eviac.blog.restws</param-value>
</init-param>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Jersey REST Service</servlet-name>
<url-pattern>/rest/*</url-pattern>
</servlet-mapping>
</web-app>

点按这个项目 run as ->run on server.

浏览器浏览：http://localhost:8080/RESTfulWS/rest/UserInfoService/name/Pavithra

URL说明：



创建一个调用客户端：

package com.eviac.blog.restclient;

import javax.ws.rs.core.MediaType;

import com.sun.jersey.api.client.Client;
import com.sun.jersey.api.client.ClientResponse;
import com.sun.jersey.api.client.WebResource;
import com.sun.jersey.api.client.config.ClientConfig;
import com.sun.jersey.api.client.config.DefaultClientConfig;

/**
*
* @author pavithra
*
*/
public class UserInfoClient {

public static final String BASE_URI = "http://localhost:8080/RESTfulWS";
public static final String PATH_NAME = "/UserInfoService/name/";
public static final String PATH_AGE = "/UserInfoService/age/";

public static void main(String[] args) {

String name = "Pavithra";
int age = 25;

ClientConfig config = new DefaultClientConfig();
Client client = Client.create(config);
WebResource resource = client.resource(BASE_URI);

WebResource nameResource = resource.path("rest").path(PATH_NAME + name);
System.out.println("Client Response \n"
+ getClientResponse(nameResource));
System.out.println("Response \n" + getResponse(nameResource) + "\n\n");

WebResource ageResource = resource.path("rest").path(PATH_AGE + age);
System.out.println("Client Response \n"
+ getClientResponse(ageResource));
System.out.println("Response \n" + getResponse(ageResource));
}

/**
* Returns client response.
* e.g :
* GET http://localhost:8080/RESTfulWS/rest/UserInfoService/name/Pavithra * returned a response status of 200 OK
*
* @param service
* @return
*/
private static String getClientResponse(WebResource resource) {
return resource.accept(MediaType.TEXT_XML).get(ClientResponse.class)
.toString();
}

/**
* Returns the response as XML
* e.g : <User><Name>Pavithra</Name></User>
*
* @param service
* @return
*/
private static String getResponse(WebResource resource) {
return resource.accept(MediaType.TEXT_XML).get(String.class);
}
}

运行这个客户端代码，得到结果：

Client Response
GET http://localhost:8080/RESTfulWS/rest/UserInfoService/name/Pavithra returned a response status of 200 OK
Response
<User><Name>Pavithra</Name></User>

Client Response
GET http://localhost:8080/RESTfulWS/rest/UserInfoService/age/25 returned a response status of 200 OK
Response
<User><Age>25</Age></User>

2.集成jersey到spring

1，导入jar包：jersey-spring-1.7.jar等
2，在web.xml文件中修改原来的配置为如下：

<!-- 发布资源的方式之一，Jersey与spring整合，WebService配置 -->  
<servlet>  
<span style="white-space:pre">	</span><servlet-name>JAX-RS REST Servlet</servlet-name>  
<span style="white-space:pre">	</span><servlet-class>com.sun.jersey.spi.spring.container.servlet.SpringServlet</servlet-class>  
<span style="white-space:pre">	</span><!-- 服务端  webservice类的包路径 -->
<span style="white-space:pre">	</span><init-param>
<span style="white-space:pre">		</span><param-name>com.sun.jersey.config.property.packages</param-name>
<span style="white-space:pre">		</span><param-value>cn.hydom.ztc.ws.impl</param-value>
<span style="white-space:pre">	</span></init-param>
<span style="white-space:pre">	</span><load-on-startup>1</load-on-startup>
</servlet>  
<servlet-mapping>  
<span style="white-space:pre">	</span><servlet-name>JAX-RS REST Servlet</servlet-name>  
<span style="white-space:pre">	</span><url-pattern>/services/*</url-pattern>  
</servlet-mapping>

3，在web服务的实体类上加注解(@Component)，一个简单的示例：

@Component
@Path("/user")
public class UserResource {
 
    @Path("/users/{username}")
    @GET
    @Produces(MediaType.TEXT_PLAIN) //@Produces(MediaType.TEXT_XML) | @Produces(MediaType.APPLICATION_JSON)
    public String getUser(@PathParam("username") String username) {
        log.debug("username:{}", username);
        return username;
    }

    @Path("/users/save")
    @POST
    @Consumes(MediaType.APPLICATION_FORM_URLENCODED) //请求数据类型
    public void saveUser(@FormParam("id") String id,
                         @FormParam("username") String username, @Context HttpServletRequest request,
                         @Context HttpServletResponse response) {
        log.debug("id:{}, username:{}", id, username);
        log.debug("request:{}, response:{}", request, response);
    }
}

4，返回结果：

直接返回对象,用@Produces控制输出的格式为Html/Xml/JSON等.
返回Response对象,根据不同的输入参数,决定返回Xml/JSON.

@XmlRootElement
public class User {

private int id;

private String username;

public User() {
}

public User(int id, String username) {
this.id = id;
this.username = username;
}

// setter getter //
...
}

,5，异常处理
最简单的抛一个干净的500错误,throw new WebApplicationException();

如果需要自定义错误返回码和错误信息,可以使用如下方法:

new WebApplicationException(Response.status(status).entity(message).type(MediaType.TEXT_PLAIN).build());

6，参数解释

@Component注解定义此类为spring组件,即bean类.

@Path注解的值是一个相对的URI路径,值得注意的是你仍然可以在URI中嵌入变量,方法如下@Path(“/users/{username}”).

如果需要对userName进行规则匹配,可以自定义的正则表达式,它将覆盖默认的正则表达式”[^/]+”.

例如@Path(“users/{username: [a-zA-Z][a-zA-Z_0-9]}*”),这里username将只匹配一个大写或小写字母和零个或多个字母数字字符和下划线开头,如果给定参数不匹配,将出现404错误.

@Path中定义的URL前后是否有”/”,都不会有影响,但如果你启用了重定向机制,则上面的规则无效.

@GET注解是请求方法指示符,这个指示符注解的Java方法会处理HTTP GET请求.

@Produces注解用于指定MIME类型,通常与MediaType联用,可定义在方法区或者类定义上.

若方法区上与类定义上都指定了@Produces,那么方法区上的@Produces会覆盖掉类定义上的@Produces.

@QueryParam注解用于从请求的URL中提取查询参数,且只能在get请求中使用,@QueryParameter可以转换任何有以String为参数的构造函数类.

@DefaultValue注解表示如果url中参数不存在,则会按DefaultValue给定值赋值,如果url中给定值不是给定类型,则会报404错误.

@Consumes注解指定了客户端发送的MIME媒体类型,与@Produces一样,通常与MediaType联用,并且可定义在方法区或者类定义上.

@POST注解是请求方法指示符,这个指示符注解的Java方法会处理HTTP POST请求.

@Context注解是注入上下文对象,如Request,Response,UriInfo,Servlet,Context等.

@FormParam注解用于POST请求,@QueryParam用于GET请求,作用与@QueryParam一样.