Sometimes you are interested not only in the response body of a client request, but also either the response code and/or response headers. The Client-Proxy framework has two ways to get at this information

You may return a javax.ws.rs.core.Response.Status enumeration from your method calls:

@Path("/")
public interface MyProxy {
   @POST
   Response.Status updateSite(MyPojo pojo);
}
            

Internally, after invoking on the server, the client proxy internals will convert the HTTP response code into a Response.Status enum.

If you are interested in everything, you can get it with the javax.ws.rs.core.Response class:

@Path("/")
public interface LibraryService {

   @GET
   @Produces("application/xml")
   Response getAllBooks();
}

A further extension implemented by the RESTEasy client proxy framework is the "response proxy facility", where a client proxy method returns an interface that represents the information contained in a javax.ws.rs.core.Response. Such an interface must be annotated with @ResponseObject from package org.jboss.resteasy.annotations, and its methods may be further annotated with @Body, @LinkHeaderParam, and @Status from the same package, as well as javax.ws.rs.HeaderParam. Consider the following example.

   @ResponseObject
   public interface TestResponseObject {
      
      @Status
      int status();

      @Body
      String body();

      @HeaderParam("Content-Type")
      String contentType();
      
      ClientResponse response();
   }

   @Path("test")
   public interface TestClient {
   
      @GET
      TestResponseObject get();
   }

   @Path("test")
   public static class TestResource {

      @GET
      @Produces("text/plain")
      public String get() {
         return "ABC";
      }
   }
        

Here, TestClient will define the client side proxy for TestResource. Note that TestResource.get() returns a String but the proxy based on TestClient will return a TestResponseObject on a call to get():

      Client client = ClientBuilder.newClient();
      TestClient ClientInterface = ProxyBuilder.builder(TestClient.class, client.target("http://localhost:8081")).build();
      TestResponseObject tro = ClientInterface.get();
        

The methods of TestResponseObject provide access to various pieces of information about the response received from TestResponse.get(). This is where the annotations on those methods come into play. status() is annotated with @Status, and a call to status() returns the HTTP status. Similarly, body() returns the returned entity, and contentType() returns the value of the response header Content-Type:

      System.out.println("status: " + tro.status());
      System.out.println("entity: " + tro.body());
      System.out.println("Content-Type: " + tro.contentType());
        

will yield

status: 200
entity: ABC
Content-Type: text/plain;charset=UTF-8        
        

Note that there is one other method in TestResponseObject, response(), that has no annotation. When RESTEasy sees a method in an interface annotated with @ResponseObject that returns a javax.ws.rs.core.Response (or a subclass thereof), it will return a org.jboss.resteasy.client.jaxrs.internal.ClientResponse. For example,

      ClientResponse clientResponse =  tro.response();
      System.out.println("Content-Length: " + clientResponse.getLength());
        

Perhaps the most interesting piece of the response proxy facility is the treatment of methods annotated with @LinkHeaderParam. Its simplest use is to assist in accessing a javax.ws.rs.core.Link returned by a resource method. For example, let's add

      @GET
      @Path("/link-header")
      public Response getWithHeader(@Context UriInfo uri) {
         URI subUri = uri.getAbsolutePathBuilder().path("next-link").build();
         Link link = new LinkBuilderImpl().uri(subUri).rel("nextLink").build();
         return Response.noContent().header("Link", link.toString()).build();
      }
        

to TestResource, add

       @GET
       @Path("link-header")
       ResponseObjectInterface performGetBasedOnHeader();
        

to ClientInterface, and add

       @LinkHeaderParam(rel = "nextLink")
       URI nextLink();
        

to ResponseObjectInterface. Then calling

      ResponseObjectInterface obj = ClientInterface.performGetBasedOnHeader();
      System.out.println("nextLink(): " + obj.nextLink());
        

will access the LinkHeader returned by TestResource.getWithHeader():

nextlink: http://localhost:8081/test/link-header/next-link
        

Last but not least, let's add

      @GET
      @Produces("text/plain")
      @Path("/link-header/next-link")
      public String getHeaderForward() {
         return "forwarded";
      }
        

to TestResource and

       @GET
       @LinkHeaderParam(rel = "nextLink")
       String followNextLink();
        

