Package org.eclipse.microprofile.rest.client

# Interface RestClientBuilder

All Superinterfaces:
  `jakarta.ws.rs.core.Configurable<RestClientBuilder>`

public interface RestClientBuilder extends jakarta.ws.rs.core.Configurable<RestClientBuilder>
This is the main entry point for creating a Type Safe Rest Client.

Invoking `newBuilder()` is intended to always create a new instance, not use a cached version.

The `RestClientBuilder` is a `Configurable` class as defined by Jakarta RESTful Web Services. This allows a user to register providers, implementation specific configuration.

Implementations are expected to implement this class and provide the instance via the mechanism in `RestClientBuilderResolver.instance()`.

## Method Summary

Modifier and Type
Method
Description
`default RestClientBuilder`
`baseUri(String uri)`
Specifies the base URI to be used when making requests.
`default RestClientBuilder`
`baseUri(URI uri)`
Specifies the base URI to be used when making requests.
`RestClientBuilder`
`baseUrl(URL url)`
Specifies the base URL to be used when making requests.
`<T> T`
`build(Class<T> clazz)`
Based on the configured RestClientBuilder, creates a new instance of the given REST interface to invoke API calls against.
`RestClientBuilder`
`connectTimeout(long timeout, TimeUnit unit)`
Set the connect timeout.
`RestClientBuilder`
`executorService(ExecutorService executor)`
Specifies the `ExecutorService` to use when invoking asynchronous Rest Client interface methods.
`RestClientBuilder`
`followRedirects(boolean follow)`
Specifies whether client built by this builder should follow HTTP redirect responses (30x) or not.
`RestClientBuilder`
`header(String name, Object value)`
Add an arbitrary header.
`RestClientBuilder`
`hostnameVerifier(HostnameVerifier hostnameVerifier)`
Set the hostname verifier to verify the endpoint's hostname
`RestClientBuilder`
`keyStore(KeyStore keyStore, String keystorePassword)`
Set the client-side key store.
`static RestClientBuilder`
`newBuilder()`
`RestClientBuilder`
`proxyAddress(String proxyHost, int proxyPort)`
Specifies the HTTP proxy hostname/IP address and port to use for requests from client instances.
`RestClientBuilder`
`queryParamStyle(QueryParamStyle style)`
Specifies the URI formatting style to use when multiple query parameter values are passed to the client.
`RestClientBuilder`
`readTimeout(long timeout, TimeUnit unit)`
Set the read timeout.
`RestClientBuilder`
`sslContext(SSLContext sslContext)`
Specifies the SSL context to use when creating secured transport connections to server endpoints from web targets created by the client instance that is using this SSL context.
`RestClientBuilder`
`trustStore(KeyStore trustStore)`
Set the client-side trust store.

### Methods inherited from interface jakarta.ws.rs.core.Configurable

`getConfiguration, property, register, register, register, register, register, register, register, register`

## Method Details

### newBuilder

static RestClientBuilder newBuilder()

### baseUrl

RestClientBuilder baseUrl(URL url)
Specifies the base URL to be used when making requests. Assuming that the interface has a `@Path("/api")` at the interface level and a `url` is given with `http://my-service:8080/service` then all REST calls will be invoked with a `url` of `http://my-service:8080/service/api` in addition to any `@Path` annotations included on the method. Subsequent calls to this method will replace the previously specified baseUri/baseUrl.

Parameters:
  `url` - the base Url for the service.
Returns:
  the current builder with the baseUrl set.

### baseUri

default RestClientBuilder baseUri(URI uri)
Specifies the base URI to be used when making requests. Assuming that the interface has a `@Path("/api")` at the interface level and a `uri` is given with `http://my-service:8080/service` then all REST calls will be invoked with a `uri` of `http://my-service:8080/service/api` in addition to any `@Path` annotations included on the method. Subsequent calls to this method will replace the previously specified baseUri/baseUrl.

Parameters:
  `uri` - the base URI for the service.
Returns:
  the current builder with the baseUri set
Throws:
  `IllegalArgumentException` - if the passed in URI is invalid
Since:
  1.1

### baseUri

default RestClientBuilder baseUri(String uri)
Specifies the base URI to be used when making requests. Assuming that the interface has a `@Path("/api")` at the interface level and a `uri` is given with `http://my-service:8080/service` then all REST calls will be invoked with a `uri` of `http://my-service:8080/service/api` in addition to any `@Path` annotations included on the method. Subsequent calls to this method will replace the previously specified baseUri/baseUrl.

Parameters:
  `uri` - the base URI for the service.
Returns:
  the current builder with the baseUri set
Throws:
  `IllegalArgumentException` - if the passed in URI is invalid
Since:
  4.0

### connectTimeout

RestClientBuilder connectTimeout(long timeout, TimeUnit unit)
Set the connect timeout.

Like Jakarta RESTful Web Services's `jakarta.ws.rs.client.ClientBuilder`'s `connectTimeout` method, specifying a timeout of 0 represents infinity, and negative values are not allowed.

If the client instance is injected via CDI and the "fully.qualified.InterfaceName/mp-rest/connectTimeout" property is set via MicroProfile Config, that property's value will override, the value specified to this method.

