javax.ws.rs.client

Interface Invocation.Builder

All Superinterfaces:

SyncInvoker

Enclosing interface:

Invocation

public static interface Invocation.Builder
extends SyncInvoker

A client request invocation builder. The builder, obtained via a call to one of the request(...) methods on a resource target, provides methods for preparing a client request invocation. Once the request is prepared the invocation builder can be either used to build an Invocation with a generic execution interface:

   Client client = ClientBuilder.newClient();
   WebTarget resourceTarget = client.target("http://examples.jaxrs.com/");

   // Build a HTTP GET request that accepts "text/plain" response type
   // and contains a custom HTTP header entry "Foo: bar".
   Invocation invocation = resourceTarget.request("text/plain")
           .header("Foo", "bar").buildGet();

   // Invoke the request using generic interface
   String response = invocation.invoke(String.class);
 

Alternatively, one of the inherited synchronous invocation methods can be used to invoke the prepared request and return the server response in a single step, e.g.:

   Client client = ClientBuilder.newClient();
   WebTarget resourceTarget = client.target("http://examples.jaxrs.com/");

   // Build and invoke the get request in a single step
   String response = resourceTarget.request("text/plain")
           .header("Foo", "bar").get(String.class);
 

Once the request is fully prepared for invoking, switching to an asynchronous invocation mode is possible by calling the async() method on the builder, e.g.:

   Client client = ClientBuilder.newClient();
   WebTarget resourceTarget = client.target("http://examples.jaxrs.com/");

   // Build and invoke the get request asynchronously in a single step
   Future response = resourceTarget.request("text/plain")
           .header("Foo", "bar").async().get(String.class);
 

Method Summary

Modifier and Type	Method and Description
Invocation.Builder	accept(MediaType... mediaTypes) Add the accepted response media types.
Invocation.Builder	accept(String... mediaTypes) Add the accepted response media types.
Invocation.Builder	acceptEncoding(String... encodings) Add acceptable encodings.
Invocation.Builder	acceptLanguage(Locale... locales) Add acceptable languages.
Invocation.Builder	acceptLanguage(String... locales) Add acceptable languages.
AsyncInvoker	async() Access the asynchronous uniform request invocation interface to asynchronously invoke the built request.
Invocation	build(String method) Build a request invocation using an arbitrary request method name.
Invocation	build(String method, Entity<?> entity) Build a request invocation using an arbitrary request method name and request entity.
Invocation	buildDelete() Build a DELETE request invocation.
Invocation	buildGet() Build a GET request invocation.
Invocation	buildPost(Entity<?> entity) Build a POST request invocation.
Invocation	buildPut(Entity<?> entity) Build a PUT request invocation.
Invocation.Builder	cacheControl(CacheControl cacheControl) Set the cache control data of the message.
Invocation.Builder	cookie(Cookie cookie) Add a cookie to be set.
Invocation.Builder	cookie(String name, String value) Add a cookie to be set.
Invocation.Builder	header(String name, Object value) Add an arbitrary header.
Invocation.Builder	headers(MultivaluedMap<String,Object> headers) Replaces all existing headers with the newly supplied headers.
NioInvoker	nio() Access the NIO uniform request invocation interface to use non-blocking I/O to read/write entities.
Invocation.Builder	property(String name, Object value) Set a new property in the context of a request represented by this invocation builder.
CompletionStageRxInvoker	rx() Access the default reactive invoker based on CompletionStage.
<T extends RxInvoker> T	rx(Class<T> clazz) Access a reactive invoker based on an implementation of RxInvoker provided.
<T extends RxInvoker> T	rx(Class<T> clazz, ExecutorService executorService) Access a reactive invoker based on an implementation of RxInvoker and the executor service provided.
CompletionStageRxInvoker	rx(ExecutorService executorService) Access the default reactive invoker based on CompletionStage and provide an ExecutorService for it.

Methods inherited from interface javax.ws.rs.client.SyncInvoker

delete, delete, delete, get, get, get, head, method, method, method, method, method, method, options, options, options, post, post, post, put, put, put, trace, trace, trace

Method Detail

build

Invocation build(String method)

Build a request invocation using an arbitrary request method name.

Parameters:

method - request method name.

Returns:

invocation encapsulating the built request.

build

Invocation build(String method,
                 Entity<?> entity)

Build a request invocation using an arbitrary request method name and request entity.

Parameters:

method - request method name.

entity - request entity, including it's full Variant information. Any variant-related HTTP headers previously set (namely Content-Type, Content-Language and Content-Encoding) will be overwritten using the entity variant information.

Returns:

invocation encapsulating the built request.

buildGet

Invocation buildGet()

Build a GET request invocation.

Returns:

invocation encapsulating the built GET request.

buildDelete

Invocation buildDelete()

Build a DELETE request invocation.

Returns:

invocation encapsulating the built DELETE request.

buildPost

Invocation buildPost(Entity<?> entity)

Build a POST request invocation.

Parameters:

entity - request entity, including it's full Variant information. Any variant-related HTTP headers previously set (namely Content-Type, Content-Language and Content-Encoding) will be overwritten using the entity variant information.