to ResponseObjectInterface. Note that, unlike ResponseObjectInterface.nextLink(), followNextLink() is annotated with @GET; that is, it qualifies as (the client proxy to) a resource method. When executing followNextLink(), RESTEasy will retrieve the value of the Link returned by TestResource.getWithHeader() and then will make a GET invocation on the URL in that Link. Calling

      System.out.println("followNextLink(): " + obj.followNextLink());
        

causes RESTEasy to retrieve the URL http://localhost:8081/test/link-header/next-link from the call to TestResource.getWithHeader() and then perform a GET on it, invoking TestResource.getHeaderForward():

followNextLink(): forwarded
        

Client proxies figure out appropriate URIs for targeting resource methods by looking at @Path annotations in the client side interface, but it is also possible to pass URIs explicitly to the proxy through the use of the org.jboss.resteasy.annotations.ClientURI annotation. For example, let TestResource be a client side interface and TestResourceImpl a server resource:

   @Path("")
   public interface TestResource {
      
      @GET
      @Path("dispatch")
      public String dispatch(@ClientURI String uri);
   }
   
   @Path("")
   public static class TestResourceImpl {
      
      @GET
      @Path("a")
      public String a() {
         return "a";
      }
      
      @GET
      @Path("b")
      public String b() {
         return "b";
      }
   }
      

Calling TestResource.dispatch() allows specifying a specific URI for accessing a resource method. In the following, let BASE_URL be the address of the TestResourceImpl resource.

   private static String BASE_URL = "http://localhost:8081/";
   ...
   public void test() throws Exception
   {
      ResteasyClient client = (ResteasyClient)ClientBuilder.newClient();
      TestResource proxy = client.target(BASE_URL).proxy(TestResource.class);
      String name = proxy.dispatch(BASE_URL + "a");
      System.out.println("name: " + name);
      name = proxy.dispatch(BASE_URL + "b");
      System.out.println("name: " + name);
      client.close();
   }
      

Then passing "http://localhost:8081/a" and "http://localhost/b" to dispatch() invokes TestResourceImp.a() and TestResourceImpl.b() respectively, yielding the output

name: a
name: b
      

It is generally possible to share an interface between the client and server. In this scenario, you just have your Jakarta RESTful Web Services services implement an annotated interface and then reuse that same interface to create client proxies to invoke on the client-side.

The ClientHttpEngine implementations based on Apache HttpClient support HTTP redirection. The feaure is disabled by default and has to be enabled by users explicitly:

ApacheHttpClient43Engine engine = new ApacheHttpClient43Engine();
engine.setFollowRedirects(true);
Client client = ((ResteasyClientBuilder)ClientBuilder.newBuilder()).httpEngine(engine).build();
     

To enable SSL on client, a ClientHttpEngine containing a SSLContext can be created to build client as in the following example:

ClientHttpEngine myEngine = new ClientHttpEngine() {
   ...
   public void setSslContext(SSLContext sslContext) {
      this.sslContext = sslContext;
   }

   @Override
   public HostnameVerifier getHostnameVerifier() {
      return hostnameVerifier;
   }
};
myEngine.setSslContext(mySslContext)
ResteasyClient client = ((ResteasyClientBuilder)ClientBuilder.newBuilder()).httpEngine(myEngine).build();
            

An alternative is to set up a keystore and truststore and pass a custom SslContext to ClientBuilder:

Client sslClient = ClientBuilder.newBuilder().sslContext(mySslContext).build();
            

If you don't want to create a SSLContext, you can build client with a keystore and truststore. Note if both SSLContext and keystore/truststore are configured, the later will be ignored by Resteasy ClientBuilder.

Client sslClient = ClientBuilder.newBuilder().keystore(keystore,mypassword).
                      trustKeystore(trustStore).build();
            

During handshaking, a custom HostNameVerifier can be called to allow the connection if URL's hostname and the server's identification hostname match.

Client sslClient =  ((ResteasyClientBuilder)ClientBuilder.newBuilder()).sslContext(mysslContext)
                       .hostnameVerifier(myhostnameVerifier).build();
            

Resteasy provides another simple way to set up a HostnameVerifier. It allows configuring ResteasyClientBuilder with a HostnameVerificationPolicy without creating a custom HostNameVerifier:

Client sslClient =  ((ResteasyClientBuilder)ClientBuilder.newBuilder()).sslContext(mysslContext)
                       .hostnameVerification(ResteasyClientBuilder.HostnameVerificationPolicy.ANY).build();
            

