org.jboss.resteasy.client.jaxrs

Class ResteasyClientBuilder

java.lang.Object

javax.ws.rs.client.ClientBuilder

org.jboss.resteasy.client.jaxrs.ResteasyClientBuilder

All Implemented Interfaces:

Configurable<ClientBuilder>

public class ResteasyClientBuilder
extends ClientBuilder

Abstraction for creating Clients. Allows SSL configuration. Uses Apache Http Client under the covers. If used with other ClientHttpEngines though, all configuration options are ignored.

Version:

$Revision: 1 $

Author:

Bill Burke

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	ResteasyClientBuilder.HostnameVerificationPolicy

Field Summary

Fields

Modifier and Type	Field and Description
protected ExecutorService	asyncExecutor
protected KeyStore	clientKeyStore
protected String	clientPrivateKeyPassword
protected int	connectionCheckoutTimeoutMs
protected int	connectionPoolSize
protected long	connectionTTL
protected TimeUnit	connectionTTLUnit
protected org.apache.http.HttpHost	defaultProxy
protected boolean	disableTrustManager
protected long	establishConnectionTimeout
protected TimeUnit	establishConnectionTimeoutUnits
protected ClientHttpEngine	httpEngine
protected int	maxPooledPerRoute
protected ResteasyClientBuilder.HostnameVerificationPolicy	policy
protected Map<String,Object>	properties
protected ResteasyProviderFactory	providerFactory
protected int	responseBufferSize
protected long	socketTimeout
protected TimeUnit	socketTimeoutUnits
protected SSLContext	sslContext
protected KeyStore	truststore
protected HostnameVerifier	verifier

Fields inherited from class javax.ws.rs.client.ClientBuilder

JAXRS_DEFAULT_CLIENT_BUILDER_PROPERTY

Constructor Summary

Constructors

Constructor and Description
ResteasyClientBuilder()

Method Summary

Methods

Modifier and Type	Method and Description
ResteasyClientBuilder	asyncExecutor(ExecutorService asyncExecutor) Executor to use to run AsyncInvoker invocations
ResteasyClient	build() Build a new client instance using all the configuration previously specified in this client builder.
ResteasyClientBuilder	connectionCheckoutTimeout(long timeout, TimeUnit unit) If connection pooling is enabled, how long will we wait to get a connection?
ResteasyClientBuilder	connectionPoolSize(int connectionPoolSize) Number of connections allowed to pool
ResteasyClientBuilder	connectionTTL(long ttl, TimeUnit unit) If there is a connection pool, set the time to live in the pool.
ResteasyClientBuilder	defaultProxy(String hostname) Specify a default proxy.
ResteasyClientBuilder	defaultProxy(String hostname, int port) Specify a default proxy host and port.
ResteasyClientBuilder	defaultProxy(String hostname, int port, String scheme) Specify default proxy.
ResteasyClientBuilder	disableTrustManager() Disable trust management and hostname verification.
ResteasyClientBuilder	establishConnectionTimeout(long timeout, TimeUnit unit) When trying to make an initial socket connection, what is the timeout?
Configuration	getConfiguration() Get a live view of an internal configuration state of this configurable instance.
protected ResteasyProviderFactory	getProviderFactory()
ResteasyClientBuilder	hostnameVerification(ResteasyClientBuilder.HostnameVerificationPolicy policy) SSL policy used to verify hostnames
ResteasyClientBuilder	hostnameVerifier(HostnameVerifier verifier) Set the hostname verifier to be used by the client to verify the endpoint's hostname against it's identification information.
ResteasyClientBuilder	httpEngine(ClientHttpEngine httpEngine) Negates all ssl and connection specific configuration
protected ClientHttpEngine	initDefaultEngine()
ResteasyClientBuilder	keyStore(KeyStore keyStore, char[] password) Set the client-side key store.
ResteasyClientBuilder	keyStore(KeyStore keyStore, String password) Set the client-side key store.
ResteasyClientBuilder	maxPooledPerRoute(int maxPooledPerRoute) If connection pooling enabled, how many connections to pool per url?
ResteasyClientBuilder	property(String name, Object value) Set the new configuration property, if already set, the existing value of the property will be updated.
ResteasyClientBuilder	providerFactory(ResteasyProviderFactory providerFactory) Changing the providerFactory will wipe clean any registered components or properties.
ResteasyClientBuilder	register(Class<?> componentClass) Register a class of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.
ResteasyClientBuilder	register(Class<?> componentClass, Class<?>... contracts) Register a class of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.
ResteasyClientBuilder	register(Class<?> componentClass, int priority) Register a class of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.
ResteasyClientBuilder	register(Class<?> componentClass, Map<Class<?>,Integer> contracts) Register a class of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.
ResteasyClientBuilder	register(Object component) Register an instance of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.
ResteasyClientBuilder	register(Object component, Class<?>... contracts) Register an instance of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.
ResteasyClientBuilder	register(Object component, int priority) Register an instance of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.
ResteasyClientBuilder	register(Object component, Map<Class<?>,Integer> contracts) Register an instance of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.
ResteasyClientBuilder	responseBufferSize(int size) Response stream is wrapped in a BufferedInputStream.
ResteasyClientBuilder	socketTimeout(long timeout, TimeUnit unit) Socket inactivity timeout
ResteasyClientBuilder	sslContext(SSLContext sslContext) Set the SSL context that will be used when creating secured transport connections to server endpoints from web targets created by the client instance that is using this SSL context.
ResteasyClientBuilder	trustStore(KeyStore truststore) Set the client-side trust store.
ResteasyClientBuilder	withConfig(Configuration config) Set the internal configuration state to an externally provided configuration state.

