Package com.linecorp.armeria.client

Class BlockingWebClientRequestPreparation

java.lang.Object

com.linecorp.armeria.client.BlockingWebClientRequestPreparation

All Implemented Interfaces:

RequestOptionsSetters, RequestPreparationSetters, HttpMessageSetters, PathAndQueryParamSetters, RequestMethodSetters

@UnstableApi
public final class BlockingWebClientRequestPreparation
extends Object

Prepares and executes a new HttpRequest for BlockingWebClient.

Method Summary

Modifier and Type	Method	Description
<U> TransformingRequestPreparation<AggregatedHttpResponse,U>	as(ResponseAs<AggregatedHttpResponse,U> responseAs)	Sets the specified ResponseAs that converts the AggregatedHttpResponse into another.
TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<byte[]>>	asBytes()	Converts the response content into bytes.
<T> TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<T>>	asJson(TypeReference<? extends T> typeRef)	Deserializes the JSON response content into the specified Java type using the default ObjectMapper.
<T> TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<T>>	asJson(TypeReference<? extends T> typeRef, ObjectMapper mapper)	Deserializes the JSON response content into the specified Java type using the specified ObjectMapper.
<T> TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<T>>	asJson(Class<? extends T> clazz)	Deserializes the JSON response content into the specified non-container type using the default ObjectMapper.
<T> TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<T>>	asJson(Class<? extends T> clazz, ObjectMapper mapper)	Deserializes the JSON response content into the specified non-container type using the specified ObjectMapper.
TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<String>>	asString()	Converts the response content into String.
<V> BlockingWebClientRequestPreparation	attr(AttributeKey<V> key, V value)	Associates the specified value with the given AttributeKey in this request.
BlockingWebClientRequestPreparation	content(MediaType contentType, byte[] content)	Sets the content for this message.
BlockingWebClientRequestPreparation	content(MediaType contentType, HttpData content)	Sets the content for this message.
BlockingWebClientRequestPreparation	content(MediaType contentType, CharSequence content)	Sets the content for this message.
BlockingWebClientRequestPreparation	content(MediaType contentType, String content)	Sets the content for this message.
BlockingWebClientRequestPreparation	content(MediaType contentType, String format, Object... content)	Sets the content for this message.
BlockingWebClientRequestPreparation	content(MediaType contentType, org.reactivestreams.Publisher<? extends HttpData> content)	Sets the Publisher for this message.
BlockingWebClientRequestPreparation	content(String content)	Sets the content as UTF-8 for this message.
BlockingWebClientRequestPreparation	content(String format, Object... content)	Sets the content as UTF-8 for this message.
BlockingWebClientRequestPreparation	contentJson(Object content)	Sets the content for this message.
BlockingWebClientRequestPreparation	cookie(Cookie cookie)	Sets a cookie for this message.
BlockingWebClientRequestPreparation	cookies(Iterable<? extends Cookie> cookies)	Sets multiple cookies for this message.
BlockingWebClientRequestPreparation	delete(String path)	Sets DELETE method and path.
BlockingWebClientRequestPreparation	disablePathParams()	Disables path parameters substitution.
BlockingWebClientRequestPreparation	exchangeType(ExchangeType exchangeType)	Sets the ExchangeType that determines whether to stream an HttpRequest or HttpResponse.
AggregatedHttpResponse	execute()	Builds and executes the blocking request.
BlockingWebClientRequestPreparation	get(String path)	Sets GET method and path.
BlockingWebClientRequestPreparation	head(String path)	Sets HEAD method and path.
BlockingWebClientRequestPreparation	header(CharSequence name, Object value)	Adds a header for this message.
BlockingWebClientRequestPreparation	headers(Iterable<? extends Map.Entry<? extends CharSequence,String>> headers)	Adds multiple headers for this message.
BlockingWebClientRequestPreparation	maxResponseLength(long maxResponseLength)	Sets the maximum allowed length of a server response in bytes.
BlockingWebClientRequestPreparation	method(HttpMethod method)	Sets the method for this request.
BlockingWebClientRequestPreparation	options(String path)	Sets OPTIONS method and path.
BlockingWebClientRequestPreparation	patch(String path)	Sets PATCH method and path.
BlockingWebClientRequestPreparation	path(String path)	Sets the path for this request.
BlockingWebClientRequestPreparation	pathParam(String name, Object value)	Sets a path param for this message.
BlockingWebClientRequestPreparation	pathParams(Map<String,?> pathParams)	Sets multiple path params for this message.
BlockingWebClientRequestPreparation	post(String path)	Sets POST method and path.
BlockingWebClientRequestPreparation	put(String path)	Sets PUT method and path.
BlockingWebClientRequestPreparation	queryParam(String name, Object value)	Adds a query param for this message.
BlockingWebClientRequestPreparation	queryParams(Iterable<? extends Map.Entry<? extends String,String>> queryParams)	Adds multiple query params for this message.
BlockingWebClientRequestPreparation	requestAutoAbortDelay(Duration delay)	Sets the amount of time to wait before aborting an HttpRequest when its corresponding HttpResponse is complete.
BlockingWebClientRequestPreparation	requestAutoAbortDelayMillis(long delayMillis)	Sets the amount of time in millis to wait before aborting an HttpRequest when its corresponding HttpResponse is complete.
BlockingWebClientRequestPreparation	requestOptions(RequestOptions requestOptions)	Sets the specified RequestOptions that could overwrite the previously configured values such as RequestOptionsSetters.responseTimeout(Duration), RequestOptionsSetters.writeTimeout(Duration), RequestOptionsSetters.maxResponseLength(long) and RequestOptionsSetters.attr(AttributeKey, Object).
BlockingWebClientRequestPreparation	responseTimeout(Duration responseTimeout)	Schedules the response timeout that is triggered when the Response is not fully received within the specified Duration since the Response started or Request was fully sent.
BlockingWebClientRequestPreparation	responseTimeoutMillis(long responseTimeoutMillis)	Schedules the response timeout that is triggered when the Response is not fully received within the specified responseTimeoutMillis since the Response started or Request was fully sent.
BlockingWebClientRequestPreparation	trace(String path)	Sets TRACE method and path.
BlockingWebClientRequestPreparation	trailer(CharSequence name, Object value)	Adds an HTTP trailer for this message.
BlockingWebClientRequestPreparation	trailers(Iterable<? extends Map.Entry<? extends CharSequence,String>> trailers)	Adds HTTP trailers for this message.
BlockingWebClientRequestPreparation	writeTimeout(Duration writeTimeout)	Sets the amount of time allowed until the initial write attempt of the current Request succeeds.
BlockingWebClientRequestPreparation	writeTimeoutMillis(long writeTimeoutMillis)	Sets the amount of time allowed until the initial write attempt of the current Request succeeds.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

