Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.sun.jersey.api.client
Class Client

    java.lang.Object
      com.sun.jersey.api.client.filter.Filterable
          com.sun.jersey.api.client.Client

All Implemented Interfaces:
  ClientHandler

    public class Client

extends Filterable
implements ClientHandler

The main class for creating `WebResource` instances and configuring the properties of connections and requests.

`ClientFilter` instances may be added to the client for filtering requests and responses, including those of `WebResource` instances created from the client.

A client may be configured by passing a `ClientConfig` instance to the appropriate constructor.

Methods to create instances of `WebResource` are thread-safe. Methods that modify configuration and or filters are not guaranteed to be thread-safe.

The creation of a `Client` instance is an expensive operation and the instance may make use of and retain many resources. It is therefore recommended that a `Client` instance is reused for the creation of `WebResource` instances that require the same configuration settings.

A client may integrate with an IoC framework by passing a `IoCComponentProviderFactory` instance to the appropriate constructor.

Author:
  Paul.Sandoz@Sun.Com

Constructor Summary
`Client()` Create a new client instance.
`Client(ClientHandler root)` Create a new client instance.
`Client(ClientHandler root, ClientConfig config)` Create a new client instance with a client configuration.
`Client(ClientHandler root, ClientConfig config, IoCComponentProviderFactory provider)` Create a new instance with a client configuration and a component provider.

Method Summary
`AsyncWebResource` | `asyncResource(java.lang.String u)` Create an asynchronous Web resource from the client.
`AsyncWebResource` | `asyncResource(java.net.URI u)` Create an asynchronous Web resource from the client.
`
`<T> java.util.concurrent.Future<T>`
` | `asyncView(java.lang.String u, java.lang.Class<T> type)`
`
`<T> java.util.concurrent.Future<T>`
` | `asyncView(java.lang.String u, T t)`
`
`<T> java.util.concurrent.Future<T>`
` | `asyncView(java.net.URI uri, java.lang.Class<T> type)`
`
`<T> java.util.concurrent.Future<T>`
` | `asyncView(java.net.URI uri, T t)`
`AsyncViewResource` | `asyncViewResource(java.lang.String u)`
`AsyncViewResource` | `asyncViewResource(java.net.URI u)`
`static Client` | `create()` Create a default client.
`static Client` | `create(ClientConfig cc)` Create a default client with client configuration.
`static Client` | `create(ClientConfig cc, IoCComponentProviderFactory provider)` Create a default client with client configuration and component provider.
`void` | `destroy()` Destroy the client.
`protected void` | `finalize()` Defer to `destroy()`
`java.util.concurrent.ExecutorService` | `getExecutorService()` Get the `ExecutorService` for sending asynchronous HTTP requests when no underlying asynchronous HTTP implementation is utilized.
`MessageBodyWorkers` | `getMessageBodyWorkers()` Get the `MessageBodyWorkers` utilized by the client.
`java.util.Map<java.lang.String,java.lang.Object>` | `getProperties()` Get the mutable property bag.
`Providers` | `getProviders()` Get the `Providers` utilized by the client.
`
`<T> ViewProxy<T>`
` | `getViewProxy(java.lang.Class<T> c)`
`ClientResponse` | `handle(ClientRequest request)` Handle a HTTP request as a `ClientRequest` and return the HTTP response as a `ClientResponse`.
`void` | `inject(java.lang.Object o)` Inject client-side bindings on an instance.
`WebResource` | `resource(java.lang.String u)` Create a Web resource from the client.
`WebResource` | `resource(java.net.URI u)` Create a Web resource from the client.
`void` | `setChunkedEncodingSize(java.lang.Integer chunkSize)` Set the client to send request entities using chunked encoding with a particular chunk size.
`void` | `setConnectTimeout(java.lang.Integer interval)` Set the connect timeout interval, in milliseconds.
`void` | `setExecutorService(java.util.concurrent.ExecutorService es)` Set the `ExecutorService` for sending asynchronous HTTP requests when no underlying asynchronous HTTP implementation is utilized.
`void` | `setFollowRedirects(java.lang.Boolean redirect)` Set if redirection should be performed or not.
`void` | `setReadTimeout(java.lang.Integer interval)` Set the read timeout interval, in milliseconds.
`
`<T> T`
` | `view(java.lang.Class<T> c, ClientResponse response)`
`
`<T> T`
` | `view(java.lang.String u, java.lang.Class<T> type)`
`
`<T> T`
` | `view(java.lang.String u, T t)`
`
`<T> T`
` | `view(T t, ClientResponse response)`
`
`<T> T`
` | `view(java.net.URI uri, java.lang.Class<T> type)`
`
`<T> T`
` | `view(java.net.URI uri, T t)`
`ViewResource` | `viewResource(java.lang.String u)`
`ViewResource` | `viewResource(java.net.URI u)`