Methods inherited from class javax.ws.rs.client.ClientBuilder

newBuilder, newClient, newClient

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

truststore

protected KeyStore truststore

clientKeyStore

protected KeyStore clientKeyStore

clientPrivateKeyPassword

protected String clientPrivateKeyPassword

disableTrustManager

protected boolean disableTrustManager

policy

protected ResteasyClientBuilder.HostnameVerificationPolicy policy

providerFactory

protected ResteasyProviderFactory providerFactory

asyncExecutor

protected ExecutorService asyncExecutor

sslContext

protected SSLContext sslContext

properties

protected Map<String,Object> properties

httpEngine

protected ClientHttpEngine httpEngine

connectionPoolSize

protected int connectionPoolSize

maxPooledPerRoute

protected int maxPooledPerRoute

connectionTTL

protected long connectionTTL

connectionTTLUnit

protected TimeUnit connectionTTLUnit

socketTimeout

protected long socketTimeout

socketTimeoutUnits

protected TimeUnit socketTimeoutUnits

establishConnectionTimeout

protected long establishConnectionTimeout

establishConnectionTimeoutUnits

protected TimeUnit establishConnectionTimeoutUnits

connectionCheckoutTimeoutMs

protected int connectionCheckoutTimeoutMs

verifier

protected HostnameVerifier verifier

defaultProxy

protected org.apache.http.HttpHost defaultProxy

responseBufferSize

protected int responseBufferSize

Constructor Detail

ResteasyClientBuilder

public ResteasyClientBuilder()

Method Detail

providerFactory

public ResteasyClientBuilder providerFactory(ResteasyProviderFactory providerFactory)

Changing the providerFactory will wipe clean any registered components or properties.

Parameters:

providerFactory -

Returns:

asyncExecutor

public ResteasyClientBuilder asyncExecutor(ExecutorService asyncExecutor)

Executor to use to run AsyncInvoker invocations

Parameters:

asyncExecutor -

Returns:

connectionTTL

public ResteasyClientBuilder connectionTTL(long ttl,
                                  TimeUnit unit)

If there is a connection pool, set the time to live in the pool.

Parameters:

ttl -

unit -

Returns:

socketTimeout

public ResteasyClientBuilder socketTimeout(long timeout,
                                  TimeUnit unit)

Socket inactivity timeout

Parameters:

timeout -

unit -

Returns:

establishConnectionTimeout

public ResteasyClientBuilder establishConnectionTimeout(long timeout,
                                               TimeUnit unit)

When trying to make an initial socket connection, what is the timeout?

Parameters:

timeout -

unit -

Returns:

maxPooledPerRoute

public ResteasyClientBuilder maxPooledPerRoute(int maxPooledPerRoute)

If connection pooling enabled, how many connections to pool per url?

Parameters:

maxPooledPerRoute -

Returns:

connectionCheckoutTimeout

public ResteasyClientBuilder connectionCheckoutTimeout(long timeout,
                                              TimeUnit unit)

If connection pooling is enabled, how long will we wait to get a connection?

Parameters:

timeout - the timeout

unit - the units the timeout is in

Returns:

this builder

connectionPoolSize

public ResteasyClientBuilder connectionPoolSize(int connectionPoolSize)

Number of connections allowed to pool

Parameters:

connectionPoolSize -

Returns:

responseBufferSize

