MicroProfile 7.0 · org.eclipse.microprofile.rest.client.RestClientBuilder

Method Summary

Modifier and Type	Method and Description
public default RestClientBuilder	Returns: the current builder with the baseUri set baseUri(URI the base URI for the service. uri) Specifies the base URI to be used when making requests.
public default RestClientBuilder	Returns: the current builder with the baseUri set baseUri(String the base URI for the service. uri) Specifies the base URI to be used when making requests.
public RestClientBuilder	Returns: the current builder with the baseUrl set. baseUrl(URL the base Url for the service. url) Specifies the base URL to be used when making requests.
public < the type of the interface T> T	Returns: a new instance of an implementation of this REST interface that build(Class<T> the interface that defines REST API methods for use clazz) Based on the configured RestClientBuilder, creates a new instance of the given REST interface to invoke API calls against.
public RestClientBuilder	Returns: the current builder with the connect timeout set. connectTimeout(long the maximum time to wait. timeout, TimeUnit the time unit of the timeout argument. unit) Set the connect timeout.
public RestClientBuilder	Returns: the current builder with the executorService set. executorService(ExecutorService the executor service for the runtime to use when invoking asynchronous Rest Client interface methods - must be non-null. executor) Specifies the `ExecutorService` to use when invoking asynchronous Rest Client interface methods.
public RestClientBuilder	Returns: the current builder with the followRedirect property set. followRedirects(boolean - true if the client should follow HTTP redirects, false if not. follow) Specifies whether client built by this builder should follow HTTP redirect responses (30x) or not.
public RestClientBuilder	Returns: the current builder with the header added to the request. header(String - the name of the header - the value of the HTTP header to add to the request. name, Object value) Add an arbitrary header.
public RestClientBuilder	Returns: the current builder with hostname verifier set hostnameVerifier(HostnameVerifier the hostname verifier hostnameVerifier) Set the hostname verifier to verify the endpoint's hostname
public RestClientBuilder	Returns: the current builder with the key store set keyStore(KeyStore key store keyStore, String the password for the specified `keyStore` keystorePassword) Set the client-side key store.
public static RestClientBuilder	newBuilder()
public RestClientBuilder	Returns: the current builder with the proxy host set proxyAddress(String - hostname or IP address of proxy server - must be non-null proxyHost, int - port of proxy server proxyPort) Specifies the HTTP proxy hostname/IP address and port to use for requests from client instances.
public RestClientBuilder	Returns: the current builder with the style of query params set queryParamStyle(QueryParamStyle - the URI formatting style to use for multiple query parameter values style) Specifies the URI formatting style to use when multiple query parameter values are passed to the client.
public RestClientBuilder	Returns: the current builder with the connect timeout set. readTimeout(long the maximum time to wait. timeout, TimeUnit the time unit of the timeout argument. unit) Set the read timeout.
public RestClientBuilder	Returns: the current builder with ssl context set sslContext(SSLContext the ssl context 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.
public RestClientBuilder	Returns: the current builder with the trust store set trustStore(KeyStore key store trustStore) Set the client-side trust store.

Inherited from jakarta.ws.rs.core.Configurable:: getConfiguration property register register register register register register register register

Method Detail

baseUri back to summary

baseUri	back to summary
public 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:URI the base URI for the service. Returns:RestClientBuilder the current builder with the baseUri set Exceptions IllegalArgumentException: if the passed in URI is invalid Since 1.1

public 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:URI: the base URI for the service.

Returns:RestClientBuilder

the current builder with the baseUri set

Exceptions

IllegalArgumentException:: if the passed in URI is invalid

Since

1.1

baseUri back to summary

baseUri	back to summary
public 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:String the base URI for the service. Returns:RestClientBuilder the current builder with the baseUri set Exceptions IllegalArgumentException: if the passed in URI is invalid Since 4.0

public default RestClientBuilder baseUri(String uri)

Parameters

uri:String: the base URI for the service.

Returns:RestClientBuilder

the current builder with the baseUri set

Exceptions

IllegalArgumentException:: if the passed in URI is invalid

Since

4.0

baseUrl back to summary

baseUrl	back to summary
public 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:URL the base Url for the service. Returns:RestClientBuilder the current builder with the baseUrl set.

public 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:URL: the base Url for the service.

Returns:RestClientBuilder

the current builder with the baseUrl set.

build	back to summary
public <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. Parameters <T> the type of the interface clazz:Class<T> the interface that defines REST API methods for use Returns:T a new instance of an implementation of this REST interface that Exceptions 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.

build

back to summary

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

Parameters

<T>: the type of the interface
clazz:Class<T>: the interface that defines REST API methods for use

Returns:T

a new instance of an implementation of this REST interface that

Exceptions

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.

connectTimeout back to summary

connectTimeout	back to summary
public 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:long the maximum time to wait. unit:TimeUnit the time unit of the timeout argument. Returns:RestClientBuilder the current builder with the connect timeout set. Exceptions IllegalArgumentException: if the value of timeout is negative. Since 1.2

public 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:long: the maximum time to wait.
unit:TimeUnit: the time unit of the timeout argument.

Returns:RestClientBuilder

the current builder with the connect timeout set.

Exceptions

IllegalArgumentException:: if the value of timeout is negative.

Since

1.2

executorService back to summary

executorService	back to summary
public 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:ExecutorService the executor service for the runtime to use when invoking asynchronous Rest Client interface methods - must be non-null. Returns:RestClientBuilder the current builder with the executorService set. Exceptions IllegalArgumentException: if the `executor` parameter is null. Since 1.1

public 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:ExecutorService: the executor service for the runtime to use when invoking asynchronous Rest Client interface methods - must be non-null.

Returns:RestClientBuilder

the current builder with the executorService set.

Exceptions

IllegalArgumentException:: if the executor parameter is null.

Since

1.1

followRedirects	back to summary
public RestClientBuilder followRedirects(boolean follow) Specifies whether client built by this builder should follow HTTP redirect responses (30x) or not. Parameters follow:boolean - true if the client should follow HTTP redirects, false if not. Returns:RestClientBuilder the current builder with the followRedirect property set. Since 2.0

followRedirects

back to summary

public RestClientBuilder followRedirects(boolean follow)

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

Parameters

follow:boolean: - true if the client should follow HTTP redirects, false if not.

Returns:RestClientBuilder

the current builder with the followRedirect property set.

Since

2.0

header	back to summary
public RestClientBuilder header(String name, Object value) Add an arbitrary header. Parameters name:String - the name of the header - the value of the HTTP header to add to the request. Returns:RestClientBuilder the current builder with the header added to the request. Exceptions NullPointerException: if the value is null. Since 4.0

header

back to summary

public RestClientBuilder header(String name, Object value)

Add an arbitrary header.

Parameters

name:String

- the name of the header
- the value of the HTTP header to add to the request.

Returns:RestClientBuilder

the current builder with the header added to the request.

Exceptions

NullPointerException:: if the value is null.

Since

4.0

hostnameVerifier back to summary

hostnameVerifier	back to summary
public RestClientBuilder hostnameVerifier(HostnameVerifier hostnameVerifier) Set the hostname verifier to verify the endpoint's hostname Parameters hostnameVerifier:HostnameVerifier the hostname verifier Returns:RestClientBuilder the current builder with hostname verifier set Exceptions NullPointerException: if the `hostnameVerifier` parameter is null. Since 1.3

public RestClientBuilder hostnameVerifier(HostnameVerifier hostnameVerifier)

Set the hostname verifier to verify the endpoint's hostname

Parameters

hostnameVerifier:HostnameVerifier: the hostname verifier

Returns:RestClientBuilder

the current builder with hostname verifier set

Exceptions

NullPointerException:: if the hostnameVerifier parameter is null.

Since

1.3

keyStore back to summary

keyStore	back to summary
public RestClientBuilder keyStore(KeyStore keyStore, String keystorePassword) Set the client-side key store. Parameters keyStore:KeyStore key store keystorePassword:String the password for the specified `keyStore` Returns:RestClientBuilder the current builder with the key store set Exceptions NullPointerException: if the `keyStore` parameter is null. Since 1.3

public RestClientBuilder keyStore(KeyStore keyStore, String keystorePassword)

Set the client-side key store.

Parameters

keyStore:KeyStore: key store
keystorePassword:String: the password for the specified keyStore

Returns:RestClientBuilder

the current builder with the key store set

Exceptions

NullPointerException:: if the keyStore parameter is null.

Since

1.3

newBuilder	back to summary
public static RestClientBuilder newBuilder()

proxyAddress back to summary

proxyAddress	back to summary
public RestClientBuilder proxyAddress(String proxyHost, int proxyPort) Specifies the HTTP proxy hostname/IP address and port to use for requests from client instances. Parameters proxyHost:String - hostname or IP address of proxy server - must be non-null proxyPort:int - port of proxy server Returns:RestClientBuilder the current builder with the proxy host set Exceptions IllegalArgumentException: if the `proxyHost` is null or the `proxyPort` is invalid Since 2.0

public RestClientBuilder proxyAddress(String proxyHost, int proxyPort)

Specifies the HTTP proxy hostname/IP address and port to use for requests from client instances.

Parameters

proxyHost:String: - hostname or IP address of proxy server - must be non-null
proxyPort:int: - port of proxy server

Returns:RestClientBuilder

the current builder with the proxy host set

Exceptions

IllegalArgumentException:: if the proxyHost is null or the proxyPort is invalid

Since

2.0

queryParamStyle	back to summary
public RestClientBuilder queryParamStyle(QueryParamStyle style) Specifies the URI formatting style to use when multiple query parameter values are passed to the client. Parameters style:QueryParamStyle - the URI formatting style to use for multiple query parameter values Returns:RestClientBuilder the current builder with the style of query params set Since 2.0

queryParamStyle

back to summary

public RestClientBuilder queryParamStyle(QueryParamStyle style)

Specifies the URI formatting style to use when multiple query parameter values are passed to the client.

Parameters

style:QueryParamStyle: - the URI formatting style to use for multiple query parameter values

Returns:RestClientBuilder

the current builder with the style of query params set

Since

2.0

readTimeout back to summary

readTimeout	back to summary
public 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:long the maximum time to wait. unit:TimeUnit the time unit of the timeout argument. Returns:RestClientBuilder the current builder with the connect timeout set. Exceptions IllegalArgumentException: if the value of timeout is negative. Since 1.2

public 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:long: the maximum time to wait.
unit:TimeUnit: the time unit of the timeout argument.

Returns:RestClientBuilder

the current builder with the connect timeout set.

Exceptions

IllegalArgumentException:: if the value of timeout is negative.

Since

1.2

sslContext back to summary

sslContext	back to summary
public 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:SSLContext the ssl context Returns:RestClientBuilder the current builder with ssl context set Exceptions NullPointerException: if the `sslContext` parameter is null. Since 1.3

public 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:SSLContext: the ssl context

Returns:RestClientBuilder

the current builder with ssl context set

Exceptions

NullPointerException:: if the sslContext parameter is null.

Since

1.3

trustStore back to summary

trustStore	back to summary
public RestClientBuilder trustStore(KeyStore trustStore) Set the client-side trust store. Parameters trustStore:KeyStore key store Returns:RestClientBuilder the current builder with the trust store set Exceptions NullPointerException: if the `trustStore` parameter is null. Since 1.3

public RestClientBuilder trustStore(KeyStore trustStore)

Set the client-side trust store.

Parameters

trustStore:KeyStore: key store

Returns:RestClientBuilder

the current builder with the trust store set

Exceptions

NullPointerException:: if the trustStore parameter is null.

Since

1.3

public Interface RestClientBuilder

Method Summary

Method Detail