Package org.eclipse.microprofile.rest.client

Interface RestClientBuilder

All Superinterfaces:

Configurable<RestClientBuilder>

public interface RestClientBuilder
extends 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 JAX-RS. 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(java.net.URI uri)	Specifies the base URI to be used when making requests.
RestClientBuilder	baseUrl(java.net.URL url)	Specifies the base URL to be used when making requests.
<T> T	build(java.lang.Class<T> clazz)	Based on the configured RestClientBuilder, creates a new instance of the given REST interface to invoke API calls against.
RestClientBuilder	executorService(java.util.concurrent.ExecutorService executor)	Specifies the ExecutorService to use when invoking asynchronous Rest Client interface methods.
static RestClientBuilder	newBuilder()

Methods inherited from interface javax.ws.rs.core.Configurable

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

Method Detail

newBuilder

static RestClientBuilder newBuilder()

baseUrl

RestClientBuilder baseUrl(java.net.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(java.net.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:

java.lang.IllegalArgumentException - if the passed in URI is invalid

Since:

1.1

executorService

RestClientBuilder executorService(java.util.concurrent.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:

java.lang.IllegalArgumentException - if the executor parameter is null.

build

<T> T build(java.lang.Class<T> clazz)
     throws java.lang.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:

java.lang.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.