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 Summary

    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.

    - ### 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)`

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.