通过 Jersey 客户端 API 调用 REST 风格的 Web 服务

Jersey 1.0 是一个开源的、可以用于生产环境的 JAX-RS（RESTful Web Services 的 Java API 规范，JSR-311）实现。通过 Jersey 可以很方便的使用 Java 来创建一个 RESTful Web Services。

    一篇早期的技术文章——《在 Java 中实现 RESTful Web Services》，介绍了 RESTful，JAX-RS 以及 Jersey。它同样向你展示了怎样使用 Java 来写一个遵循 JAX-RS 标准的 RESTful Web Services。另一篇文章《在 Jersey 1.0 中为 RESTful Web Services 配置 JSON》说明了怎么通过 Jersey 1.0 来配置数据格式为 JSON（JavaScript 对象符号）。

    在这篇文章中，你将学到怎么使用 Jersey 1.0.2 客户端 API 来创建基于 HTTP 的 RESTful Web Services。Jersey 1.0.2 客户端 API 是一个易于使用的，高层的的 Java API，可以帮助你编写任何基于 HTTP 的 RESTful Web Services。这个 API 构建于一个统一的接口规范，其中的一个关键就是 REST 原则。这个统一的接口规范意味着一个基于 REST 的应用程序不管它访问任何 URL，那些 URL 的接口都必须是一样的。

    Jersey 客户端 API 基础

    要开始使用 Jersey 客户端 API，你首先需要创建一个 com.sun.jersey.api.client.Client 类的实例。下面是最简单的方法：

import com.sun.jersey.api.client.Client;
Client client = Client.create();

    Client 类是创建一个 RESTful Web Service 客户端的主要配置点。你可以使用它来配置不同的客户端属性和功能，并且指出使用哪个资源提供者。创建一个 Client 类的实例是一个比较昂贵的操作，所以尽量避免创建一些不需要的客户端实例。比较好的方式是尽可能地复用已经存在的实例。

    当你创建完一个 Client 类的实例后，你可以开始使用它。无论如何，在发出请求前，你需要创建一个 WebResource 对象来封装客户端所需要的 Web 资源。例如，以下代码为一个完整地址为 http://example.com/base 的 Web 资源创建了一个 WebResponse 对象：

import com.sun.jersey.api.client.WebResource;
WebResource webResource = c.resource("http://example.com/base");

    通过使用 WebResource 对象来创建要发送到 Web 资源的请求，以及处理从 Web 资源返回的响应。例如，你可以使用 WebResource 对象来发送 HTTP GET、PUT、POST 以及 DELETE 请求。

    GET 请求：使用 WebResource 类的 get() 方法来提交一个 HTTP GET请求到 Web 资源：

String s = webResource.get(String.class);

    这表示如果 WebResource 对象的 URL 是 http://example.com/base，那么一个 HTTP GET 请求将会发送到地址为 http://example.com/base 的资源。如果你熟悉命令行下的 HTTP 工具 curl，那么你可以知道：

String s = webResource.get(String.class);

    相应的 curl 命令如下：

curl http://example.com/base

    你还可以指定 get() 请求时的查询参数。例如，下面的代码在 get() 请求中指定了两个查询参数：

MultivaluedMap queryParams = new MultivaluedMapImpl();
queryParams.add("param1", "val1");
queryParams.add("param2", "val2");
String s = webResouce.queryParams(queryParams).get(String.class);

    相应的 curl 命令如下：

curl http://example.com/base?param1=val1&param2=val2

    你还可以指定响应所能接受的 MIME 类型。例如，下面的代码指定了响应的 MIME 类型只能为文本：

String s = webResource.accept("text/plain").get(String.class);

    相应的 curl 命令如下：

curl -HAccept:text/plain http://example.com/base

    另外，你还可以获取对应请求的 HTTP 状态码，例如下面这个例子展示获取一个请求所返回的文本实体与状态码：  

ClientResponse response = webResource.accept("text/plain")                                     .get(ClientResponse.class);int status = response.getStatus();String textEntity = response.getEntity(String.class);  

    ClientResponse 对象代表了一个客户端收到的 HTTP 响应。

 

    PUT 请求：使用 WebResource 类的 put() 方法来提交一个 HTTP PUT 请求到 Web 资源。例如下面的代码展示了请求发送一个文本实体 foo:bar 到指定的 Web 资源:

ClientResponse response = webResource.type("text/plain")                                     .put(ClientResponse.class, "foo:bar");

    相应的 curl 命令如下：

curl -XPUT -HContent-type:text/plain --data "foo:bar" http://example.com/base

    同样，你也可以在使用 put() 方法发送请求时指定查询参数，方法与使用 get() 方法时指定查询参数一样。在下面的例子中，把在之前 get() 方法示例中使用过的两个同样的查询参数指定到了一个 put() 请求中：