execute

public AggregatedHttpResponse execute()

Builds and executes the blocking request.

as

@UnstableApi
public <U>
TransformingRequestPreparation<AggregatedHttpResponse,U> as(ResponseAs<AggregatedHttpResponse,U> responseAs)

Sets the specified ResponseAs that converts the AggregatedHttpResponse into another.

asBytes

@UnstableApi
public TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<byte[]>> asBytes()

Converts the response content into bytes. For example:

 BlockingWebClient client = BlockingWebClient.of("https://api.example.com");
 ResponseEntity<byte[]> response = client.prepare()
                                         .get("/v1/items/1")
                                         .asBytes()
                                         .execute();
 

asString

@UnstableApi
public TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<String>> asString()

Converts the response content into String. For example:

 BlockingWebClient client = BlockingWebClient.of("https://api.example.com");
 ResponseEntity<String> response = client.prepare()
                                         .get("/v1/items/1")
                                         .asString()
                                         .execute();
 

asJson

@UnstableApi
public <T>
TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<T>> asJson(Class<? extends T> clazz)

Deserializes the JSON response content into the specified non-container type using the default ObjectMapper. For example:

 BlockingWebClient client = BlockingWebClient.of("https://api.example.com");
 ResponseEntity<MyObject> response = client.prepare()
                                           .get("/v1/items/1")
                                           .asJson(MyObject.class)
                                           .execute();
 