public ResteasyClientBuilder responseBufferSize(int size)

Response stream is wrapped in a BufferedInputStream. Default is 8192. Value of 0 will not wrap it. Value of -1 will use a SelfExpandingBufferedInputStream

Parameters:

size -

Returns:

disableTrustManager

public ResteasyClientBuilder disableTrustManager()

Disable trust management and hostname verification. NOTE this is a security hole, so only set this option if you cannot or do not want to verify the identity of the host you are communicating with.

hostnameVerification

public ResteasyClientBuilder hostnameVerification(ResteasyClientBuilder.HostnameVerificationPolicy policy)

SSL policy used to verify hostnames

Parameters:

policy -

Returns:

httpEngine

public ResteasyClientBuilder httpEngine(ClientHttpEngine httpEngine)

Negates all ssl and connection specific configuration

Parameters:

httpEngine -

Returns:

sslContext

public ResteasyClientBuilder sslContext(SSLContext sslContext)

Description copied from class: ClientBuilder

Set the SSL context that will be used when creating secured transport connections to server endpoints from web targets created by the client instance that is using this SSL context. The SSL context is expected to have all the security infrastructure initialized, including the key and trust managers.

Setting a SSL context instance resets any key store or trust store values previously specified.

Specified by:

sslContext in class ClientBuilder

Parameters:

sslContext - secure socket protocol implementation which acts as a factory for secure socket factories or SSL engines. Must not be null.

Returns:

an updated client builder instance.

See Also:

ClientBuilder.keyStore(java.security.KeyStore, char[]), ClientBuilder.keyStore(java.security.KeyStore, String), ClientBuilder.trustStore(java.security.KeyStore)

trustStore

public ResteasyClientBuilder trustStore(KeyStore truststore)

Description copied from class: ClientBuilder

Set the client-side trust store. Trust store is expected to contain certificates from other parties the client is you expect to communicate with, or from Certificate Authorities that are trusted to identify other parties.

Setting a trust store instance resets any SSL context instance value previously specified.

In case a custom trust store or custom SSL context is not specified, the trust management will be configured to use the default Java runtime settings.

Specified by:

trustStore in class ClientBuilder

Parameters:

truststore - client-side trust store. Must not be null.

Returns:

an updated client builder instance.

See Also:

ClientBuilder.sslContext(javax.net.ssl.SSLContext), ClientBuilder.keyStore(java.security.KeyStore, char[]), ClientBuilder.keyStore(java.security.KeyStore, String)

keyStore

public ResteasyClientBuilder keyStore(KeyStore keyStore,
                             String password)

Description copied from class: ClientBuilder

Set the client-side key store. Key store contains client's private keys, and the certificates with their corresponding public keys.

Setting a key store instance resets any SSL context instance value previously specified.

Note that for improved security of working with password data and avoid storing passwords in Java string objects, the ClientBuilder.keyStore(java.security.KeyStore, char[]) version of the method can be utilized. Also note that a custom key store is only required if you want to enable a custom setup of a 2-way SSL connections (client certificate authentication).

Overrides:

keyStore in class ClientBuilder

Parameters:

keyStore - client-side key store. Must not be null.

password - client key password. Must not be null.

Returns:

an updated client builder instance.

See Also:

ClientBuilder.sslContext(javax.net.ssl.SSLContext), ClientBuilder.keyStore(java.security.KeyStore, char[]), ClientBuilder.trustStore(java.security.KeyStore)

keyStore

public ResteasyClientBuilder keyStore(KeyStore keyStore,
                             char[] password)

Description copied from class: ClientBuilder

Set the client-side key store. Key store contains client's private keys, and the certificates with their corresponding public keys.

Setting a key store instance resets any SSL context instance value previously specified.

Note that a custom key store is only required if you want to enable a custom setup of a 2-way SSL connections (client certificate authentication).

Specified by:

keyStore in class ClientBuilder

Parameters:

keyStore - client-side key store. Must not be null.

password - client key password. Must not be null.

Returns:

an updated client builder instance.

See Also:

ClientBuilder.sslContext(javax.net.ssl.SSLContext), ClientBuilder.keyStore(java.security.KeyStore, String), ClientBuilder.trustStore(java.security.KeyStore)

property

public ResteasyClientBuilder property(String name,
                             Object value)

Description copied from interface: Configurable

Set the new configuration property, if already set, the existing value of the property will be updated. Setting a null value into a property effectively removes the property from the property bag.

Parameters:

name - property name.

value - (new) property value. null value removes the property with the given name.

Returns:

