responseentity

Spring's RestTemplate is a robust, popular Java-based REST client. The Spring for Android RestTemplate Module provides a version of RestTemplate that works in an Android environment.

The RestTemplate class is the heart of the Spring for Android RestTemplate library. It is conceptually similar to other template classes found in other Spring portfolio projects. RestTemplate's behavior is customized by providing callback methods and configuring the HttpMessageConverter used to marshal objects into the HTTP request body and to unmarshal any response back into an object. When you create a new RestTemplate instance, the constructor sets up several supporting objects that make up the RestTemplate functionality.

Here is an overview of the functionality supported within RestTemplate.

RestTemplate provides an abstraction for making RESTful HTTP requests, and internally, RestTemplate utilizes a native Android HTTP client library for those requests. There are two native HTTP clients available on Android, the standard J2SE facilities, and the HttpComponents HttpClient. The standard JS2SE facilities are made available through the SimpleClientHttpRequestFactory, while the HttpClient is made available through the HttpComponentsClientHttpRequestFactory. The default ClientHttpRequestFactory used when you create a new RestTemplate instance differs based on the version of Android on which your application is running.

Google recommends to use the J2SE facilities on Gingerbread [Version 2.3] and newer, while previous versions should use the HttpComponents HttpClient. Based on this recommendation RestTemplate checks the version of Android on which your app is running and uses the appropriate ClientHttpRequestFactory. To utilize a specific ClientHttpRequestFactory you must either pass a new instance into the RestTemplate constructor, or call setRequestFactory[ClientHttpRequestFactory requestFactory] on an existing RestTemplate instance.

RestTemplate supports sending and receiving data encoded with gzip compression. The HTTP specification allows for additional values in the Accept-Encoding header field, however RestTemplate only supports gzip compression at this time.

2.2.3 Object to JSON Marshaling

Object to JSON marshaling in Spring for Android RestTemplate requires the use of a third party JSON mapping library. There are three libraries supported in Spring for Android, Jackson JSON Processor, Jackson 2.x, and Google Gson. While Jackson is a well known JSON parsing library, the Gson library is smaller, which would result in an smaller Android app when packaged.

2.2.4 Object to XML Marshaling

Object to XML marshaling in Spring for Android RestTemplate requires the use of a third party XML mapping library. The Simple XML serializer is used to provide this marshaling functionality.

2.2.5 RSS and Atom Support

RSS and Atom feed support in Spring for Android RestTemplate requires the use of a third party feed reader library. The Android ROME Feed Reader is used to provide this functionality.

There are a few methods for including external jars in your Android app. One is to manually download them and include them in your app's libs/ folder. Another option is to use Maven for dependency management.

2.3.1 Standard Installation

In order to use RestTemplate in your Android application, you must include the following Spring for Android jars in the libs/ folder. These are available from the SpringSource Community Downloads page.

• spring-android-rest-template-{version}.jar
• spring-android-core-{version}.jar

If you are building your project with Ant, Ant will automatically include any jars located in the libs/ folder located in the root of your project. However, in Eclipse you must manually add the jars to the Build Path. Follow these steps to add the jars to your existing Android project in Eclipse.

1. Refresh the project in Eclipse so the libs/ folder and jars display in the Package Explorer.
2. Right-Click [Command-Click] the first jar.
3. Select the BuildPath submenu.
4. Select Add to Build Path from the context menu.
5. Repeat these steps for each jar.

Google's provided Android toolset does not include dependency management support. However, through the use of third party tools, you can use Maven to manage dependencies and build your Android app. See the Spring for Android and Maven section for more information. Additional dependencies may be required, depending on which HTTP Message Converters you are using within RestTemplate. See the Message Converters section for more information.

Add the spring-android-rest-template artifact to your classpath:

org.springframework.android spring-android-rest-template ${spring-android-version}

The transitive dependencies are automatically imported by Maven, but they are listed here for clarity.

org.springframework.android spring-android-core ${spring-android-version}

