image:https://semaphoreci.com/api/v1/smallrye/smallrye-rest-client/branches/master/badge.svg["Semaphore CI", link="https://semaphoreci.com/smallrye/smallrye-rest-client"]
image:https://img.shields.io/github/license/thorntail/thorntail.svg["License", link="http://www.apache.org/licenses/LICENSE-2.0"]

= SmallRye Rest Client

SmallRye Rest Client is an implementation of https://github.com/eclipse/microprofile-rest-client[Eclipse MicroProfile Rest Client].

== Build

To build simply run

 $ mvn clean install

== Project Structure

* *docs* - project documentation
* *implementation* - produces implementation artifact
* *testsuite*
** *basic* - basic testsuite, tests functionalities which are not covered by the TCK
** *common* - test utils shared accross all test suites
** *tck* - TCK runner

== Non-portable Features

=== CDI Interceptors Support

In general, Rest Client proxies are not created by the CDI container and therefore method invocations do not pass through CDI interceptors.
In SmallRye, however, you can associate business method interceptors (denoted by the `@AroundInvoke` annotation) with a Rest Client proxy by using interceptor bindings.
The primary use case is the support of MicroProfile Fault Tolerance annotations, for example:

[java]
--------------------------------------------------------------------------
import org.eclipse.microprofile.faulttolerance.Retry;

@Path("/v1")
interface MyClient {

    @Retry(maxRetries = 3) // Retry on any exception thrown
    @GET
    @Path("/hello")
    String hello();
}
--------------------------------------------------------------------------

NOTE: The `org.eclipse.microprofile.faulttolerance.Asynchronous` annotation is currently not supported because the underlying RESTEasy client is not able to handle the `java.util.concurrent.Future` return types.

=== RestClientProxy

In addition to the MicroProfile Rest Client specification, every Rest Client proxy implements `io.smallrye.restclient.RestClientProxy` interface which allows you to:

* obtain the underlying `javax.ws.rs.client.Client` instance
* release all associated resources, for example:

[java]
--------------------------------------------------------------------------
public void hello() {
   MyClient myClient = RestClientBuilder.newBuilder().build(MyClient.class);
   myClient.hello();
   // Finally release all associated resources
   ((RestClientProxy) helloClient).close();
}
--------------------------------------------------------------------------