the updated configurable instance.

defaultProxy

public ResteasyClientBuilder defaultProxy(String hostname)

Specify a default proxy. Default port and schema will be used

Parameters:

hostname -

Returns:

defaultProxy

public ResteasyClientBuilder defaultProxy(String hostname,
                                 int port)

Specify a default proxy host and port. Default schema will be used

Parameters:

hostname -

port -

Returns:

defaultProxy

public ResteasyClientBuilder defaultProxy(String hostname,
                                 int port,
                                 String scheme)

Specify default proxy.

Parameters:

hostname -

port -

scheme -

Returns:

getProviderFactory

protected ResteasyProviderFactory getProviderFactory()

build

public ResteasyClient build()

Description copied from class: ClientBuilder

Build a new client instance using all the configuration previously specified in this client builder.

Specified by:

build in class ClientBuilder

Returns:

a new client instance.

initDefaultEngine

protected ClientHttpEngine initDefaultEngine()

hostnameVerifier

public ResteasyClientBuilder hostnameVerifier(HostnameVerifier verifier)

Description copied from class: ClientBuilder

Set the hostname verifier to be used by the client to verify the endpoint's hostname against it's identification information.

Specified by:

hostnameVerifier in class ClientBuilder

Parameters:

verifier - hostname verifier.

Returns:

an updated client builder instance.

getConfiguration

public Configuration getConfiguration()

Description copied from interface: Configurable

Get a live view of an internal configuration state of this configurable instance. Any changes made using methods of this Configurable instance will be reflected in the returned Configuration instance.

The returned Configuration instance and the collection data it provides are not thread-safe wrt. modification made using methods on the parent configurable object.

Returns:

configuration live view of the internal configuration state.

register

public ResteasyClientBuilder register(Class<?> componentClass)

Description copied from interface: Configurable

Register a class of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context. Implementations SHOULD warn about and ignore registrations that do not conform to the requirements of supported JAX-RS component types in the given configurable context. Any subsequent registration attempts for a component type, for which a class or instance-based registration already exists in the system MUST be rejected by the JAX-RS implementation and a warning SHOULD be raised to inform the user about the rejected registration. The registered JAX-RS component class is registered as a contract provider of all the recognized JAX-RS or implementation-specific extension contracts including meta-provider contracts, such as Feature or DynamicFeature.

As opposed to component instances registered via Configurable.register(Object) method, the lifecycle of components registered using this class-based register(...) method is fully managed by the JAX-RS implementation or any underlying IoC container supported by the implementation.

Parameters:

componentClass - JAX-RS component class to be configured in the scope of this configurable context.

Returns:

the updated configurable context.

register

public ResteasyClientBuilder register(Class<?> componentClass,
                             int priority)

Description copied from interface: Configurable

Register a class of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.

This registration method provides the same functionality as Configurable.register(Class) except that any priority specified on the registered JAX-RS component class via javax.annotation.Priority annotation is overridden with the supplied priority value.

Note that in case the priority is not applicable to a particular provider contract implemented by the class of the registered component, the supplied priority value will be ignored for that contract.

Parameters:

componentClass - JAX-RS component class to be configured in the scope of this configurable context.

priority - the overriding priority for the registered component and all the provider contracts the component implements.

Returns:

the updated configurable context.

register

public ResteasyClientBuilder register(Class<?> componentClass,
                             Class<?>... contracts)

Description copied from interface: Configurable

Register a class of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.

This registration method provides the same functionality as Configurable.register(Class) except the JAX-RS component class is only registered as a provider of the listed extension provider or meta-provider contracts. All explicitly enumerated contract types must represent a class or an interface implemented or extended by the registered component. Contracts that are not assignable from the registered component class MUST be ignored and implementations SHOULD raise a warning to inform users about the ignored contract(s).

Parameters:

componentClass - JAX-RS component class to be configured in the scope of this configurable context.

contracts - the specific extension provider or meta-provider contracts implemented by the component for which the component should be registered. Implementations MUST ignore attempts to register a component class for an empty or null collection of contracts via this method and SHOULD raise a warning about such event.

Returns:

the updated configurable context.

register

public ResteasyClientBuilder register(Class<?> componentClass,
                             Map<Class<?>,Integer> contracts)

Description copied from interface: Configurable

Register a class of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.

This registration method provides same functionality as Configurable.register(Class, Class[]) except that any priority specified on the registered JAX-RS component class via javax.annotation.Priority annotation is overridden for each extension provider contract type separately with an integer priority value specified as a value in the supplied map of [contract type, priority] pairs.