2.4 RestTemplate Constructors

The four RestTemplate constructors are listed below. The default constructor does not include any message body converters. You must add a message converter when using the default constructor. If you would like to include a default set of message converters with a new RestTemplate instance, then you can pass true for the includeDefaultConverters parameter. For a list of default converters, see the HTTP Message Conversion section. Additionally, if you would like to specify a different ClientHttpRequestFactory then you can do so by passing it in to the requestFactory parameter.

RestTemplate[]; RestTemplate[boolean includeDefaultConverters]; RestTemplate[ClientHttpRequestFactory requestFactory]; RestTemplate[boolean includeDefaultConverters, ClientHttpRequestFactory requestFactory];

RestTemplate provides higher level methods that correspond to each of the six main HTTP methods. These methods make it easy to invoke many RESTful services and enforce REST best practices.

The names of RestTemplate methods follow a naming convention, the first part indicates what HTTP method is being invoked and the second part indicates what is returned. For example, the method getForObject[] will perform a GET, convert the HTTP response into an object type of your choice and return that object. The method postForLocation[] will do a POST, converting the given object into a HTTP request and return the response HTTP Location header where the newly created object can be found. In case of an exception processing the HTTP request, an exception of the type RestClientException will be thrown. This behavior can be changed by plugging in another ResponseErrorHandler implementation into the RestTemplate.

For more information on RestTemplate and it's associated methods, please refer to the API Javadoc

public void delete[String url, Object... urlVariables] throws RestClientException; public void delete[String url, Map urlVariables] throws RestClientException; public void delete[URI url] throws RestClientException;

public T getForObject[String url, Class responseType, Object... urlVariables] throws RestClientException; public T getForObject[String url, Class responseType, Map urlVariables] throws RestClientException; public T getForObject[URI url, Class responseType] throws RestClientException; public ResponseEntity getForEntity[String url, Class responseType, Object... urlVariables]; public ResponseEntity getForEntity[String url, Class responseType, Map urlVariables]; public ResponseEntity getForEntity[URI url, Class responseType] throws RestClientException;

public HttpHeaders headForHeaders[String url, Object... urlVariables] throws RestClientException; public HttpHeaders headForHeaders[String url, Map urlVariables] throws RestClientException; public HttpHeaders headForHeaders[URI url] throws RestClientException;

public Set optionsForAllow[String url, Object... urlVariables] throws RestClientException; public Set optionsForAllow[String url, Map urlVariables] throws RestClientException; public Set optionsForAllow[URI url] throws RestClientException;

public URI postForLocation[String url, Object request, Object... urlVariables] throws RestClientException; public URI postForLocation[String url, Object request, Map urlVariables]; public URI postForLocation[URI url, Object request] throws RestClientException; public T postForObject[String url, Object request, Class responseType, Object... uriVariables]; public T postForObject[String url, Object request, Class responseType, Map uriVariables]; public T postForObject[URI url, Object request, Class responseType] throws RestClientException; public ResponseEntity postForEntity[String url, Object request, Class responseType, Object... uriVariables]; public ResponseEntity postForEntity[String url, Object request, Class responseType, Map uriVariables] throws RestClientException; public ResponseEntity postForEntity[URI url, Object request, Class responseType] throws RestClientException;

public void put[String url, Object request, Object... urlVariables] throws RestClientException; public void put[String url, Object request, Map urlVariables] throws RestClientException; public void put[String url, Object request, Map urlVariables] throws RestClientException;

2.6 HTTP Message Conversion

Objects passed to and returned from the methods getForObject[], getForEntity[], postForLocation[], postForObject[] and put[] are converted to HTTP requests and from HTTP responses by HttpMessageConverter instances. The HttpMessageConverter interface is shown below to give you a better feel for its functionality.

public interface HttpMessageConverter { boolean canRead[Class clazz, MediaType mediaType]; boolean canWrite[Class clazz, MediaType mediaType]; List getSupportedMediaTypes[]; T read[Class