Invocation.Builder (Java(TM) EE 8 Specification APIs)

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

All Methods Instance Methods Abstract Methods
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.
`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 a `RxInvoker` subclass provider.

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.
    
    Returns:
    
    default reactive invoker instance.
    
    Since:
    
    2.1
    
    See Also:
    
    rx(Class)
  - rx
```
<T extends RxInvoker> T rx(Class<T> clazz)
```
    Access a reactive invoker based on a RxInvoker subclass provider. Note that corresponding RxInvokerProvider must be registered in the client runtime.
    This method is an extension point for JAX-RS implementations to support other types representing asynchronous computations.
    
    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)

Interface Invocation.Builder

Method Summary

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

Method Detail

build

build

buildGet

buildDelete

buildPost

buildPut

async

accept

accept

acceptLanguage

acceptLanguage

acceptEncoding

cookie

cookie

cacheControl

header

headers

property

rx

rx