JAX-RS 2.0 REST客户端编程实例
2015-03-25 12:36
246 查看
JAX-RS 2.0 REST客户端编程实例
2014/01/28 | 分类: 基础技术, 教程 | 0 条评论 | 标签: JAX-RS, RESTFUL分享到:3
本文由 ImportNew - 靳禹 翻译自 hascode。欢迎加入翻译小组。转载请见文末要求。
导读
JAX-RS 2.0 又称 JSR 339 不仅定义了一套用于构建 RESTful 网络服务的 API,同时也通过增强客户端 API 功能简化了REST 客户端的构建过程。
JAX-RS: Java API for RESTful Web Services是一个Java编程语言的应用程序接口,支持按照 表象化状态转变 (REST)架构风格创建Web服务Web服务[1]. JAX-RS使用了Java SE 5引入的Java 标注来简化Web服务客户端和服务端的开发和部署 [wikipedia]。
在下面的教程中,我们将为一个预先设置好的 REST 服务构建一个客户端,并在这个过程中探索新的构建选项。例如,如何处理同步或者异步的请求,如何给一个请求注册一个回调,如何指定调用对象来构建一个请求使得请求可以被延迟执行。再或者比如,如何使用客户端请求和相应的过滤方法来过滤客户端与服务器之前的通信。
我们开始吧
对于想要重建下述客户端例子的读者,我已经使用 Maven 创建好了一个完整的 RESTful 网络服务程序。程序中有内嵌的应用程序服务器,以及一个可独立运行的应用服务器 (war-file 可以通过下文中的下载地址获取)。请根据下面的一系列命令来下载并启动 REST 服务器 (下载所有依赖可能会耗费些时间……):
REST 服务
下面的代码就是个客户端提供服务的 REST 服务。这里的 BookRepository 就是一个由 @Singleton 和 @Startup 修饰的简单 session bean,这个 bean 用来模拟存储或获取 Book Entity。服务对外提供了保存一本书、删除一本书、根据标识查找书籍和获取所有可用书籍的接口。当一本书被保存在服务端时,服务器会为该书生成一个 id,并会返回一个 entity 或一组 entity 的 JSON 数据。Book Entity
下面代码中的 bean 就是贯穿本教程的 Book Entity,它包含id、书名、价格和出版日期属性。创建并绑定一个客户端
我们可以创建一个 REST 客户端,将其绑定到一个特定的目标 URL 上。并且为它指定专属的、参数化的路径。具体步骤如下:通过 ClientBuilder 获取一个客户端的引用:Client client = ClientBuilder.newClient();
使用 target() 方法将客户端绑定到 REST 服务上提供的某个 URL:client.target(“http://localhost:8080/myrestservice”);
通过 path() 和 resolveTemplate() 方法来处理动态的 URL 路径参数:client.target(..).path(“{id}”).resolveTemplate(“id”, someId);
使用 request() 函数来初始化一个请求并用后续的 post 或者 get 等方法来指定请求的类型,例如:client.target(..).request().get();
每一步都提供了多样的可选择的参数和配置选项,稍后的教程中我将用到其中的一些配置像异步请求、回调处理、还有过滤器注册和特性类等。
现在,让我们先看一些具备说明性的例子。
客户端例子
由于我把所有客户端示例都融进了 jUnit 和 Hamcrest 驱动的测试用例,因此下面的代码实际上在每一个测试用例中都有使用。不过为了让文章尽量简练,重复代码将在后面的代码示例中省略。Maven 整合
所有代码示例运行都需要用到下面依赖:基础操作
下面的示例中我们首先将一个书本实体的信息序列化成 JSON 格式,通过 POST 请求发送到服务端来保存这本书。之后,我们使用客户端提供的 path() 和 resolveTemplate() 方法通过匹配服务端返回值的协议来获取该本书的标识。
第三步, 我们获取所有可用图书的列表,并在最后删除掉刚才保存的那本书。
异步处理
只要给请求构造器加一个简单的 async() 方法,我们就可以使用 Java 的 Future API 提供的多种途径来异步地处理请求。下面的例子中,我们在第一个请求中添加一本书,然后再删除它。最后获取所有可用图书的列表。
发起回调
在客户端与服务器通信过程中,我们还有另一种方式可以对服务器的相应进行修改,那就是在请求中加入一个 InvocationCallback 回调处理。可以看到,下面代码段中有着很多缩进那部分就是我们的回调函数了,这些回调可以打印保存成功的图书的完整信息,或者在出现错误的情况下则打印错误和堆栈信息。
延迟调用 / 请求构建
通过 javax.ws.rs.client.Invocation 类,我们可以先构建一个请求而不用即时发送。这个请求可以是同步的, 也可以是异步的。在下面的示例中,我们构建了两个调用但并不马上使用—— 一个请求用来保存图书,另一个请求则是获取所有可用的图书。然后,我们在后面调用时才使用这两个构建好的请求。
我们应当使用 invoke() 方法来同步地调用一个请求。当需要使用异步请求时,则需要用 submit() 方法——两种调用都会返回一个 javax.ws.rs.core.Response 对象。如果调用者在调用参数中给定了返回实体的类,则上述方法会返回该类。
客户端请求过滤器
JAX-RS 允许我们使用请求过滤器来截获客户端发送到服务器的请求。为了达成这个目标,只需要实现 javax.ws.rs.client.ClientRequestFilter 这个接口。当创建客户端时,使用客户端的 register() 方法将 ClientRequestFilter 的具体实现注册到客户端中。
javax.ws.rs.client.ClientRequestContext 对象将赋予访问信息请求足够的权限。
下面就是一个客户端请求过滤的例子。这个例子中,所有客户端发出的 POST 请求中如果包含书籍实体,则书籍价格都会被这个过滤器修改(虽然这不是一个好的实际示例)。对价格的修改则依据相应的税率。
客户端响应过滤器
为了获得对服务器相应的控制,有一个十分类似的办法:客户端相应过滤器。同样地,只要实现 javax.ws.rs.client.ClientResponseFilter 这个接口,就能够修改或者截获服务器返回的响应。
下面这个响应过滤器能够将一些 HTTP 响应头打印到标准输出(STDOUT):
教程源码
欢迎下载本教程中的源码,你可以用 Git 来 Fork 或者直接 Clone:Bitbucket代码仓库。下载 war-File REST 服务器
你可以从这里下载 war-file 然后运行自己的 RESTful 服务:https://bitbucket.org/hascode/jaxrs2-client-tutorial/downloadsJAX-RS 1.0 and JAX-B
如果你对旧版本的协议感兴趣,这篇文章正是你需要的。相关文章推荐
- JAX-RS 2.0 REST客户端编程实例
- JAX-RS 2.0 REST客户端编程实例
- JAX-RS 2.0 REST客户端编程实例
- JAX-RS 2.0 REST 客户端
- RESTLET开发实例(一)基于JAX-RS的REST服务
- JAX-RS 2.0 中 REST 的四种服务类型
- Eclipse Java EE工程报错:JAX-RS (REST Web Services) 2.0 can not be installed、JAX-RS (REST Web Services) 2
- JAX-RS(REST Web Services)2.0 requires Dynamic Web Module 3.1 or newer
- 使用maven整合ssm报错:JAX-RS (REST Web Services) 2.0 can not be installed
- JAX-RS(REST Web Services)2.0 requires Dynamic Web Module 3.1 or newer
- maven+springmvc错误 JAX-RS (REST Web Services) 2.0 can not be installed
- JAX-RS 2.0 REST 请求处理
- 基于JAX-RS 2.0 REST服务几种类型
- JAX-RS(REST Web Services)2.0 can not be installed: One or more constraints have not been satisfied
- maven+springmvc错误 JAX-RS (REST Web Services) 2.0 can not be installed
- RESTLET开发实例(一)基于JAX-RS的REST服务
- Java EE 7 / JAX-RS 2.0: Simple REST API Authentication & Authorization with Custom HTTP Header--reference
- JAX-RS REST客户端实现基本身份验证机制
- 使用 JAX-RS 简化 REST 应用开发 实例
- Eclipse JAX-RS (REST Web Services) 2.0 requires Java 1.6 or newer