MultivaluedMap queryParams = new MultivaluedMapImpl();queryParams.add("param1", "val1");queryParams.add("param2", "val2");ClientResponse response = webResource.queryParams(queryParams)                                     .put(ClientResponse.class, "foo:bar");

    相应的 curl 命令如下：

curl -XPUT -HContent-type:text/plain --data "foo:bar" http://example.com/base?param1=val1&param2=val2

    POST 请求：一个 POST 请求相当于一个 GET 请求和一个 PUT 请求的综合，也就意味着，你可以使用 POST 请求来发送一个实体到指定的 Web 资源并且接收另一个实体。使用 WebResource 类的 post() 方法来发送一个 HTTP POST 请求到指定的 Web 资源。下面的例子展示了发送一个带有查询参数以及进行了 URL 编码的表单数据的 POST 请求：

MultivaluedMap formData = new MultivaluedMapImpl();formData.add("name1", "val1");formData.add("name2", "val2");ClientResponse response = webResource.type("application/x-www-form-urlencoded")                                     .post(ClientResponse.class, formData);

    相应的 curl 命令如下：

curl -d name1=val1 -d name2=val2 http://example.com/base

    DELETE 请求：使用 WebResource 类的 delete() 方法来发送珍上 HTTP DELETE 请求到指定的 Web 资源。例如，下面的例子展示删除一个 URI 为 http://example.com/base/user/123 资源：

ClientResponse response = webResource.path("user/123")                                     .delete(ClientResponse.class);

    相应的 curl 命令如下：

curl -XDELETE http://example.com/base/user/123

    另外，WebResource.path() 方法可以在所有 HTTP 请求中使用，它可以让你给要请求的 Web 资源指定一个额外的路径。另一个 WebResouce 类的方法 header() 可以给你的请求添加 HTTP 头部信息。

    配置 Jersey 客户端

    在发送请求前，你还需要配置 Jersey 客户端，这涉及到注册提供程序。另外你也可以添加过滤器 ，这是可选的操作。你可以查阅 Jersey 1.0.2 客户端 API 来得到所有可选操作的概览。

 

    注册提供程序：在 JAX-RS 中，提供程序是指一个 JAX-RS 扩展的实现。一个提供程序类被一个 @Provier 注解所标注。Jersey 服务器实现了提供程序的基础结构。在实现 JAX-RS 时，Jersey 包含了标准的提供程序类。Jersey 客户端 API 重用了与 Jersey 服务器同样的提供程序基础结构。无论如何，你都必须显式的注册所有非标准的提供程序，因为在客户端不会自动进行类库路径的搜索。

 

    要注册一个提供程序，你需要将提供程序的类添加到 ClientConfig 对象用来创建 Client 类的实例。ClientConfig 类定义了通用的属性名称、功能、属性、提供程序类，以及可以被 Client 对象使用的单例提供程序实例。例如下面的代码注册了一个供 Client 对象使用的 JSON 提供程序：

ClientConfig config = new DefaultClientConfig();config.getClasses().add(JSONRootElementProvider.class);Client client = Client.create(config);

    注意 DefaultClientConfig 类的使用，它定义了默认的 Client 配置。

 

    添加过滤器：另外一个在配置 Client 过程中可选的操作是添加过滤器到 Client 实例。过滤器动态的拦截到一个资源类的请求和响应，并且可以修改请求或响应。Jersey 客户端 API 提供了一些工具类过滤器。其中之一是 LoggingFilter，它实现了一个日志记录过滤器。你可以使用一个日志记录过滤器来跟踪客户端与服务器之间的通信，这在调试的时候往往很有用。下面的代码展示了怎么添加一个日志记录过滤器到客户端：

import com.sun.jersey.api.client.filter.LoggingFilterclient.addFilter(new LoggingFilter());

    一个基于 Jersey 客户端的示例

    跟随这个提示的是一个使用 Jersey 客户端 API 来存取目前流行的 Twitter 的 Web 服务的应用程序示例。这个示例演示了 Jersey 客户端 API 使用现实世界中基于 HTTP 的 Web 服务的能力。你可以下载这个示例程序  Twitter 客户端的压缩包。解开压缩包后你可以查阅这个客户端的源代码。或者你也可以下载一个可执行的 Twitter 客户端 JAR 文件来看看它是怎么工作的。注意你先需要安装有 Java SE Runtime Environment (JRE) 6 才能运行这个程序。

 

    Twitter: Twitter 是一个允许你与朋友、同事、家人或者其他人之间交换简短信息的服务。那些信息是用来回答“你在干什么”这个问题。下面是通过 Twitter 显示一些信息的例子：

    

