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 Details

    • 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.

      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)