RESTEasy Proxy client

This is, in my opinion, the most excited way of creating client when using RESTEasy client. You can create an interface that describe your REST request in the JAX-RS way and then use it to create a proxy that will use the JAX-RS annotations and perform requests to the server. It’s pretty simple and has a lot of advantages over the ClientRequest class, but also presents a few disadvantages. You have to choose the right client according your necessities.
To use the Proxy client the first thing you have to do is create an interface with the corresponding JAX-RS annotations. Let us say we want to consume the Master The JBoss RESTEasy Tutorial, what we have to do is to create an interface and use JAX-RS annotations describe the requests like the following interface:

    @Path("/web-interfaces")
    public interface MasterJBoss{
        @GET
        @Path("273-resteasy-tutorial-.html")
        public String resteasyTutorial();        
    }


Now we can create concrete implementation of these interfaces using the <strong>org.jboss.resteasy.client.ClientRequestFactory</strong> class:
        ClientRequestFactory crf = new ClientRequestFactory(UriBuilder.fromUri(
                "http://www.mastertheboss.com").build());
        MasterJBoss mb = crf.createProxy(MasterJBoss.class);
        System.out.println(mb.resteasyTutorial());

It may not look very advantageous at the first look, but when we are dealing with complex and well REST oriented APIs/Web Services, this kind of client is very useful. Other circumstance that make this client a good choose is when we want to share an interface between the server and the client.
I said that we can use JAX-RS features with this approach, we have a more complex example that uses the Twitter API. The related interface is showed in the following code:
    public interface TwitterAPI {
        @GET
        @Path("users/show.xml")
        public TwitterUser userInformation(
                @QueryParam("screen_name") String screenName);

        @GET
        @Path("statuses/show.xml")
        public Status status(@QueryParam("id") String id);
    }

Then you can simply create a new implementation based in this interface and call the methods you want.
        ClientRequestFactory crf = new ClientRequestFactory(UriBuilder.fromUri(
                "https://api.twitter.com/1").build());
        TwitterAPI twitterAPI = crf.createProxy(TwitterAPI.class);
        System.out.println(twitterAPI.userInformation("resteasy"));        
        System.out.println(twitterAPI.status("112652479837110273"));

Of course, nothing is magical and perfect. You may face some incompatibility of what you described in the interface and how your interface really is. RESTEasy has a lot of resources to help you to workaround some of them (for example when using lists RESTEasy lets you map lists using a proprietary annotation), but it’s out of scope of this article describe all of these possibilities of incompatibilities.

Using RESTEasy interceptors

The last topic is to show you a very useful feature of the client API. You create interceptors that will help you to, for the most common use, create log of the application or other things.
The interceptor may be called before(prefix interceptor) and after the request(suffix interceptor), I mean, when send the request to the server and when the server responds to you.
To use this feature you simply need to create a class that implements the interface org.jboss.resteasy.spi.interception.ClientExecutionInterceptor and register this class as a prefix or suffix interceptor in the ClientRequestFactory. In the following piece of code we show how to register two interceptors.

        ClientRequestFactory crf = new ClientRequestFactory(UriBuilder.fromUri(
                "http://api.twitter.com/1").build());

        crf.getPrefixInterceptors().getExecutionInterceptorList()
                .add(new ClientExecutionInterceptor() {
                    @Override
                    public ClientResponse execute(ClientExecutionContext ctx)
                            throws Exception {
                        System.out.println("Starting execution of method "
                                + ctx.getRequest().getHttpMethod() + " in URL "
                                + ctx.getRequest().getUri());
                        return ctx.proceed();
                    }
                });
        
        crf.getSuffixInterceptors().getExecutionInterceptorList()
        .add(new ClientExecutionInterceptor() {
            @Override
            public ClientResponse execute(ClientExecutionContext ctx)
                    throws Exception {
                System.out.println("End execution of method "
                        + ctx.getRequest().getHttpMethod() + " in URL "
                        + ctx.getRequest().getUri());
                return ctx.proceed();
            }
        });

JAX-RS 2.0 Client API

JAX-RS 2.0 (JSR 339) is almost finished and it will specify a a client API.

Response res = client.target("http://example.org/hello")
.queryParam("MyParam","...")
.request("text/plain")
.header("MyHeader", "...")
.get();

It will be based in builders and will not use the proxy concept we presented here. RESTEasy 3.0 will implement JAX-RS.

Conclusion

We presented the main features of the RESTEasy client API. Of course according your necessities it will be necessary to go more deeper in the API documentation, but I hope we could introduce you this API.

Download the code of this tutorial.

0
0
0
s2smodern