Top Description Fields Constructors Methods
javax.ws.rs.client

public abstract Class ClientBuilder

extends Object
implements Configurable<ClientBuilder>
Class Inheritance
All Implemented Interfaces
javax.ws.rs.core.Configurable
Imports
java.net.URL, java.security.KeyStore, java.util.concurrent.ExecutorService, .ScheduledExecutorService, .TimeUnit, .TimeoutException, javax.ws.rs.ProcessingException, javax.ws.rs.core.Configurable, .Configuration, javax.ws.rs.sse.SseEventSource, javax.net.ssl.HostnameVerifier, .SSLContext
Main entry point to the client API used to bootstrap javax.ws.rs.client.Client instances.
Author
Marek Potociar
Since
2.0

Field Summary

Modifier and TypeField and Description
private static final String
JAXRS_DEFAULT_CLIENT_BUILDER

Default client builder implementation class name.

public static final String
JAXRS_DEFAULT_CLIENT_BUILDER_PROPERTY

Name of the property identifying the ClientBuilder implementation to be returned from ClientBuilder#newBuilder().

Constructor Summary

AccessConstructor and Description
protected
ClientBuilder()

Allows custom implementations to extend the ClientBuilder class.

Method Summary

Modifier and TypeMethod and Description
public abstract Client

Returns:

a new client instance.
build()

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

public abstract ClientBuilder

Returns:

an updated client builder instance.
connectTimeout(long
the maximum time to wait.
timeout, TimeUnit
the time unit of the timeout argument.
unit)

Set the connect timeout.

public abstract ClientBuilder

Returns:

an updated client builder instance.
executorService(final ExecutorService
executor service to be used for async invocations.
executorService)

Set the client-side ExecutorService.

public abstract ClientBuilder

Returns:

an updated client builder instance.
hostnameVerifier(final HostnameVerifier
hostname verifier.
verifier)

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

public abstract ClientBuilder

Returns:

an updated client builder instance.
keyStore(final KeyStore
client-side key store. Must not be null.
keyStore, final char[]
client key password. Must not be null.
password)

Set the client-side key store.

public ClientBuilder

Returns:

an updated client builder instance.
keyStore(final KeyStore
client-side key store. Must not be null.
keyStore, final String
client key password. Must not be null.
password)

Set the client-side key store.

public static ClientBuilder

Returns:

new client builder instance.
newBuilder()

Create a new ClientBuilder instance using the default client builder implementation class provided by the JAX-RS implementation provider.

public static Client

Returns:

new client instance.
newClient()

Create a new Client instance using the default client builder implementation class provided by the JAX-RS implementation provider.

public static Client

Returns:

new configured client instance.
newClient(final Configuration
data used to provide initial configuration for the new client instance.
configuration)

Create a new custom-configured Client instance using the default client builder implementation class provided by the JAX-RS implementation provider.

public abstract ClientBuilder

Returns:

an updated client builder instance.
readTimeout(long
the maximum time to wait.
timeout, TimeUnit
the time unit of the timeout argument.
unit)

Set the read timeout.

public abstract ClientBuilder

Returns:

an updated client builder instance.
scheduledExecutorService(final ScheduledExecutorService
executor service to be used for scheduled async invocations.
scheduledExecutorService)

Set the client-side ScheduledExecutorService.

public abstract ClientBuilder

Returns:

an updated client builder instance.
sslContext(final SSLContext
secure socket protocol implementation which acts as a factory for secure socket factories or SSL engines. Must not be null.
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.

public abstract ClientBuilder

Returns:

an updated client builder instance.
trustStore(final KeyStore
client-side trust store. Must not be null.
trustStore)

Set the client-side trust store.

public abstract ClientBuilder

Returns:

the updated client builder instance.
withConfig(Configuration
external configuration state to replace the configuration of this configurable instance.
config)

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

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

JAXRS_DEFAULT_CLIENT_BUILDERback to summary
private static final String JAXRS_DEFAULT_CLIENT_BUILDER

Default client builder implementation class name.

JAXRS_DEFAULT_CLIENT_BUILDER_PROPERTYback to summary
public static final String JAXRS_DEFAULT_CLIENT_BUILDER_PROPERTY

Name of the property identifying the ClientBuilder implementation to be returned from ClientBuilder#newBuilder().

Constructor Detail

ClientBuilderback to summary
protected ClientBuilder()

Allows custom implementations to extend the ClientBuilder class.

Method Detail

buildback to summary
public abstract Client build()

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

Returns:Client

a new client instance.

connectTimeoutback to summary
public abstract ClientBuilder connectTimeout(long timeout, TimeUnit unit)

Set the connect timeout.

Value 0 represents infinity. Negative values are not allowed.

Parameters
timeout:long

the maximum time to wait.

unit:TimeUnit

the time unit of the timeout argument.

Returns:ClientBuilder

an updated client builder instance.

Exceptions
IllegalArgumentException:
when the value is negative.
Since
2.1
executorServiceback to summary
public abstract ClientBuilder executorService(final ExecutorService executorService)

Set the client-side ExecutorService.

Provided executor service will be used for executing asynchronous tasks.

When running in a Java EE container, implementations are required to use the container-managed executor service by default. In Java SE, the default is implementation-specific. In either case, calling this method will override the default.

Parameters
executorService:ExecutorService

executor service to be used for async invocations.

Returns:ClientBuilder

an updated client builder instance.

Since
2.1
See Also
Invocation.Builder#async(), Invocation.Builder#rx(), RxInvokerProvider#getRxInvoker(SyncInvoker, ExecutorService)
hostnameVerifierback to summary
public abstract ClientBuilder hostnameVerifier(final HostnameVerifier verifier)

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

Parameters
verifier:HostnameVerifier

hostname verifier.

Returns:ClientBuilder

an updated client builder instance.

keyStoreback to summary
public abstract ClientBuilder keyStore(final KeyStore keyStore, final char[] password)

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).