Note that this method should NOT be used if the result type is a container such as Collection or Map. Use asJson(TypeReference) for the container type.

Throws:

InvalidHttpResponseException - if the HttpStatus of the response is not success or fails to decode the response body into the result type.

See Also:

• JacksonObjectMapperProvider

asJson

@UnstableApi
public <T>
TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<T>> asJson(Class<? extends T> clazz,
 ObjectMapper mapper)

Deserializes the JSON response content into the specified non-container type using the specified ObjectMapper. For example:

 ObjectMapper mapper = ...;
 BlockingWebClient client = BlockingWebClient.of("https://api.example.com");
 ResponseEntity<MyObject> response = client.prepare()
                                           .get("/v1/items/1")
                                           .asJson(MyObject.class, mapper)
                                           .execute();
 

Note that this method should NOT be used if the result type is a container such as Collection or Map. Use asJson(TypeReference, ObjectMapper) for the container type.

Throws:

InvalidHttpResponseException - if the HttpStatus of the response is not success or fails to decode the response body into the result type.

asJson

@UnstableApi
public <T>
TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<T>> asJson(TypeReference<? extends T> typeRef)

Deserializes the JSON response content into the specified Java type using the default ObjectMapper. This method is useful when you want to deserialize the content into a container type such as List and Map. For example:

 BlockingWebClient client = BlockingWebClient.of("https://api.example.com");
 ResponseEntity<List<MyObject>> response =
     client.prepare()
           .get("/v1/items/1")
           .asJson(new TypeReference<List<MyObject>>() {})
           .execute();
 

Throws:

InvalidHttpResponseException - if the HttpStatus of the response is not success or fails to decode the response body into the result type.

See Also:

• JacksonObjectMapperProvider

asJson

@UnstableApi
public <T>
TransformingRequestPreparation<AggregatedHttpResponse,ResponseEntity<T>> asJson(TypeReference<? extends T> typeRef,
 ObjectMapper mapper)

Deserializes the JSON response content into the specified Java type using the specified ObjectMapper. For example:

 ObjectMapper mapper = ...;
 BlockingWebClient client = BlockingWebClient.of("https://api.example.com");
 ResponseEntity<List<MyObject>> response =
     client.prepare()
           .get("/v1/items/1")
           .asJson(new TypeReference<List<MyObject>>() {}, mapper)
           .execute();
 

Throws:

InvalidHttpResponseException - if the HttpStatus of the response is not success or fails to decode the response body into the result type.

exchangeType

public BlockingWebClientRequestPreparation exchangeType(ExchangeType exchangeType)

Description copied from interface: RequestOptionsSetters

Sets the ExchangeType that determines whether to stream an HttpRequest or HttpResponse. Note that an HttpRequest will be aggregated before being written if ExchangeType.UNARY or ExchangeType.RESPONSE_STREAMING is set. If unspecified, the Clients try to infer a proper ExchangeType depending on the content type of a request and a response. Here are examples:

WebClient

 WebClient client = WebClient.of("https://armeria.dev");

 try (ClientRequestContextCaptor captor = Clients.newContextCaptor()) {
     client.prepare()
           .post("/api/v1/items")
           .contentJson(new Item(...)) // A non-streaming request type.
           .asString()                 // A non-streaming response type.
           .execute();
     assert captor.get().exchangeType() == ExchangeType.UNARY;
 }

 try (ClientRequestContextCaptor captor = Clients.newContextCaptor()) {
     client.get("/api/v1/items")   // A non-streaming request type.
           .aggregate();           // A return type is not specified; Assuming that response streaming
                                   // is enabled.
     assert captor.get().exchangeType() == ExchangeType.RESPONSE_STREAMING;
 }

 try (ClientRequestContextCaptor captor = Clients.newContextCaptor()) {
     client.prepare()
           .post("/api/v1/items")
           .content(MediaType.JSON_LINES, StreamMessage.of(...)) // A streaming request type.
           .asFile(Path.get("/path/to/destination"))             // A streaming response type.
           .execute();
     assert captor.get().exchangeType() == ExchangeType.BIDI_STREAMING;
 }
 