Returns:

invocation encapsulating the built POST request.

buildPut

Invocation buildPut(Entity<?> entity)

Build a PUT request invocation.

Parameters:

entity - request entity, including it's full Variant information. Any variant-related HTTP headers previously set (namely Content-Type, Content-Language and Content-Encoding) will be overwritten using the entity variant information.

Returns:

invocation encapsulating the built PUT request.

async

AsyncInvoker async()

Access the asynchronous uniform request invocation interface to asynchronously invoke the built request.

Returns:

asynchronous uniform request invocation interface.

accept

Invocation.Builder accept(String... mediaTypes)

Add the accepted response media types.

Parameters:

mediaTypes - accepted response media types.

Returns:

the updated builder.

accept

Invocation.Builder accept(MediaType... mediaTypes)

Add the accepted response media types.

Parameters:

mediaTypes - accepted response media types.

Returns:

the updated builder.

acceptLanguage

Invocation.Builder acceptLanguage(Locale... locales)

Add acceptable languages.

Parameters:

locales - an array of the acceptable languages.

Returns:

the updated builder.

acceptLanguage

Invocation.Builder acceptLanguage(String... locales)

Add acceptable languages.

Parameters:

locales - an array of the acceptable languages.

Returns:

the updated builder.

acceptEncoding

Invocation.Builder acceptEncoding(String... encodings)

Add acceptable encodings.

Parameters:

encodings - an array of the acceptable encodings.

Returns:

the updated builder.

cookie

Invocation.Builder cookie(Cookie cookie)

Add a cookie to be set.

Parameters:

cookie - to be set.

Returns:

the updated builder.

cookie

Invocation.Builder cookie(String name,
                          String value)

Add a cookie to be set.

Parameters:

name - the name of the cookie.

value - the value of the cookie.

Returns:

the updated builder.

cacheControl

Invocation.Builder cacheControl(CacheControl cacheControl)

Set the cache control data of the message.

Parameters:

cacheControl - the cache control directives, if null any existing cache control directives will be removed.

Returns:

the updated builder.

header

Invocation.Builder header(String name,
                          Object value)

Add an arbitrary header.

Parameters:

name - the name of the header

value - the value of the header, the header will be serialized using a RuntimeDelegate.HeaderDelegate if one is available via RuntimeDelegate.createHeaderDelegate(java.lang.Class) for the class of value or using its toString method if a header delegate is not available. If value is null then all current headers of the same name will be removed.

Returns:

the updated builder.

headers

Invocation.Builder headers(MultivaluedMap<String,Object> headers)

Replaces all existing headers with the newly supplied headers.

Parameters:

headers - new headers to be set, if null all existing headers will be removed.

Returns:

the updated builder.

property

Invocation.Builder property(String name,
                            Object value)

Set a new property in the context of a request represented by this invocation builder.

The property is available for a later retrieval via ClientRequestContext.getProperty(String) or InterceptorContext.getProperty(String). If a property with a given name is already set in the request context, the existing value of the property will be updated. Setting a null value into a property effectively removes the property from the request property bag.

Parameters:

name - property name.

value - (new) property value. null value removes the property with the given name.

Returns:

the updated builder.

See Also:

Invocation.property(String, Object)

rx

CompletionStageRxInvoker rx()

Access the default reactive invoker based on CompletionStage. Equivalent to calling rx(CompletionStageRxInvoker.class).

Returns:

default reactive invoker instance.

Since:

2.1

See Also:

rx(Class)

rx

CompletionStageRxInvoker rx(ExecutorService executorService)

Access the default reactive invoker based on CompletionStage and provide an ExecutorService for it. Note that not all executor services are supported in all runtime environments. For example, only executor services provided by JSR 236 should be supported in a Java EE environment.

Parameters:

executorService - executor service to use.

Returns:

default reactive invoker instance.

Throws:

IllegalArgumentException - if the executor service provided is not supported by the runtime environment.

Since:

2.1

See Also:

rx()

rx

<T extends RxInvoker> T rx(Class<T> clazz)

Access a reactive invoker based on an implementation of RxInvoker provided. This method is an extension point for JAX-RS implementations to support other types representing asynchronous computations.

Parameters:

clazz - implementation of reactive invoker.

Returns:

reactive invoker instance.

Since:

2.1

See Also:

rx(Class, ExecutorService)

rx

<T extends RxInvoker> T rx(Class<T> clazz,
                           ExecutorService executorService)

Access a reactive invoker based on an implementation of RxInvoker and the executor service provided. This method is an extension point for JAX-RS implementations to support other types representing asynchronous computations. Note that not all executor services are supported in all runtime environments. For example, only executor services provided by JSR 236 should be supported in a Java EE environment.

Parameters:

clazz - implementation of reactive invoker.

executorService - executor service to use.

Returns:

default reactive invoker instance.

Throws:

IllegalArgumentException - if the executor service provided is not supported by the runtime environment.

Since:

2.1

See Also:

rx()

nio

NioInvoker nio()

Access the NIO uniform request invocation interface to use non-blocking I/O to read/write entities.

Returns:

NIO uniform request invocation interface.