49.3. 클라이언트 호출 빌드

대상 URI를 빌드한 후 WebTarget 빌더 클래스를 사용하여 HTTP 헤더, 쿠키 등 요청의 다른 측면(예: Invocation.Builder 클래스를 사용하여 구성)을 구성합니다. 호출을 빌드하는 마지막 단계는 적절한 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");

다음과 같이 속성 메서드를 사용하여 이 요청 컨텍스트에서 속성을 설정할 수 있습니다.

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

요청에 메시지 본문을 포함하는 HTTP 메서드(예: POST 또는 PUT)의 경우 메시지 본문을 메서드의 첫 번째 인수로 지정해야 합니다. 메시지 본문은 javax.ws.rs.client.Entity 개체로 지정해야 합니다. 여기서 엔터티 는 메시지 내용 및 관련 미디어 유형을 캡슐화합니다. 예를 들어 메시지 콘텐츠가 문자열 유형으로 제공되는 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();

Cryostat-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절. “클라이언트에서 비동기 처리” 을 참조하십시오.