Note that in case a priority is not applicable to a provider contract registered for the JAX-RS component, the supplied priority value is ignored for such contract.

Parameters:

componentClass - JAX-RS component class to be configured in the scope of this configurable context.

contracts - map of the specific extension provider and meta-provider contracts and their associated priorities for which the JAX-RS component is registered. All contracts in the map must represent a class or an interface implemented or extended by the JAX-RS component. Contracts that are not assignable from the registered component class MUST be ignored and implementations SHOULD raise a warning to inform users about the ignored contract(s).

Returns:

the updated configurable context.

register

public ResteasyClientBuilder register(Object component)

Description copied from interface: Configurable

Register an instance of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context. Implementations SHOULD warn about and ignore registrations that do not conform to the requirements of supported JAX-RS component types in the given configurable context. Any subsequent registration attempts for a component type, for which a class or instance-based registration already exists in the system MUST be rejected by the JAX-RS implementation and a warning SHOULD be raised to inform the user about the rejected registration. The registered JAX-RS component is registered as a contract provider of all the recognized JAX-RS or implementation-specific extension contracts including meta-provider contracts, such as Feature or DynamicFeature.

As opposed to components registered via Configurable.register(Class) method, the lifecycle of providers registered using this instance-based register(...) is not managed by JAX-RS runtime. The same registered component instance is used during the whole lifespan of the configurable context. Fields and properties of all registered JAX-RS component instances are injected with their declared dependencies (see Context) by the JAX-RS runtime prior to use.

Parameters:

component - JAX-RS component instance to be configured in the scope of this configurable context.

Returns:

the updated configurable context.

register

public ResteasyClientBuilder register(Object component,
                             int priority)

Description copied from interface: Configurable

Register an instance of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.

This registration method provides the same functionality as Configurable.register(Object) except that any priority specified on the registered JAX-RS component class via javax.annotation.Priority annotation is overridden with the supplied priority value.

Note that in case the priority is not applicable to a particular provider contract implemented by the class of the registered component, the supplied priority value will be ignored for that contract.

Parameters:

component - JAX-RS component instance to be configured in the scope of this configurable context.

priority - the overriding priority for the registered component and all the provider contracts the component implements.

Returns:

the updated configurable context.

register

public ResteasyClientBuilder register(Object component,
                             Class<?>... contracts)

Description copied from interface: Configurable

Register an instance of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.

This registration method provides the same functionality as Configurable.register(Object) except the JAX-RS component class is only registered as a provider of the listed extension provider or meta-provider contracts. All explicitly enumerated contract types must represent a class or an interface implemented or extended by the registered component. Contracts that are not assignable from the registered component class MUST be ignored and implementations SHOULD raise a warning to inform users about the ignored contract(s).

Parameters:

component - JAX-RS component instance to be configured in the scope of this configurable context.

contracts - the specific extension provider or meta-provider contracts implemented by the component for which the component should be registered. Implementations MUST ignore attempts to register a component class for an empty or null collection of contracts via this method and SHOULD raise a warning about such event.

Returns:

the updated configurable context.

register

public ResteasyClientBuilder register(Object component,
                             Map<Class<?>,Integer> contracts)

Description copied from interface: Configurable

Register an instance of a custom JAX-RS component (such as an extension provider or a feature meta-provider) to be instantiated and used in the scope of this configurable context.

This registration method provides same functionality as Configurable.register(Object, Class[]) except that any priority specified on the registered JAX-RS component class via javax.annotation.Priority annotation is overridden for each extension provider contract type separately with an integer priority value specified as a value in the supplied map of [contract type, priority] pairs.

Note that in case a priority is not applicable to a provider contract registered for the JAX-RS component, the supplied priority value is ignored for such contract.

Parameters:

component - JAX-RS component instance to be configured in the scope of this configurable context.

contracts - map of the specific extension provider and meta-provider contracts and their associated priorities for which the JAX-RS component is registered. All contracts in the map must represent a class or an interface implemented or extended by the JAX-RS component. Contracts that are not assignable from the registered component class MUST be ignored and implementations SHOULD raise a warning to inform users about the ignored contract(s).

Returns:

the updated configurable context.

withConfig

public ResteasyClientBuilder withConfig(Configuration config)

Description copied from class: ClientBuilder

Set the internal configuration state to an externally provided configuration state.

Specified by:

withConfig in class ClientBuilder

Parameters:

config - external configuration state to replace the configuration of this configurable instance.

Returns:

the updated client builder instance.