Package org.eclipse.microprofile.rest.client

Interface RestClientBuilder

  • All Superinterfaces:
    javax.ws.rs.core.Configurable<RestClientBuilder>

    public interface RestClientBuilder
extends javax.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 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 Detail

      • 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

      • connectTimeout

        RestClientBuilder connectTimeout​(long timeout,
                                 java.util.concurrent.TimeUnit unit)
        Set the connect timeout.

        Like JAX-RS's javax.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:
        java.lang.IllegalArgumentException - - if the value of timeout is negative.
        Since:
        1.2

      • readTimeout

        RestClientBuilder readTimeout​(long timeout,
                              java.util.concurrent.TimeUnit unit)
        Set the read timeout.

        Like JAX-RS's javax.ws.rs.client.ClientBuilder's readTimeout method, specifying a timeout of 0 represents infinity, and negative values are not allowed.

        Also like the JAX-RS Client API, if the read timeout is reached, the client interface method will throw a javax.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:
        java.lang.IllegalArgumentException - - if the value of timeout is negative.
        Since:
        1.2

      • 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.
        Since:
        1.1

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