49.3. 构建 Client Invocation

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

javax.ws.rs.client.Invocation.Builder 构建器类提供 fluent API 的一部分，使您能够构建 HTTP 消息的内容并调用 HTTP 方法。

若要创建 Invocation.Builder 实例，可在 javax.ws.rs.client.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);

但是，为了解决这个问题，您必须使用 客户端 实例注册合适的 实体提供程序，该供应商可以将响应格式 application/xml 映射到请求的类型。有关实体供应商的详情，请参考 第 49.4 节 “解析请求和响应”。

对于在请求中包含消息正文的 HTTP 方法（如 POST 或 PUT），您必须将消息正文指定为方法的第一个参数。消息正文必须指定为 javax.ws.rs.client.Entity 对象，其中 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 （） 构造器方法会自动将提供的消息实例映射到指定介质类型（使用注册的实体提供程序）。始终可以将消息正文指定为简单的 String 类型。

您可以选择创建 javax.ws.rs.client.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 节 “客户端上的异步处理”。