BlockingWebClient

Since a request and a response of BlockingWebClient are fully aggregated, ExchangeType.UNARY is only supported.

 try (ClientRequestContextCaptor captor = Clients.newContextCaptor()) {
     AggregatedHttpResponse response = client.blocking().get("/api/v1/items");
     assert captor.get().exchangeType() == ExchangeType.UNARY;
 }
 

gRPC clients

An ExchangeType is automatically inferred from the io.grpc.MethodDescriptor.MethodType.

 try (ClientRequestContextCaptor captor = Clients.newContextCaptor()) {
     Response response = grpcClient.unaryCall(...);
     assert captor.get().exchangeType() == ExchangeType.UNARY;
 }
 

Thrift clients

Thrift protocols do not support streaming. ExchangeType.UNARY is only supported.

Specified by:

exchangeType in interface RequestOptionsSetters

requestOptions

public BlockingWebClientRequestPreparation requestOptions(RequestOptions requestOptions)

Description copied from interface: RequestPreparationSetters

Sets the specified RequestOptions that could overwrite the previously configured values such as RequestOptionsSetters.responseTimeout(Duration), RequestOptionsSetters.writeTimeout(Duration), RequestOptionsSetters.maxResponseLength(long) and RequestOptionsSetters.attr(AttributeKey, Object).

Specified by:

requestOptions in interface RequestPreparationSetters

get

public BlockingWebClientRequestPreparation get(String path)

Description copied from interface: RequestMethodSetters

Sets GET method and path.

Specified by:

get in interface RequestMethodSetters

post

public BlockingWebClientRequestPreparation post(String path)

Description copied from interface: RequestMethodSetters

Sets POST method and path.

Specified by:

post in interface RequestMethodSetters

put

public BlockingWebClientRequestPreparation put(String path)

Description copied from interface: RequestMethodSetters

Sets PUT method and path.

Specified by:

put in interface RequestMethodSetters

delete

public BlockingWebClientRequestPreparation delete(String path)

Description copied from interface: RequestMethodSetters

Sets DELETE method and path.

Specified by:

delete in interface RequestMethodSetters

patch

public BlockingWebClientRequestPreparation patch(String path)

Description copied from interface: RequestMethodSetters

Sets PATCH method and path.

Specified by:

patch in interface RequestMethodSetters

options

public BlockingWebClientRequestPreparation options(String path)

Description copied from interface: RequestMethodSetters

Sets OPTIONS method and path.

Specified by:

options in interface RequestMethodSetters

head

public BlockingWebClientRequestPreparation head(String path)

Description copied from interface: RequestMethodSetters

Sets HEAD method and path.

Specified by:

head in interface RequestMethodSetters

trace

public BlockingWebClientRequestPreparation trace(String path)

Description copied from interface: RequestMethodSetters

Sets TRACE method and path.

Specified by:

trace in interface RequestMethodSetters

method

public BlockingWebClientRequestPreparation method(HttpMethod method)

Description copied from interface: RequestMethodSetters

Sets the method for this request.

Specified by:

method in interface RequestMethodSetters

See Also:

• HttpMethod

path

public BlockingWebClientRequestPreparation path(String path)

Description copied from interface: RequestMethodSetters

Sets the path for this request.

Specified by:

path in interface RequestMethodSetters

content

public BlockingWebClientRequestPreparation content(String content)

Description copied from interface: HttpMessageSetters

Sets the content as UTF-8 for this message.

Specified by:

content in interface HttpMessageSetters

content

public BlockingWebClientRequestPreparation content(MediaType contentType,
 CharSequence content)

Description copied from interface: HttpMessageSetters

Sets the content for this message.