Twitter Messages

    Twitter 提供了一个公开的 Twitter API ，你可以通过这个 API 来使用编程的方式发表或查看 Twitter 消息，或使用这个服务的其他功能。如果你要使用 Twitter API，有一件事你必须考虑到是Twitter的认证和安全机制和要求。

    Twitter 认证与安全：Twitter 使用基本的 HTTP 认证语法。这意味着如果你要通过 Twitter API 来存取 Twitter，你需要在你的请求中添加认证头。如果你需要更安全的通信，那么你同样可以使用 SSL(Secure Sockets Layer) 来与服务器进行通信。你只需要简单的依照下面的代码做即可：

ClientConfig config = new DefaultClientConfig();SSLContext ctx = SSLContext.getInstance("SSL");ctx.init(null, myTrustManager, null);config.getProperties().put(HTTPSProperties.PROPERTY_HTTPS_PROPERTIES,                             new HTTPSProperties(hostnameVerifier, ctx));Client client = Client.create(config);

    查看客户端源代码：下载 Twitter 客户端压缩包 并解压缩。在 srcmainjavacomsunjerseytechtipstwitter 目录中定位到 TwitterClient 类。这是应用程序中基于 Jersey 的客户端。

 

    在你查看 TwitterClient 类的源代码时，特别需要注意下面几点：

 

• 创建 Client 和 WebResource 对象的代码
  

import com.sun.jersey.api.client.Client;import com.sun.jersey.api.client.WebResource;private static final String BaseURI = "https://twitter.com";private final WebResource wr;Client client = Client.create(config);wr = client.resource(BaseURI);

• 配置客户端的代码

import com.sun.jersey.api.client.config.ClientConfig;import com.sun.jersey.api.client.config.DefaultClientConfig;ClientConfig config = new DefaultClientConfig();   config.getProperties().put(HTTPSProperties.PROPERTY_HTTPS_PROPERTIES,                                new HTTPSProperties(hv, ctx));config.getClasses().add(JAXBContextResolver.class);

• 发出一个 GET 请求的代码

public List<StatusBean> getFriendsTimelineJson() {

   return wr.path("statuses/friends_timeline.json")

  .header(AUTHENTICATION_HEADER, authentication)

  .accept(MediaType.APPLICATION_JSON_TYPE)

  .get(new GenericType<List<StatusBean>>() {

   });

}

        注意在请求时添加的认证头部。

    运行示例程序

    要运行这个示例程序，按以下步骤操作：

1. 如果你还没有安装 JRE 6，下载 并安装它。
2. 下载 Twitter 客户端 JAR 文件
3. 在命令行中执行以下指令：

java -jar jersey-twitter-client-1.0-SNAPSHOT-jar-with-dependencies.jar

        程序运行后会提示你输入你的 Twitter 用户名和密码，按提示进行合适的操作，你可以看到带有时间戳的 Twitter 消息。下面是一个例子：

Simple Jersey (http://jersey.dev.java.net) based twitter clientTwitter username:mytwitterPassword:Hello mytwitter!Status will get updated every 60 secs.Enter !exit to finish the session.Arun Gupta (1238705837), at: Mon Feb 23 00:04:40 +0000 2009: #slumdog is a favorite ... have not seen the movie yet but would be great if it's the first Indian movie to win ... fingers crossed!LarryLary (1238103969), at: Mon Feb 23 00:07:33 +0000 2009: Gonna go for a walk. Need some fresh air.kmollo (1239025876), at: Mon Feb 23 01:43:34 +0000 2009: enjoying everyone's '15 Albums That Changed Your Life' lists. I have been so bored, it's nice to have some 'new' music to check out!iFab @fauntleroy (1239103887), at: Mon Feb 23 02:02:20 +0000 2009: It's a beautiful dayJessicaxG (1239248068), at: Mon Feb 23 02:36:34 +0000 2009: Shop. Shop. Shop. Another way to avoid things I need to do.DoughJoe (1239571723), at: Mon Feb 23 03:55:39 +0000 2009: Slumdog grabs it all> Congratulations to Kate Winslet on her best actress Oscar.Posted at: Tue Feb 24 16:54:17 +0000 2009>!exitbye

        注意你也可以在这个客户端中输入你自己的消息。

    深入阅读

    要进一步了解 Jersey，查阅以下资源：

• Jersey 1.0.2 客户端 API
• Jersey 项目
• 在 Jersey 1.0 中为 REST 风格 Web 服务配置 JSON
• 使用 Java 实现 REST 风格的 Web 服务