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

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

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