Package jakarta.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<String> response = resourceTarget.request("text/plain") .header("Foo", "bar").async().get(String.class);
-
Method Summary
Modifier and Type Method 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(String... locales)
Add acceptable languages.Invocation.Builder
acceptLanguage(Locale... 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.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 onCompletionStage
.<T extends RxInvoker>
Trx(Class<T> clazz)
Access a reactive invoker based on aRxInvoker
subclass provider.
-
Method Details
-
build
Build a request invocation using an arbitrary request method name.- Parameters:
method
- request method name.- Returns:
- invocation encapsulating the built request.
-
build
Build a request invocation using an arbitrary request method name and request entity.- Parameters:
method
- request method name.entity
- request entity, including it's fullVariant
information. Any variant-related HTTP headers previously set (namelyContent-Type
,Content-Language
andContent-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
Build a POST request invocation.- Parameters:
entity
- request entity, including it's fullVariant
information. Any variant-related HTTP headers previously set (namelyContent-Type
,Content-Language
andContent-Encoding
) will be overwritten using the entity variant information.- Returns:
- invocation encapsulating the built POST request.
-
buildPut
Build a PUT request invocation.- Parameters:
entity
- request entity, including it's fullVariant
information. Any variant-related HTTP headers previously set (namelyContent-Type
,Content-Language
andContent-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
Add the accepted response media types.- Parameters:
mediaTypes
- accepted response media types.- Returns:
- the updated builder.
-
accept
Add the accepted response media types.- Parameters:
mediaTypes
- accepted response media types.- Returns:
- the updated builder.
-
acceptLanguage
Add acceptable languages.- Parameters:
locales
- an array of the acceptable languages.- Returns:
- the updated builder.
-
acceptLanguage
Add acceptable languages.- Parameters:
locales
- an array of the acceptable languages.- Returns:
- the updated builder.
-
acceptEncoding
Add acceptable encodings.- Parameters:
encodings
- an array of the acceptable encodings.- Returns:
- the updated builder.
-
cookie
Add a cookie to be set.- Parameters:
cookie
- to be set.- Returns:
- the updated builder.
-
cookie
Add a cookie to be set.- Parameters:
name
- the name of the cookie.value
- the value of the cookie.- Returns:
- the updated builder.
-
cacheControl
Set the cache control data of the message.- Parameters:
cacheControl
- the cache control directives, ifnull
any existing cache control directives will be removed.- Returns:
- the updated builder.
-
header
Add an arbitrary header.- Parameters:
name
- the name of the headervalue
- the value of the header, the header will be serialized using aRuntimeDelegate.HeaderDelegate
if one is available viaRuntimeDelegate.createHeaderDelegate(java.lang.Class)
for the class ofvalue
or using itstoString
method if a header delegate is not available. Ifvalue
isnull
then all current headers of the same name will be removed.- Returns:
- the updated builder.
-
headers
Replaces all existing headers with the newly supplied headers.- Parameters:
headers
- new headers to be set, ifnull
all existing headers will be removed.- Returns:
- the updated builder.
-
property
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)
orInterceptorContext.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 anull
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
Access the default reactive invoker based onCompletionStage
.- Returns:
- default reactive invoker instance.
- Since:
- 2.1
- See Also:
rx(Class)
-
rx
Access a reactive invoker based on aRxInvoker
subclass provider. Note that correspondingRxInvokerProvider
must be registered in the client runtime.This method is an extension point for JAX-RS implementations to support other types representing asynchronous computations.
- Type Parameters:
T
- generic invoker type.- Parameters:
clazz
-RxInvoker
subclass.- Returns:
- reactive invoker instance.
- Throws:
IllegalStateException
- when provider for given class is not registered.- Since:
- 2.1
- See Also:
Configurable.register(Class)
-