Parameters
keyStore:KeyStore

client-side key store. Must not be null.

password:char[]

client key password. Must not be null.

Returns:ClientBuilder

an updated client builder instance.

Exceptions
NullPointerException:
in case any of the supplied parameters is null.
See Also
sslContext, keyStore(java.security.KeyStore, String), trustStore
keyStoreback to summary
public ClientBuilder keyStore(final KeyStore keyStore, final String password)

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 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).

Parameters
keyStore:KeyStore

client-side key store. Must not be null.

password:String

client key password. Must not be null.

Returns:ClientBuilder

an updated client builder instance.

Exceptions
NullPointerException:
in case any of the supplied parameters is null.
See Also
sslContext, keyStore(java.security.KeyStore, char[]), trustStore
newBuilderback to summary
public static ClientBuilder newBuilder()

Create a new ClientBuilder instance using the default client builder implementation class provided by the JAX-RS implementation provider.

Returns:ClientBuilder

new client builder instance.

newClientback to summary
public static Client newClient()

Create a new Client instance using the default client builder implementation class provided by the JAX-RS implementation provider.

Returns:Client

new client instance.

newClientback to summary
public static Client newClient(final Configuration configuration)

Create a new custom-configured Client instance using the default client builder implementation class provided by the JAX-RS implementation provider.

Parameters
configuration:Configuration

data used to provide initial configuration for the new client instance.

Returns:Client

new configured client instance.

readTimeoutback to summary
public abstract ClientBuilder readTimeout(long timeout, TimeUnit unit)

Set the read timeout.

The value is the timeout to read a response. If the server doesn't respond within the defined timeframe, ProcessingException is thrown with TimeoutException as a cause.

Value 0 represents infinity. Negative values are not allowed.

Parameters
timeout:long

the maximum time to wait.

unit:TimeUnit

the time unit of the timeout argument.

Returns:ClientBuilder

an updated client builder instance.

Exceptions
IllegalArgumentException:
when the value is negative.
Since
2.1
scheduledExecutorServiceback to summary
public abstract ClientBuilder scheduledExecutorService(final ScheduledExecutorService scheduledExecutorService)

Set the client-side ScheduledExecutorService.

Provided executor service will be used for executing scheduled asynchronous tasks.

When running in a Java EE container, implementations are required to use the container-managed scheduled executor service by default. In Java SE the default is implementation-specific. In either case, calling this method will override the default.

Parameters
scheduledExecutorService:ScheduledExecutorService

executor service to be used for scheduled async invocations.

Returns:ClientBuilder

an updated client builder instance.

Since
2.1
See Also
SseEventSource.Builder#reconnectingEvery(long, TimeUnit)
sslContextback to summary
public abstract ClientBuilder sslContext(final 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. 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.

Parameters
sslContext:SSLContext

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

Returns:ClientBuilder

an updated client builder instance.

Exceptions
NullPointerException:
in case the sslContext parameter is null.
See Also
keyStore(java.security.KeyStore, char[]), keyStore(java.security.KeyStore, String), trustStore
trustStoreback to summary
public abstract ClientBuilder trustStore(final KeyStore trustStore)

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.

Parameters
trustStore:KeyStore

client-side trust store. Must not be null.

Returns:ClientBuilder

an updated client builder instance.

Exceptions
NullPointerException:
in case the supplied trust store parameter is null.
See Also
sslContext, keyStore(java.security.KeyStore, char[]), keyStore(java.security.KeyStore, String)
withConfigback to summary
public abstract ClientBuilder withConfig(Configuration config)

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

Parameters
config:Configuration

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

Returns:ClientBuilder

the updated client builder instance.