49.3. 클라이언트 할당 빌드

WebTarget 빌더 클래스를 사용하여 대상 URI를 빌드한 후 다음 단계는 HTTP 헤더, 쿠키 등 요청의 다른 측면을 구성하는 것입니다. 호출을 빌드하는 마지막 단계는 적절한 HTTP 동사(GET, POST, PUT 또는 DELETE)를 호출하고 필요한 경우 메시지 본문을 제공하는 것입니다.

javax.ws.rs.client.Invocation.Builder 빌더 클래스는 HTTP 메시지의 내용을 빌드하고 HTTP 메서드를 호출할 수 있는 fluent API의 일부를 제공합니다.

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");

다음과 같이 쿠키 방법을 사용하여 요청 메시지에 쿠키 를 추가할 수 있습니다.

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

다음과 같이 속성 메서드를 사용하여 이 요청의 컨텍스트에서 속성을 설정할 수 있습니다.You can set a property in the context of this request using the property method, as follows:

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.Sync invoker 기본 클래스에서 상속됨)을 호출할 수 있습니다.

get
post
delete
put
head
trace
options

호출하려는 특정 HTTP 동사가 이 목록에 없는 경우 일반 메서드 메서드를 사용하여 모든 HTTP 메서드를 호출할 수 있습니다.If the specific HTTP verb you want to invoke is not on this list, you can use the generic method method to invoke any HTTP method.

모든 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 을 요청된 유형으로 매핑할 수 있는 Client 인스턴스에 적합한 엔터티 공급자 를 등록해야 합니다. 엔터티 공급자에 대한 자세한 내용은 49.4절. “요청 및 응답 구문 분석” 을 참조하십시오.

메시지 본문을 요청에 포함하는 HTTP 메서드 (예: POST 또는 PUT)의 경우 메시지 본문을 메서드의 첫 번째 인수로 지정해야 합니다.For HTTP methods that include a message body in the request (such as POST or PUT), you must specify the message body as the first argument of the method. 메시지 본문은 javax.ws.rs.client.Entity 오브젝트로 지정해야 합니다. 여기서 Entity 는 메시지 내용 및 관련 미디어 유형을 캡슐화합니다. 예를 들어 메시지 내용이 String 유형으로 제공되는 POST 메서드를 호출하려면 다음을 수행합니다.

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() 생성자 메서드는 등록된 엔터티 공급자를 사용하여 제공된 메시지 인스턴스를 지정된 미디어 유형에 자동으로 매핑합니다. 메시지 본문을 간단한 문자열 유형으로 지정할 수 있습니다.

HTTP 요청을 바로 호출하는 대신(예: get() 메서드를 호출하여) 나중에 호출할 수 있는 javax.ws.rs.client.Invocation 오브젝트를 생성하는 옵션이 있습니다. 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절. “클라이언트의 비동기 처리” 을 참조하십시오.