The ClientHttpEngine implementations based on Apache HttpClient support HTTP proxy. This feature can be enabled by setting specific properties on the builder:

Client client = ClientBuilder.newBuilder().property("org.jboss.resteasy.jaxrs.client.proxy.host", "someproxy.com").property("org.jboss.resteasy.jaxrs.client.proxy.port", 8080).build();
     

The RESTEasy Client framework automatically creates and properly configures the underlying Apache HTTP Client engine. When the ApacheHttpClient43Engine is manually created, though, the user can either let it build and use a default HttpClient instance or provide a custom one:

public ApacheHttpClient43Engine() {
   ...
}

public ApacheHttpClient43Engine(HttpClient httpClient) {
   ...
}

public ApacheHttpClient43Engine(HttpClient httpClient, boolean closeHttpClient) {
   ...
}
     

The closeHttpClient parameter on the last constructor above allows controlling whether the Apache HttpClient is to be closed upon engine finalization. The default value is true. When a custom HttpClient instance is not provided, the default instance will always be closed together with the engine.

RESTEasy's default async engine implementation class is ApacheHttpAsyncClient4Engine. It can be set as the active engine by calling method useAsyncHttpEngine in ResteasyClientBuilder.

    Client asyncClient = ((ResteasyClientBuilder)ClientBuilder.newBuilder()).useAsyncHttpEngine()
                             .build();
    Future<Response> future = asyncClient
                             .target("http://locahost:8080/test").request()
                             .async().get();
    Response res = future.get();
    Assert.assertEquals(HttpResponseCodes.SC_OK, res.getStatus());
    String entity = res.readEntity(String.class);
        

As a drop in replacement, RESTEasy allows selecting a Jetty 9.4+ based HTTP engine. The Jetty implementation is newer and less tested, but it may end up being a good choice when relying on Jetty as server side already. The Jetty Server can even share execution resources with Client libraries if you configure them to use e.g. the same QueuedThreadPool.

The Jetty engine is enabled by adding a dependency to the org.jboss.resteasy:resteasy-client-jetty artifact to the Maven project; then the client can be built as follows:

ResteasyClient client = ((ResteasyClientBuilder)ClientBuilder.newBuilder()).clientEngine(
   new JettyClientEngine(new HttpClient())).build();
        

Still as a drop in replacement, RESTEasy allows selecting a Vert.x-based HTTP engine. The Vert.x implementation can perform asynchronous client invocations. It provides the following features:

The Vert.x engine is enabled by adding a dependency to the org.jboss.resteasy:resteasy-client-vertx artifact to the Maven project; then the client can be built as follows:

VertxClientHttpEngine engine = new VertxClientHttpEngine();
ResteasyClient client = ((ResteasyClientBuilder)ClientBuilder.newBuilder())
  .clientEngine(engine).build();
         

A Vert.x instance can also be provided when creating the client engine, as well as options configuration:

HttpClientOptions options = new HttpClientOptions()
 .setSsl(true);
 .setTrustStoreOptions(new JksOptions()
   .setPath("/path/to/your/truststore.jks")
   .setPassword("password-of-your-truststore")
);
VertxClientHttpEngine engine = new VertxClientHttpEngine(vertx, options);
         

Still as a drop in replacement, RESTEasy allows selecting a Reactor Netty based HTTP engine. The Reactor Netty implementation is newer and less tested, but can be a good choice if the user application is already dependening on Netty and performs asynchronous client invocations.

The Reactor Netty engine is enabled by adding a dependency to the org.jboss.resteasy:resteasy-client-reactor-netty artifact to the Maven project; then the client can be built as follows:

ReactorNettyClientHttpEngine engine = new ReactorNettyClientHttpEngine(
   HttpClient.create(),
   new DefaultChannelGroup(new DefaultEventExecutor()),
   HttpResources.get());
ResteasyClient client = ((ResteasyClientBuilder)ClientBuilder.newBuilder())
   .clientEngine(engine).build();
        

When coupled with the MonoRxInvoker, this has several benefits. It supports things like this:

webTarget.path("/foo").get().rx(MonoRxInvoker.class).map(...).subscribe()

in order to achieve non-blocking HTTP client calls. This allows leveraging some reactor features:

For some sample code, see org.jboss.resteasy.reactor.ReactorTest in the RESTEasy module resteasy-reactor.