Specified by:

content in interface HttpMessageSetters

content

public BlockingWebClientRequestPreparation content(MediaType contentType,
 String content)

Description copied from interface: HttpMessageSetters

Sets the content for this message.

Specified by:

content in interface HttpMessageSetters

content

@FormatMethod
public BlockingWebClientRequestPreparation content(@FormatString
 String format,
 Object... content)

Description copied from interface: HttpMessageSetters

Sets the content as UTF-8 for this message. The content is formatted by String.format(Locale, String, Object...) with English locale.

Specified by:

content in interface HttpMessageSetters

content

@FormatMethod
public BlockingWebClientRequestPreparation content(MediaType contentType,
 @FormatString
 String format,
 Object... content)

Description copied from interface: HttpMessageSetters

Sets the content for this message. The content is formatted by String.format(Locale, String, Object...) with English locale.

Specified by:

content in interface HttpMessageSetters

content

public BlockingWebClientRequestPreparation content(MediaType contentType,
 byte[] content)

Description copied from interface: HttpMessageSetters

Sets the content for this message. The content will be wrapped using HttpData.wrap(byte[]), so any changes made to content will be reflected in the request.

Specified by:

content in interface HttpMessageSetters

content

public BlockingWebClientRequestPreparation content(MediaType contentType,
 HttpData content)

Description copied from interface: HttpMessageSetters

Sets the content for this message.

Specified by:

content in interface HttpMessageSetters

content

public BlockingWebClientRequestPreparation content(MediaType contentType,
 org.reactivestreams.Publisher<? extends HttpData> content)

Description copied from interface: HttpMessageSetters

Sets the Publisher for this message.

Specified by:

content in interface HttpMessageSetters

contentJson

public BlockingWebClientRequestPreparation contentJson(Object content)

Description copied from interface: HttpMessageSetters

Sets the content for this message. The content is converted into JSON format using the default ObjectMapper.

Specified by:

contentJson in interface HttpMessageSetters

header

public BlockingWebClientRequestPreparation header(CharSequence name,
 Object value)

Description copied from interface: HttpMessageSetters

Adds a header for this message.

Specified by:

header in interface HttpMessageSetters

headers

public BlockingWebClientRequestPreparation headers(Iterable<? extends Map.Entry<? extends CharSequence,String>> headers)

Description copied from interface: HttpMessageSetters

Adds multiple headers for this message.

Specified by:

headers in interface HttpMessageSetters

See Also:

• HttpHeaders

trailer

public BlockingWebClientRequestPreparation trailer(CharSequence name,
 Object value)

Description copied from interface: HttpMessageSetters

Adds an HTTP trailer for this message.

Specified by:

trailer in interface HttpMessageSetters

trailers

public BlockingWebClientRequestPreparation trailers(Iterable<? extends Map.Entry<? extends CharSequence,String>> trailers)

Description copied from interface: HttpMessageSetters

Adds HTTP trailers for this message.

Specified by:

trailers in interface HttpMessageSetters

pathParam

public BlockingWebClientRequestPreparation pathParam(String name,
 Object value)

Description copied from interface: PathAndQueryParamSetters

Sets a path param for this message.

Specified by:

pathParam in interface PathAndQueryParamSetters

pathParams

public BlockingWebClientRequestPreparation pathParams(Map<String,?> pathParams)

Description copied from interface: PathAndQueryParamSetters

Sets multiple path params for this message.

Specified by:

pathParams in interface PathAndQueryParamSetters

disablePathParams

public BlockingWebClientRequestPreparation disablePathParams()

Description copied from interface: PathAndQueryParamSetters

Disables path parameters substitution. If path parameter is not disabled and a parameter is specified using {} or :, value is not found, an IllegalStateException is thrown.

Specified by:

disablePathParams in interface PathAndQueryParamSetters

queryParam

public BlockingWebClientRequestPreparation queryParam(String name,
 Object value)

Description copied from interface: PathAndQueryParamSetters

Adds a query param for this message.

Specified by:

