javax.ws.rs.client

## Interface Invocation

-     public interface Invocation

  A client request invocation. An invocation is a request that has been prepared and is ready for execution. Invocations provide a generic (command) interface that enables a separation of concerns between the creator and the submitter. In particular, the submitter does not need to know how the invocation was prepared, but only how it should be executed (synchronously or asynchronously) and when.
  Author:
    Marek Potociar
  See Also:
    `Invocation.Builder`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `Invocation.Builder` A client request invocation builder.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Response` | `invoke()` Synchronously invoke the request and receive a response back.
    `<T> T` | `invoke(Class<T> responseType)` Synchronously invoke the request and receive a response of the specified type back.
    `<T> T` | `invoke(GenericType<T> responseType)` Synchronously invoke the request and receive a response of the specified generic type back.
    `Invocation` | `property(String name, Object value)` Set a new property in the context of a request represented by this invocation.
    `Future<Response>` | `submit()` Submit the request for an asynchronous invocation and receive a future response back.
    `<T> Future<T>` | `submit(Class<T> responseType)` Submit the request for an asynchronous invocation and receive a future response of the specified type back.
    `<T> Future<T>` | `submit(GenericType<T> responseType)` Submit the request for an asynchronous invocation and receive a future response of the specified generic type back.
    `<T> Future<T>` | `submit(InvocationCallback<T> callback)` Submit the request for an asynchronous invocation and register an `InvocationCallback` to process the future result of the invocation.

- - ### Method Detail

    - #### property

          Invocation property(String name,
                            Object value)

      Set a new property in the context of a request represented by this invocation.

      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 invocation.
      See Also:
        `Invocation.Builder.property(String, Object)`

    - #### invoke

          Response invoke()

      Synchronously invoke the request and receive a response back.
      Returns:
        `response` object as a result of the request invocation.
      Throws:
        `ResponseProcessingException` - in case processing of a received HTTP response fails (e.g. in a filter or during conversion of the response entity data to an instance of a particular Java type).
        `ProcessingException` - in case the request processing or subsequent I/O operation fails.

    - #### invoke

          <T> T invoke(Class<T> responseType)

      Synchronously invoke the request and receive a response of the specified type back.
      Type Parameters:
        `T` - response type
      Parameters:
        `responseType` - Java type the response should be converted into.
      Returns:
        response object of the specified type as a result of the request invocation.
      Throws:
        `ResponseProcessingException` - in case processing of a received HTTP response fails (e.g. in a filter or during conversion of the response entity data to an instance of a particular Java type).
        `ProcessingException` - in case the request processing or subsequent I/O operation fails.
        `WebApplicationException` - in case the response status code of the response returned by the server is not `successful`.

    - #### invoke

          <T> T invoke(GenericType<T> responseType)

      Synchronously invoke the request and receive a response of the specified generic type back.
      Type Parameters:
        `T` - generic response type
      Parameters:
        `responseType` - type literal representing a generic Java type the response should be converted into.
      Returns:
        response object of the specified generic type as a result of the request invocation.
      Throws:
        `ResponseProcessingException` - in case processing of a received HTTP response fails (e.g. in a filter or during conversion of the response entity data to an instance of a particular Java type).
        `ProcessingException` - in case the request processing or subsequent I/O operation fails.
        `WebApplicationException` - in case the response status code of the response returned by the server is not `successful`.

    - #### submit

          Future<Response> submit()

      Submit the request for an asynchronous invocation and receive a future response back.

      Note that calling the `Future.get()` method on the returned `Future` instance may throw an `ExecutionException` that wraps a `ProcessingException` thrown in case of an invocation processing failure. In case a processing of a properly received response fails, the wrapped processing exception will be of `ResponseProcessingException` type and will contain the `Response` instance whose processing has failed.

      Returns:
        future `response` object as a result of the request invocation.

    - #### submit

          <T> Future<T> submit(Class<T> responseType)

      Submit the request for an asynchronous invocation and receive a future response of the specified type back.

      Note that calling the `Future.get()` method on the returned `Future` instance may throw an `ExecutionException` that wraps either a `ProcessingException` thrown in case of an invocation processing failure or a `WebApplicationException` or one of its subclasses thrown in case the received response status code is not `successful` and the specified response type is not `Response`. In case a processing of a properly received response fails, the wrapped processing exception will be of `ResponseProcessingException` type and will contain the `Response` instance whose processing has failed.

      Type Parameters:
        `T` - response type
      Parameters:
        `responseType` - Java type the response should be converted into.
      Returns:
        future response object of the specified type as a result of the request invocation.

    - #### submit

          <T> Future<T> submit(GenericType<T> responseType)

      Submit the request for an asynchronous invocation and receive a future response of the specified generic type back.

      Note that calling the `Future.get()` method on the returned `Future` instance may throw an `ExecutionException` that wraps either a `ProcessingException` thrown in case of an invocation processing failure or a `WebApplicationException` or one of its subclasses thrown in case the received response status code is not `successful` and the specified response type is not `Response`. In case a processing of a properly received response fails, the wrapped processing exception will be of `ResponseProcessingException` type and will contain the `Response` instance whose processing has failed.

      Type Parameters:
        `T` - generic response type
      Parameters:
        `responseType` - type literal representing a generic Java type the response should be converted into.
      Returns:
        future response object of the specified generic type as a result of the request invocation.

    - #### submit

          <T> Future<T> submit(InvocationCallback<T> callback)

      Submit the request for an asynchronous invocation and register an `InvocationCallback` to process the future result of the invocation.

      Note that calling the `Future.get()` method on the returned `Future` instance may throw an `ExecutionException` that wraps either a `ProcessingException` thrown in case of an invocation processing failure or a `WebApplicationException` or one of its subclasses thrown in case the received response status code is not `successful` and the generic type of the supplied response callback is not `Response`. In case a processing of a properly received response fails, the wrapped processing exception will be of `ResponseProcessingException` type and will contain the `Response` instance whose processing has failed.

      Type Parameters:
        `T` - response type
      Parameters:
        `callback` - invocation callback for asynchronous processing of the request invocation result.
      Returns:
        future response object of the specified type as a result of the request invocation.

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