Parameters:
  `timeout` - the maximum time to wait.
  `unit` - the time unit of the timeout argument.
Returns:
  the current builder with the connect timeout set.
Throws:
  `IllegalArgumentException` - if the value of timeout is negative.
Since:
  1.2

### readTimeout

RestClientBuilder readTimeout(long timeout, TimeUnit unit)
Set the read timeout.

Like Jakarta RESTful Web Services's `jakarta.ws.rs.client.ClientBuilder`'s `readTimeout` method, specifying a timeout of 0 represents infinity, and negative values are not allowed.

Also like the Jakarta RESTful Web Services Client API, if the read timeout is reached, the client interface method will throw a `jakarta.ws.rs.ProcessingException`.

If the client instance is injected via CDI and the "fully.qualified.InterfaceName/mp-rest/readTimeout" property is set via MicroProfile Config, that property's value will override, the value specified to this method.

Parameters:
  `timeout` - the maximum time to wait.
  `unit` - the time unit of the timeout argument.
Returns:
  the current builder with the connect timeout set.
Throws:
  `IllegalArgumentException` - if the value of timeout is negative.
Since:
  1.2

### executorService

RestClientBuilder executorService(ExecutorService executor)
Specifies the `ExecutorService` to use when invoking asynchronous Rest Client interface methods. By default, the executor service used is determined by the MP Rest Client implementation runtime.

Parameters:
  `executor` - the executor service for the runtime to use when invoking asynchronous Rest Client interface methods - must be non-null.
Returns:
  the current builder with the executorService set.
Throws:
  `IllegalArgumentException` - if the `executor` parameter is null.
Since:
  1.1

### sslContext

RestClientBuilder sslContext(SSLContext sslContext)
Specifies the SSL context to use when creating secured transport connections to server endpoints from web targets created by the client instance that is using this SSL context.

Parameters:
  `sslContext` - the ssl context
Returns:
  the current builder with ssl context set
Throws:
  `NullPointerException` - if the `sslContext` parameter is null.
Since:
  1.3

### trustStore

RestClientBuilder trustStore(KeyStore trustStore)
Set the client-side trust store.

Parameters:
  `trustStore` - key store
Returns:
  the current builder with the trust store set
Throws:
  `NullPointerException` - if the `trustStore` parameter is null.
Since:
  1.3

### keyStore

RestClientBuilder keyStore(KeyStore keyStore, String keystorePassword)
Set the client-side key store.

Parameters:
  `keyStore` - key store
  `keystorePassword` - the password for the specified `keyStore`
Returns:
  the current builder with the key store set
Throws:
  `NullPointerException` - if the `keyStore` parameter is null.
Since:
  1.3

### hostnameVerifier

RestClientBuilder hostnameVerifier(HostnameVerifier hostnameVerifier)
Set the hostname verifier to verify the endpoint's hostname

Parameters:
  `hostnameVerifier` - the hostname verifier
Returns:
  the current builder with hostname verifier set
Throws:
  `NullPointerException` - if the `hostnameVerifier` parameter is null.
Since:
  1.3

### followRedirects

RestClientBuilder followRedirects(boolean follow)
Specifies whether client built by this builder should follow HTTP redirect responses (30x) or not.

Parameters:
  `follow` - - true if the client should follow HTTP redirects, false if not.
Returns:
  the current builder with the followRedirect property set.
Since:
  2.0

### proxyAddress

RestClientBuilder proxyAddress(String proxyHost, int proxyPort)
Specifies the HTTP proxy hostname/IP address and port to use for requests from client instances.

Parameters:
  `proxyHost` - - hostname or IP address of proxy server - must be non-null
  `proxyPort` - - port of proxy server
Returns:
  the current builder with the proxy host set
Throws:
  `IllegalArgumentException` - if the `proxyHost` is null or the `proxyPort` is invalid
Since:
  2.0

### queryParamStyle

RestClientBuilder queryParamStyle(QueryParamStyle style)
Specifies the URI formatting style to use when multiple query parameter values are passed to the client.

Parameters:
  `style` - - the URI formatting style to use for multiple query parameter values
Returns:
  the current builder with the style of query params set
Since:
  2.0

### header

RestClientBuilder header(String name, Object value)
Add an arbitrary header.

Parameters:
  `name` - - the name of the header
  `name` - - the value of the HTTP header to add to the request.
Returns:
  the current builder with the header added to the request.
Throws:
  `NullPointerException` - if the value is null.
Since:
  4.0

### build

<T> T build(Class<T> clazz) throws IllegalStateException, RestClientDefinitionException
Based on the configured RestClientBuilder, creates a new instance of the given REST interface to invoke API calls against.

Type Parameters:
  `T` - the type of the interface
Parameters:
  `clazz` - the interface that defines REST API methods for use
Returns:
  a new instance of an implementation of this REST interface that
Throws:
  `IllegalStateException` - if not all pre-requisites are satisfied for the builder, this exception may get thrown. For instance, if the base URI/URL has not been set.
  `RestClientDefinitionException` - if the passed-in interface class is invalid.