queryParam in interface PathAndQueryParamSetters

queryParams

public BlockingWebClientRequestPreparation queryParams(Iterable<? extends Map.Entry<? extends String,String>> queryParams)

Description copied from interface: PathAndQueryParamSetters

Adds multiple query params for this message.

Specified by:

queryParams in interface PathAndQueryParamSetters

cookie

public BlockingWebClientRequestPreparation cookie(Cookie cookie)

Description copied from interface: HttpMessageSetters

Sets a cookie for this message.

Specified by:

cookie in interface HttpMessageSetters

See Also:

• Cookie

cookies

public BlockingWebClientRequestPreparation cookies(Iterable<? extends Cookie> cookies)

Description copied from interface: HttpMessageSetters

Sets multiple cookies for this message.

Specified by:

cookies in interface HttpMessageSetters

See Also:

• Cookies

responseTimeout

public BlockingWebClientRequestPreparation responseTimeout(Duration responseTimeout)

Description copied from interface: RequestOptionsSetters

Schedules the response timeout that is triggered when the Response is not fully received within the specified Duration since the Response started or Request was fully sent. Duration.ZERO disables the limit.

Specified by:

responseTimeout in interface RequestOptionsSetters

responseTimeoutMillis

public BlockingWebClientRequestPreparation responseTimeoutMillis(long responseTimeoutMillis)

Description copied from interface: RequestOptionsSetters

Schedules the response timeout that is triggered when the Response is not fully received within the specified responseTimeoutMillis since the Response started or Request was fully sent. 0 disables the limit.

Specified by:

responseTimeoutMillis in interface RequestOptionsSetters

writeTimeout

public BlockingWebClientRequestPreparation writeTimeout(Duration writeTimeout)

Description copied from interface: RequestOptionsSetters

Sets the amount of time allowed until the initial write attempt of the current Request succeeds. Duration.ZERO disables the limit.

Specified by:

writeTimeout in interface RequestOptionsSetters

writeTimeoutMillis

public BlockingWebClientRequestPreparation writeTimeoutMillis(long writeTimeoutMillis)

Description copied from interface: RequestOptionsSetters

Sets the amount of time allowed until the initial write attempt of the current Request succeeds. 0 disables the limit.

Specified by:

writeTimeoutMillis in interface RequestOptionsSetters

maxResponseLength

public BlockingWebClientRequestPreparation maxResponseLength(long maxResponseLength)

Description copied from interface: RequestOptionsSetters

Sets the maximum allowed length of a server response in bytes. 0 disables the limit.

Specified by:

maxResponseLength in interface RequestOptionsSetters

requestAutoAbortDelay

public BlockingWebClientRequestPreparation requestAutoAbortDelay(Duration delay)

Description copied from interface: RequestOptionsSetters

Sets the amount of time to wait before aborting an HttpRequest when its corresponding HttpResponse is complete. This may be useful when you want to send additional data even after the response is complete. Specify Duration.ZERO to abort the HttpRequest immediately. Any negative value will not abort the request automatically. There is no delay by default.

Specified by:

requestAutoAbortDelay in interface RequestOptionsSetters

requestAutoAbortDelayMillis

public BlockingWebClientRequestPreparation requestAutoAbortDelayMillis(long delayMillis)

Description copied from interface: RequestOptionsSetters

Sets the amount of time in millis to wait before aborting an HttpRequest when its corresponding HttpResponse is complete. This may be useful when you want to send additional data even after the response is complete. Specify 0 to abort the HttpRequest immediately. Any negative value will not abort the request automatically. There is no delay by default.

Specified by:

requestAutoAbortDelayMillis in interface RequestOptionsSetters

attr

public <V> BlockingWebClientRequestPreparation attr(AttributeKey<V> key,
 @Nullable
 V value)

Description copied from interface: RequestOptionsSetters

Associates the specified value with the given AttributeKey in this request. If this context previously contained a mapping for the AttributeKey, the old value is replaced by the specified value.

Specified by:

attr in interface RequestOptionsSetters