用Jersey编写REST风格的web服务

by Xiang Zhuyuan

本文英文原文来自REST with Java (JAX-RS) using Jersey – Tutorial

1. Rest ( representational state transfer)

1.1 概述

REST是一种基于HTTP协议的一种架构.在2000年被Roy Fielding提出

在REST风格的架构设计中,所有事物被看做是资源.一个资源能够通过

一个基本的http请求来获取.在REST架构的工程中,应该有一个server来提供访问资源,一个客户端来修改资源.每一个资源都能够被http请求来操作.每一个资源对应一个唯一的URI.

1.2 Http方法

在REST的架构设计中,一般有PUT,GET,POST,DELETE几种方法.

  1.     GET这个一般就是只能读取一个资源.而不能够修改它.
  2.     PUT会创建一个新的资源.必须是幂等的.
  3.     DELETE会移除资源.这个操作也会是幂等的.获取的结果都是一样的.
  4.     POST会创建一个新的或者更新一个已经存在的资源.

1.3 RESTFul web services

一个REST风格的web服务也就是基于一个HTTP方法和REST概念的方法.一般将会给这个服务定义一个基本的URI,还有MIME类型(支持xml,json,user-defined,…)还有就是所要采用的方法类型.

1.4 Java,REST和Jersey

java通过JAX-RS(The Java API for RESTful Web Services)来通过了标准的REST支持.它通过使用注解(annotations)来定义相关的类.

通过在web.xml中注册由Jersey提供的servlet,同时定义rest工程的路径,servlet的基本的URL是这样的:

http://yourdomain:port/display-name/url-pattern/pathfromrestclass

这个servlet会分析过来的http请求,然后选择合适的类和方法来响应这个请求,选择的依据就是类和方法各自添加的注解.

在JAX-RS中最常见的注解是:

注解描述
@PATH(yourpath)Sets the path to base URL + /yourpath. The base URL is based on your application name, the servlet and the URL pattern from the web.xml” configuration file.
@POSTIndicates that the following method will answer to a HTTP POST request
@GETIndicates that the following method will answer to a HTTP GET request
@PUTIndicates that the following method will answer to a HTTP PUT request
@DELETEIndicates that the following method will answer to a HTTP DELETE request
@Produces( MediaType.TEXT_PLAIN [, more-types ] )@Produces defines which MIME type is delivered by a method annotated with @GET. In the example text (“text/plain” ) is produced. Other examples would be “application/xml” or “application/json”.
@Consumes( type [, more-types ] )@Consumes defines which MIME type is consumed by this method.
@PathParamUsed to inject values from the URL into a method parameter. This way you inject for example the ID of a resource into the method to get the correct object.
一个完整的路径来获取资源就是由基本URL加上在对应的类上@PATH注解中的路径.

http://your_domain:port/display-name/url-pattern/path_from_rest_class

Jersey就是这个的规范的参考实现.Jersey包括基本的REST服务端和客户端.核心的客户端能够提供测试以及用来和服务端通信的库. 一个REST的web程序是由数据类和服务构成的,这两个部分一般都是分开在两个包下存放.jersey的servlet是通过web.xml来找到对应的数据类.