49.3. 构建客户端调用

构建目标 URI 后，使用 WebTarget 构建器类，下一步是配置请求的其他方面，如 HTTP 标头、Cookie 等等，因此使用 Invocation.Builder 类。构建调用的最后一步是调用适当的 HTTP 动词(GET、POST、PUT 或 DELETE)，并提供消息正文（如果需要）。

javax.ws.rs.client.Invocation.Builder builder 类提供了 fluent API 的一部分，可让您构建 HTTP 消息的内容并调用 HTTP 方法。

要创建 Invocation.Builder 实例，请在 javax.ws.rs.client.WebTarget 实例中调用其中一个 请求 方法。例如：

// Java
import javax.ws.rs.client.WebTarget;
import javax.ws.rs.client.Invocation.Builder;
...
WebTarget books = client.target("http://example.org/bookstore/books/123");
Invocation.Builder invbuilder = books.request();

您可以使用标头方法在请求消息中添加 HTTP 标头，如下所示：

Invocation.Builder invheader = invbuilder.header("From", "fionn@example.org");

您可以使用 cookie 方法在请求消息中添加 Cookie，如下所示：

Invocation.Builder invcookie = invbuilder.cookie("myrestclient", "123xyz");

您可以使用属性方法在此请求上下文中设置属性，如下所示：

Invocation.Builder invproperty = invbuilder.property("Name", "Value");

您可以定义可接受的介质类型、语言或编码，如下所示：

Invocation.Builder invmedia = invbuilder.accept("application/xml")
                                        .acceptLanguage("en-US")
                                        .acceptEncoding("gzip");

构建 REST 调用的过程通过调用 HTTP 方法终止，该方法执行 HTTP 调用。可以调用以下方法（从 javax.ws.rs.client.SyncInvoker 基础类）调用：

get
post
delete
put
head
trace
options

如果此列表中没有调用的特定 HTTP 动词，您可以使用通用方法方法调用任何 HTTP 方法。

所有 HTTP 调用方法都提供未输入的变体和类型变体（取一个额外的参数）。如果您使用默认 get （） 方法调用请求（无参数），则从调用中返回 javax.ws.rs.core.Response 对象。例如：

Response res = client.target("http://example.org/bookstore/books/123")
                     .request("application/xml").get();

但是，也可以使用 get (Class<T>) 方法要求以特定类型返回响应。例如，要调用请求并要求以 BookInfo 对象返回响应：

BookInfo res = client.target("http://example.org/bookstore/books/123")
                     .request("application/xml").get(BookInfo.class);

但是，为了正常工作，您必须将合适的 实体供应商 注册到 Client 实例，该实例能够将响应格式 application/xml 映射到请求的类型。有关实体供应商的详情，请参阅 第 49.4 节 “解析请求和响应”。

对于在请求中包含消息正文（如 POST 或 PUT）的 HTTP 方法，您必须将消息正文指定为方法的第一个参数。邮件正文必须指定为 javax.ws.rs.client.Entity 对象，其中 实体 封装消息内容及其关联的介质类型。例如，要调用 POST 方法，其中消息内容作为 String 类型提供：

import javax.ws.rs.client.Entity;
...
Response res = client.target("http://example.org/bookstore/registerbook")
                     .request("application/xml")
                     .put(Entity.entity("Red Hat Install Guide", "text/plain"));

如有必要，Entity.entity （） 构造器方法将自动使用注册的实体提供程序将提供的消息实例映射到指定的介质类型。始终可以将消息正文指定为一个简单的 String 类型。

您可以选择创建 javax.ws.rs.client.Invocation 对象，而不必立即调用 HTTP 请求（例如，通过调用 get （） 方法）。Invocation 对象 封装 待处理调用的所有详情，包括 HTTP 方法。

以下方法可用于构建 Invocation 对象：

buildGet
buildPost
buildDelete
buildPut
build

例如，要创建一个 GET Invocation 对象并在以后调用它，您可以使用类似如下的代码：

import javax.ws.rs.client.Invocation;
import javax.ws.rs.core.Response;
...
Invocation getBookInfo = client.target("http://example.org/bookstore/books/123")
                     .request("application/xml").buildGet();
...
// Later on, in some other part of the application:
Response = getBookInfo.invoke();

JAX-RS 2.0 客户端 API 支持客户端上的异步调用。要进行异步调用，只需在以下 request （） 链中调用 async （） 方法。例如：

Future<Response> res = client.target("http://example.org/bookstore/books/123")
                     .request("application/xml")
                     .async()
                     .get();

当您进行异步调用时，返回的值是一个 java.util.concurrent.Future 对象。有关异步调用的详情，请参考 第 49.6 节 “客户端上的异步处理”。