Package 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 Detail

      • build

        Invocation build​(java.lang.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​(java.lang.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​(java.lang.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​(java.util.Locale... locales)
        Add acceptable languages.
        Parameters:
        locales - an array of the acceptable languages.
        Returns:
        the updated builder.

      • acceptLanguage

        Invocation.Builder acceptLanguage​(java.lang.String... locales)
        Add acceptable languages.
        Parameters:
        locales - an array of the acceptable languages.
        Returns:
        the updated builder.

      • acceptEncoding

        Invocation.Builder acceptEncoding​(java.lang.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​(java.lang.String name,
                          java.lang.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​(java.lang.String name,
                          java.lang.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<java.lang.String,java.lang.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​(java.lang.String name,
                            java.lang.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​(java.lang.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:
        java.lang.IllegalStateException - when provider for given class is not registered.
        Since:
        2.1
        See Also:
        Configurable.register(Class)