RestfulMappingClient

RestfulMappingClient is an interface which provides facilities to communicate with RESTful web services. RestfulMappingClient differs from RestfulSession in that it must be provided with RESTful endpoint URIs and request data, whereas the latter is integrated into the ORM and abstracts this information out so that a web service can be consumed using domain objects. While RestfulSession is geared towards communicating with a repository web service, RestfulMappingClient is designed to simplify communication with any RESTful service, external API or otherwise.

Unlike RestfulClient, which provides a low-level REST client, RestfulMappingClient converts REST responses into objects using a MessageConverter.

Using a RestfulMappingClient

Infinitum provides an implementation of RestfulMappingClient called CachingEnabledRestfulMappingClient. Like RestfulClient, there is no configuration needed to use RestfulMappingClient — simply instantiate it and begin making web requests!

RestfulMappingClient rest = new CachingEnabledRestfulMappingClient(context);

// HTTP GET request
Foo foo = rest.executeGet("http://localhost/mywebservice/foo/42", Foo.class);

// HTTP DELETE request
RestResponse response = rest.executeDelete("http://localhost/mywebservice/foo/42");

// HTTP POST request
String someJson = "{\"id\":\"328\",\"val\":\"42\"}";
Bar bar = rest.executePost("http://localhost/mywebservice/foo", someJson, "application/json", Bar.class);

// HTTP PUT request
someJson = "{\"id\":\"328\",\"val\":\"76\"}";
RestResponse response = rest.executePut("http://localhost/mywebservice/foo", someJson, "application/json");

We can also apply headers to our requests:

Map<String, String> headers = new HashMap<String, String>();
headers.put("Accept", "text/xml");
Foo foo = rest.executeGet("http://localhost/mywebservice/foo/42", headers, Foo.class);

Additionally, connection and response timeouts can be configured for the RestfulMappingClient:

rest.setConnectionTimeout(5000);
rest.setResponseTimeout(5000);

RestfulMappingClient can make use of an AuthenticationStrategy to simplify the process of creating authorized requests to a web service.

rest.setAuthStrategy(myAuthStrategy);

In order to convert responses into objects, RestfulMappingClient uses a MessageConverter. Infinitum provides several implementations including GsonMessageConverter, SimpleXmlMessageConverter, and JacksonMessageConverter. If a MessageConverter is not provided, CachingEnabledRestfulMappingClient will default to GsonMessageConverter.

rest.setMessageConverter(new JacksonMessageConverter());

The MessageConverter can also be specified in the constructor:

RestfulMappingClient rest = new CachingEnabledRestfulMappingClient(context, new JacksonMessageConverter());