Methods inherited from class com.sun.jersey.api.client.filter.Filterable
`addFilter, getHeadHandler, isFilterPreset, removeAllFilters, removeFilter`

Methods inherited from class java.lang.Object
`clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### Client

    public Client()

  Create a new client instance.

### Client

    public Client(ClientHandler root)

  Create a new client instance.

  Parameters:
    `root` - the root client handler for dispatching a request and returning a response.

### Client

    public Client(ClientHandler root,
                  ClientConfig config)

  Create a new client instance with a client configuration.

  Parameters:
    `root` - the root client handler for dispatching a request and returning a response.
    `config` - the client configuration.

### Client

    public Client(ClientHandler root,
                  ClientConfig config,
                  IoCComponentProviderFactory provider)

  Create a new instance with a client configuration and a component provider.

  Parameters:
    `root` - the root client handler for dispatching a request and returning a response.
    `config` - the client configuration.
    `provider` - the IoC component provider factory.

Method Detail

### destroy

    public void destroy()

  Destroy the client. Any system resources associated with the client will be cleaned up.

  This method must be called when there are not responses pending otherwise undefined behavior will occur.

  The client must not be reused after this method is called otherwise undefined behavior will occur.

### finalize

    protected void finalize()
                     throws java.lang.Throwable

  Defer to `destroy()`

  Overrides:
    `finalize` in class `java.lang.Object`
  Throws:
    `java.lang.Throwable`

### getProviders

    public Providers getProviders()

  Get the `Providers` utilized by the client.

  Returns:
    the `Providers` utilized by the client.

### getMessageBodyWorkers

    public MessageBodyWorkers getMessageBodyWorkers()

  Get the `MessageBodyWorkers` utilized by the client.

  Returns:
    the `MessageBodyWorkers` utilized by the client.

### resource

    public WebResource resource(java.lang.String u)

  Create a Web resource from the client.

  Parameters:
    `u` - the URI of the resource.
  Returns:
    the Web resource.

### resource

    public WebResource resource(java.net.URI u)

  Create a Web resource from the client.

  Parameters:
    `u` - the URI of the resource.
  Returns:
    the Web resource.

### asyncResource

    public AsyncWebResource asyncResource(java.lang.String u)

  Create an asynchronous Web resource from the client.

  Parameters:
    `u` - the URI of the resource.
  Returns:
    the Web resource.

### asyncResource

    public AsyncWebResource asyncResource(java.net.URI u)

  Create an asynchronous Web resource from the client.

  Parameters:
    `u` - the URI of the resource.
  Returns:
    the Web resource.

### viewResource

    public ViewResource viewResource(java.lang.String u)

### viewResource

    public ViewResource viewResource(java.net.URI u)

### asyncViewResource

    public AsyncViewResource asyncViewResource(java.lang.String u)

### asyncViewResource

    public AsyncViewResource asyncViewResource(java.net.URI u)

### view

    public <T> T view(java.lang.String u,
                      java.lang.Class<T> type)

### view

    public <T> T view(java.net.URI uri,
                      java.lang.Class<T> type)

### view

    public <T> T view(java.lang.String u,
                      T t)

### view

    public <T> T view(java.net.URI uri,
                      T t)

### asyncView

    public <T> java.util.concurrent.Future<T> asyncView(java.lang.String u,
                                                        java.lang.Class<T> type)

### asyncView

    public <T> java.util.concurrent.Future<T> asyncView(java.net.URI uri,
                                                        java.lang.Class<T> type)

### asyncView

    public <T> java.util.concurrent.Future<T> asyncView(java.lang.String u,
                                                        T t)

### asyncView

    public <T> java.util.concurrent.Future<T> asyncView(java.net.URI uri,
                                                        T t)

### view

    public <T> T view(java.lang.Class<T> c,
                      ClientResponse response)

### view

    public <T> T view(T t,
                      ClientResponse response)

### getViewProxy

    public <T> ViewProxy<T> getViewProxy(java.lang.Class<T> c)

### setExecutorService

    public void setExecutorService(java.util.concurrent.ExecutorService es)

  Set the `ExecutorService` for sending asynchronous HTTP requests when no underlying asynchronous HTTP implementation is utilized.

  Parameters:
    `es` - the `ExecutorService`.
  Since:
    1.4

### getExecutorService

    public java.util.concurrent.ExecutorService getExecutorService()

  Get the `ExecutorService` for sending asynchronous HTTP requests when no underlying asynchronous HTTP implementation is utilized.

  By default the implementation returned from `Executors.newCachedThreadPool()` is utilized.

  Returns:
    the `ExecutorService`.
  Since:
    1.4

### getProperties

    public java.util.Map<java.lang.String,java.lang.Object> getProperties()

  Get the mutable property bag.

  Returns:
    the property bag.

### setFollowRedirects

    public void setFollowRedirects(java.lang.Boolean redirect)

  Set if redirection should be performed or not. This method is the functional equivalent to setting the property `ClientConfig.PROPERTY_FOLLOW_REDIRECTS` on the property bag returned from `getProperties()`

  Parameters:
    `redirect` - if true then the client will automatically redirect to the URI declared in 3xx responses.

### setReadTimeout

    public void setReadTimeout(java.lang.Integer interval)

  Set the read timeout interval, in milliseconds. This method is the functional equivalent to setting the property `ClientConfig.PROPERTY_READ_TIMEOUT` on the property bag returned from `getProperties()`

  Parameters:
    `interval` - the read timeout interval. If null or 0 then an interval of infinity is declared.

### setConnectTimeout

    public void setConnectTimeout(java.lang.Integer interval)

  Set the connect timeout interval, in milliseconds. This method is the functional equivalent to setting the property `ClientConfig.PROPERTY_CONNECT_TIMEOUT` on the property bag returned from `getProperties()`

  Parameters:
    `interval` - the connect timeout interval. If null or 0 then an interval of infinity is declared.

### setChunkedEncodingSize

    public void setChunkedEncodingSize(java.lang.Integer chunkSize)

  Set the client to send request entities using chunked encoding with a particular chunk size. This method is the functional equivalent to setting the property `ClientConfig.PROPERTY_CHUNKED_ENCODING_SIZE` on the property bag returned from `getProperties()`

  Parameters:
    `chunkSize` - the chunked encoding size. If <= 0 then the default size will be used. If null then chunked encoding will not be utilized.

### handle

    public ClientResponse handle(ClientRequest request)
                          throws ClientHandlerException

  Description copied from interface: `ClientHandler`
  Handle a HTTP request as a `ClientRequest` and return the HTTP response as a `ClientResponse`.

  Specified by:
    `handle` in interface `ClientHandler`
  Parameters:
    `request` - the HTTP request.
  Returns:
    the HTTP response.
  Throws:
    `ClientHandlerException` - if the client handler fails to process the request or response.

### inject

    public void inject(java.lang.Object o)

  Inject client-side bindings on an instance.

  Parameters:
    `o` - the instance to inject on.

### create

    public static Client create()

  Create a default client.

  Returns:
    a default client.

### create

    public static Client create(ClientConfig cc)

  Create a default client with client configuration.

  Parameters:
    `cc` - the client configuration.
  Returns:
    a default client.

### create

    public static Client create(ClientConfig cc,
                                IoCComponentProviderFactory provider)

  Create a default client with client configuration and component provider.

  Parameters:
    `cc` - the client configuration.
    `provider` - the IoC component provider factory.
  Returns:
    a default client.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2011 Oracle Corporation. All Rights Reserved.