Instant Spring for Android Starter: Leverage Spring for Android to create RESTful and OAuth Android apps

The RestTemplate module is a port of the Java-based REST client RestTemplate, which initially appeared in 2009 in Spring for MVC. Like the other Spring template counterparts (JdbcTemplate, JmsTemplate, and so on), its aim is to bring to Java developers (and thus Android developers) a high-level abstraction of lower-level Java API; in this case, it eases the development of HTTP clients.

In its Android version, RestTemplate relies on the core Java HTTP facilities (HttpURLConnection) or the Apache HTTP Client. According to the Android device version you use to run your app, RestTemplate for Android can pick the most appropriate one for you. This is according to Android developers' recommendations.

RestTemplate for Android also supports gzip compression and different message converters to convert your Java objects from and to JSON, XML, and so on.

The goal of the Spring Android Auth module is to let an Android app gain authorization to a web service provider using OAuth (Version 1 or 2).

OAuth is probably the most popular authorization protocol (and it is worth mentioning that, it is an open standard) and is currently used by Facebook, Twitter, Google apps (and many others) to let third-party applications access users account.

Spring for Android Auth module is based on several Spring libraries because it needs to securely (with cryptography) persist (via JDBC) a token obtained via HTTP; here is a list of the needed libraries for OAuth:

While performing the OAuth workflow, we will also need the browser to take the user to the service provider authentication page, for example, the following is the Twitter OAuth authentication dialog:

SpringSource (the company behind Spring for Android) is very famous among Java developers. Their most popular product is the Spring Framework for Java which includes a dependency injection framework (also called an inversion of control framework). Spring for Android does not bring inversion of control to the Android platform.

In its very first release (1.0.0.M1), Spring for Android brought a common logging facade for Android; the authors removed it in the next version.

You can use the IDE to manually satisfy the dependencies (and their transitive dependencies). The alternative to manual dependency management is automatic project building with Maven. We will explain Maven building later in the section.

Eclipse is certainly the most popular IDE to develop Android apps; one of the reasons why it is so is because the Android Development Tools (ADT), maintained by Google, provides the Eclipse plugins to ease Android development (debugger, custom XML editors, and so on).

We need to perform the following steps to get started with Eclipse:

In the previous example, we only added two JARs to the libs folder; but if you need other dependencies, such as MessageConverters (to unmarshall JSON, XML responses), the Auth module, or any other existing libraries in your project, managing your dependencies will soon become a burden!

Maven can help you manage your dependencies (in a nutshell, you specify them in a file called pom.xml and it will get them from the Internet automatically, including their transitive dependencies) and much more: release operations, tests runs, header generation, and so on. Maven is a modular open source build tool with tons of plugins!

To begin with, let's add the m2e (Maven to Eclipse) plugin to Eclipse: like we did for the ADT plugin, open Help | Eclipse Marketplace and search for maven; choose Maven Integration for Eclipse, click on Install and acknowledge the dialogs; restart your IDE at the end of the process.

Installing Maven Integration for Eclipse

Now import the project named spring-for-android-first-example-maven into your workspace: you can either clone it from GitHub or unzip the examples.zip archive; and then, from Eclipse, click on File | Import… and choose Existing Maven Projects, and click on Next.

Import existing Maven project

Browse to the directory where you cloned or unzipped the project and click on the Next button:

Browse to your maven project

M2e will show you a list of m2e connectors needed to integrate the Maven-based project into your IDE (basically those connectors tell m2e how to generate and compile sources); click on Finish and accept the following dialogs; restart Eclipse.

The project should be imported just fine and you can deploy the project on your AVD in the same way you did with the previous project (right-click on the project, and choose Run as | Android application).

Let's have a look though at the pom.xml file (the only additional file compared to the previous project), right-clicking on it and choosing Open with… | Maven POM Editor; click on the pom.xml tab at the bottom of the view.

(...)<dependencies>
        <dependency>
            <groupId>com.google.android</groupId>
            <artifactId>android</artifactId>
            <version>4.0.1.2</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
          <groupId>org.springframework.android</groupId>
          <artifactId>spring-android-rest-template</artifactId>
          <version>${spring-android-version}</version>
        </dependency>
    </dependencies>
    <build>
        <finalName>${project.artifactId}</finalName>
        <sourceDirectory>src</sourceDirectory>
        <plugins>
            <plugin>
        <groupId>com.jayway.maven.plugins.android.generation2</groupId>
                <artifactId>android-maven-plugin</artifactId>
                <version>3.3.0</version>
                <extensions>true</extensions>
                <configuration>
                    <sdk>
                        <!-- platform or api level (api level 4 = platform 1.6)-->
                        <platform>15</platform>
                    </sdk>
                </configuration>
            </plugin>
        </plugins>
    </build>(...)

There you can see in the dependencies section; the Android platform and the Spring for Android RestTemplate artifact (no need to specify Spring for Android core! Remember, Maven automatically gets the transitive dependencies) and in the plugins section the Android-Maven plugin (which extends Maven for Android projects, thanks to the extensions=true attribute), configured to require Android 4.0.3 (API level 15).

Maven at its core is a command-line tool, and if you download and unzip Maven on your machine, you could go to the root directory of the Maven project (where pom.xml resides) and type the Maven command with different goals:

Now we are ready to hack together some richer Spring for Android based apps!

In the previous section, we already used a message converter: StringHttpMessageConverter. Each message converter supports reading from and writing to certain media types (often referred to as MIME types); StringHttpMessageConverter supports reading all kinds of documents (MIME */*) and writing to text (MIME text/plain). Let's discover more complex message converters.

MappingJacksonHttpMessageConverter

JSON messages are very frequent among REST web services. Originally designed for the JavaScript language (JavaScriptObjectNotation); they're lightweight and human readable as well.

Ifconfig.me can return a JSON response, if you use this URL : http://ifconfig.me/all.json.

In the code from our first example, let's replace StringHttpMessageConverter with MappingJacksonHttpMessageConverter:

AsyncTask<String, Void, IfConfigMeJson> simpleGetTask =  
  new AsyncTask<String, Void, IfConfigMeJson>() {
  @Override
  protected IfConfigMeJson doInBackground(String... params) {
    String url = params[0];
    RestTemplate restTemplate = new RestTemplate();
    MappingJacksonHttpMessageConverter jacksonConverter = 
         new MappingJacksonHttpMessageConverter();
    restTemplate.getMessageConverters().add(jacksonConverter);
    return restTemplate.getForObject(url,
           IfConfigMeJson.class);
  }
  
  @Override
  protected void onPostExecute(IfConfigMeJson result) {
    String resultAsString =  new StringBuilder()
                      .append("Your current IP is : ")
                      .append(result.getIpAddr()).toString();
    resultTextView.setText(resultAsString );
  }

};

String url = "http://ifconfig.me/all.json";
//triggers the task
simpleGetTask.execute(url);

As you can see, we also introduced a model class named IfConfigMeJson: this class defines the mapping between the JSON messages properties ({"connection":"keep-alive","ip_addr":"70.30.43.43", [..]}) and a POJO (Plain Old Java Object: a simple class with member variables and their accessors), so that we can easily access each property of the response (in the following example: result.getIpAddr()) in our Java code:

public class IfConfigMeJson {
  private String connection;
  @JsonProperty("ip_addr")
  private String ipAddr;
  public String getConnection() {
    return connection;
  }
  public void setConnection(String connection) {
    this.connection = connection;
  }
  public String getIpAddr() {
    return ipAddr;
  }
  public void setIpAddr(String opAddr) {
    this.ipAddr = opAddr;
  }

Note

Jackson automatically matches JSON properties with Java fields as long as they are named identically (CamelCase in Java, underscore for JSON). You've certainly noticed that we mapped the JSON property ip_addr with the field ipAddr, to respect Java naming conventions, thanks to Jackson's @JsonProperty annotation before the field definition. On a side note, we could have declared the fields of the class as public and have the accessors removed.

When you run the application, you will only see the following screenshot:

The app using MappingJacksonHttpMessageConverter

In this section we added a dependency to jackson-mapper-asl in our pom.xml file:

<dependency>
<groupId>org.codehaus.jackson</groupId>
  <artifactId>jackson-mapper-asl</artifactId>
  <version>${jackson-version}</version>
</dependency>

Note

There is another JSON message converter available, GsonHttpMessageConverter, using the Google Gson library instead of Jackson, that can be used alternatively.

AsyncTask<String, Void, IfConfigMeXml> simpleGetTask =  
   new AsyncTask<String, Void, IfConfigMeXml>() {
   @Override
   protected IfConfigMeXml doInBackground(String... params) {
      String url = params[0];
RestTemplate restTemplate = new RestTemplate();
      SimpleXmlHttpMessageConverter xmlConverter = 
           new SimpleXmlHttpMessageConverter();
      restTemplate.getMessageConverters().add(xmlConverter);
      return restTemplate.getForObject(url, IfConfigMeXml.class);
   }

   @Override
   protected void onPostExecute(IfConfigMeXml result) {
       String resultAsString =  new StringBuilder()
                  .append("Your current IP is : ")	
                  .append(result.getIpAddr()).toString();
       resultTextView.setText(resultAsString );
   }

};

String url = "http://ifconfig.me/all.xml";

<info>
<forwarded/>
<ip_addr>70.43.43.43</ip_addr>
[...]
</info>

@Root (name="info")
public class IfConfigMeXml {

  @Element(required=false)
  private String forwarded;

  @Element(name="ip_addr")
  private String ipAddr;
  [...]
}

<dependency>
  <groupId>org.simpleframework</groupId>
  <artifactId>simple-xml</artifactId>
  <version>${simple-version}</version>
  <exclusions>
    <!-- StAX is not available on Android -->
    <exclusion>
      <artifactId>stax</artifactId>
      <groupId>stax</groupId>
    </exclusion>
    <exclusion>
      <artifactId>stax-api</artifactId>
      <groupId>stax</groupId>
    </exclusion>
    <!-- Provided by Android -->
    <exclusion>
      <artifactId>xpp3</artifactId>
      <groupId>xpp3</groupId>
    </exclusion>
  </exclusions>
</dependency>

RssChannelHttpMessageConverter

This message converter is about parsing RSS feeds; as usual we are going to inject it to our RestTemplate instance, but this time we will read entries from a blog feed.

final WebView resultTextView = (WebView) findViewById(R.id.result_text);
AsyncTask<String, Void, Channel> simpleGetTask =  new AsyncTask<String, Void, Channel>() {
   @Override
   protected Channel doInBackground(String... params) {
      RestTemplate restTemplate = new RestTemplate();
      // Configure the RSS message converter.
       RssChannelHttpMessageConverter rssChannelConverter = new RssChannelHttpMessageConverter();
      rssChannelConverter.setSupportedMediaTypes(
         Collections.singletonList(MediaType.TEXT_XML));

        // Add the RSS message converter to the RestTemplate instance
        restTemplate.getMessageConverters().add(rssChannelConverter);

      // Make the HTTP GET request on the url (params[0]), marshaling //the response to a String
      return restTemplate.getForObject(params[0], Channel.class);
   }

   @Override
   protected void onPostExecute(Channel result) {
      //get the latest article from the blog
      Item item = (Item) result.getItems().get(0);

      // load the content of the article into the WebView
      resultTextView.loadData(item.getContent().getValue(), "text/html", "UTF-8");
   }
};
String url = "http://blog.dahanne.net/feed/";

We don't have to create a POJO mapping class here since the result will always be a Channel – a class providing us with methods to access the different property of the feed: items, language, published date, and so on. In this example, we only read the content of the first item – the latest article from my blog!

The feed looks as follows:

<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
<channel>
   <title>Anthony Dahanne's blog</title>
   <description>A blog</description>
   [...]
   <item>
      <title>Article 1</title>
      <description>content of the article</description>
      [...]
   </item>
   [...]
</channel>
</rss>

And the result on the device is as follows:

The content of the first item of an RSS feed

Note

You may have noticed that I switched the previous TextView for a WebView, capable of interpreting HTML code such as hyperlinks.

RssChannelHttpMessageConverter does not have default supported types, that's why we added the media type text/xml as a supported type.

Note

We had to add a dependency on the Android ROME Feed Reader for this RSS feed example; this library is not published on Maven Central, which means we also had to declare the repository where its artifacts are deployed to.

<dependency>
   <groupId>com.google.code.android-rome-feed-reader</groupId>
   <artifactId>android-rome-feed-reader</artifactId>
   <version>${android-rome-version}</version>
</dependency>


<repositories>
   <repository>
      <id>android-rome-feed-reader-repository</id>
      <name>Android ROME Feed Reader Repository</name>
      <url>https://android-rome-feed-reader.googlecode.com/svn/maven2/releases</url>
   </repository>
</repositories>

To save bandwidth during transfers, as part of each request you can tell the server that you support gzip encryption. If the server supports gzipping the responses, it will do so.

Spring for Android RestTemplate, relies on Android java.net.HttpURLConnection since Gingerbread (2.3), which defaults in sending the Accept-Encoding : gzip header; so gzip compression is on by default.

Otherwise, you just need to specify in the headers of the request that you can support gzip. Let's have a look at a concrete example – the Jackson example where this time we only show the client supported encoding mechanism:

@Override
protected IfConfigMeJson doInBackground(String... params) {

   HttpHeaders requestHeaders = new HttpHeaders();
   requestHeaders.setAcceptEncoding(ContentCodingType.IDENTITY);
// Add the gzip Accept-Encoding header   
//requestHeaders.setAcceptEncoding(ContentCodingType.GZIP);
   HttpEntity<?> requestEntity = 
        new HttpEntity<Object>(requestHeaders);
   RestTemplate restTemplate = new RestTemplate();
   MappingJacksonHttpMessageConverter jacksonConverter = 
        new MappingJacksonHttpMessageConverter();
   restTemplate.getMessageConverters().add(jacksonConverter);
   ResponseEntity<IfConfigMeJson> response = 
        restTemplate.exchange(params[0], HttpMethod.GET, 
                      requestEntity, IfConfigMeJson.class);
   return response.getBody();
}

Using Identity, we declare that we do not support anything else other than raw text.

Did you notice that instead of using getForObject(url,Pojo.class) we used exchange(url,GET,requestEntity,Pojo.class)? The exchange() method is a more versatile method that allows for customization of the request.

Let's have a look at the request/response exchanged during the execution of this code:

This authentication scheme is, as its name implies it, very basic and unsecured. You just provide a username and a password to access a realm (usually a portion of a website).

As we did for the encoding, we can provide the credentials through a header: the username and the password will be Base64-encoded.

As an example, we'll try to access a web page that displays Hello World; provided you sent the right credentials. The page is http://restfulapp.appspot.com/helloworld, and the credentials are username – s4a and password – s4a (you can try it in your web browser).

Let's try to access this page with Spring for Android's RestTemplate!

AsyncTask<String, Void, String> simpleGetTask =  new AsyncTask<String, Void, String>() {
   @Override
   protected String doInBackground(String... params) {
      // Set the credentials for creating a Basic Auth request
      HttpAuthentication authHeader = 
          new HttpBasicAuthentication("s4a", "s4a");
      HttpHeaders requestHeaders = new HttpHeaders();
      requestHeaders.setAuthorization(authHeader);
      HttpEntity<?> requestEntity = 
          new HttpEntity<Object>(requestHeaders);

      RestTemplate restTemplate = new RestTemplate();

      restTemplate.getMessageConverters()
              .add(new StringHttpMessageConverter());

      try {
          // Make the GET request to the Basic Auth protected URL
          ResponseEntity<String> response = 
                restTemplate.exchange(params[0], HttpMethod.GET, 
                       requestEntity, String.class);
          return response.getBody();
      } catch (HttpClientErrorException e) {
         // Handle 401 Unauthorized response
         Log.e("MainActivity",e.getLocalizedMessage(),e);
         return "Wrong credentials";
      }
   }

   @Override
   protected void onPostExecute(String result) {
      // executed by the UI thread		 
      resultTextView.setText(result);
   }

};

The way we set Accepted-Encoding in the previous example, we set an HttpBasicAuthentication header to the RestTemplate headers.

Let's have a look at the request/response exchanged during the execution of this code:

We will cover a better way to authenticate and also authorize a user and the user's app in the next section: Quick Start – OAuth.

Let's study the case of the RESTful recipe app: an Android app to interact with a RESTful service to create, update, read, and delete recipes.

A recipe is somewhat simple – it is a POJO with the following fields:

The online web app that we will use as our backend service, is a JAX-RS (the JEE specification for REST services) application based on Jersey (the reference JAX-RS implementation library), and deployed on Google App Engine – it could have been written in Ruby, Python, or any other language.

RecipeList activity: listing all recipes stored on the server

When the user launches the app, the first thing he wants to see is the list of the available recipes.

This activity uses ListView, backed with ListAdapter to display them to the user.

But first, it needs to get them from the server:

• We need a model (Recipe.java):

  public class Recipe {
  
     private Long id;
     private String title;
     private String description;
     private String type;
     private String author;
  }

• And a RestTemplate instance nested in an AsyncTask:

  private class GetRecipesTask extends RecipeAbstractAsyncTask <Void, Void, List<Recipe>> {
  
     @Override
     protected void onPreExecute() {
        showProgressDialog("Loading recipes. Please wait...");
     }
  
     @Override
     protected List<Recipe> doInBackground(Void... params) {
        HttpHeaders requestHeaders =  
                 prepareHeadersWithMediaTypeAndBasicAuthentication();
  
        // Populate the headers in an HttpEntity object		
        HttpEntity<?> requestEntity = 
                 new HttpEntity<Object>(requestHeaders);
  
        // Create a new RestTemplate instance
        RestTemplate restTemplate = new RestTemplate();
        restTemplate.getMessageConverters()
  .add(new MappingJacksonHttpMessageConverter());
  
        try {
           // Perform the HTTP GET request
           ResponseEntity<Recipe[]> responseEntity = 
              restTemplate.exchange(
                 "http://www.restfulapp.appspot.com/rest/recipes/",
                 HttpMethod.GET, requestEntity,
     Recipe[].class);
           return Arrays.asList(responseEntity.getBody());
        }
        catch (RestClientException e) {
           Log.e(TAG, e.getMessage(), e);
           exception = e;
           return null;
        }
     }
  
     @Override
     protected void onPostExecute(List<Recipe> result) {
        dismissProgressDialog();
        if(result != null) {
           recipes = result;
        } else {
           String message = exception != null ? 
              exception.getMessage() : "unknown reason";
           Toast.makeText(RecipesList.this, 
              "A problem occurred during the reception of all recipes
              : " +message , Toast.LENGTH_LONG).show();
            recipes = new ArrayList<Recipe>();
        }
        ListAdapter adapter = new RecipeAdapter(RecipesList.this, 
           R.layout.recipeslist_item, recipes ) ;
        setListAdapter(adapter );
     }
  }

This task will get executed every time we need to get an updated list of recipes:

• When the activity is created (or resumed): onResume()

• When we're back from a successful update operation: onActivityResult()

You may have noticed that this AsyncTask extends RecipeAbstractAsyncTask, a class that defines an exception, and a utility method, prepareHeadersWithMediaTypeAndBasicAuthentication():

protected HttpHeaders prepareHeadersWithMediaTypeAndBasicAuthentication() {
      HttpHeaders requestHeaders = new HttpHeaders();
      List<MediaType> acceptableMediaTypes = new ArrayList<MediaType>();
      acceptableMediaTypes.add(MediaType.APPLICATION_JSON);
      requestHeaders.setAccept(acceptableMediaTypes);
      HttpAuthentication authHeader = new HttpBasicAuthentication("s4a", "s4a");
      requestHeaders.setAuthorization(authHeader);
      return requestHeaders;
   }

As its name implies, it prepares the request headers to include the Basic authentication needed, and the desired MediaType object from the server.

Back to GetRecipesTask: we prepare the request headers, we create a new RestTemplate instance – configured to use Jackson to (un) serialize the messages, and we perform the GET request:

// Perform the HTTP GET request
               ResponseEntity<Recipe[]> responseEntity = restTemplate.exchange(getString(R.string.recipe_resource_url), HttpMethod.GET, requestEntity, Recipe[].class);

Note

The R.string.resource_url value is defined in strings.xml and is defined to be equal to: http://www.restfulapp.appspot.com/rest/recipes/.

Since we want to get a list of recipes, the type given to the ResponseEntity object is an array.

Another important thing to note is that the exception handler: RestClientException is, unlike its name, a wrapping server and client exception. If you want to tell your user what went wrong, you'd better catch this exception and keep it until you're back in the UI thread when executing the code in the onPostExecute() method.

Note

Note that RestClientException is a subclass of RuntimeException, that's why you don't need to catch it explicitly. If you don't though, this exception could kill your activity if it is thrown.

Talking about the user interface, this task uses its pre-and post-execute methods to keep the user updated about the status of the loading by using ProgresDialogs and Toasts.

Note

It can be useful to manually debug a REST resource, from outside your application; the cURL application (downloadable at http://curl.haxx.se/download.html) is probably the most popular tool to do so.

For each HTTP request evoked in this section, I will now include its matching cURL command line.

curl --user s4a:s4a  -H "Accept: application/json" -i http://www.restfulapp.appspot.com/rest/recipes 
[{"id":0,"title":"Montreal's Poutine","description":"French fries are covered with fresh cheese curds, and topped with brown gravy.","type":"MAIN_DISH","author":"Anthony"},{"id":1,"title":"a title","description":"a description","type":"a type","author":"an author"}]

An overview of the RecipesList activity

RecipeEditor activity

This activity is responsible for getting, updating, creating, and deleting the recipes.

The RecipeEditor activity in update mode

• GETting a recipe

  When a user taps on the create icon of the RecipeList activity, or on one of the recipe title, he/she is directed to the RecipeEditor activity.

  If the user wants to create a new recipe, he/she will see empty fields, but if he/she wants to see a recipe, they'll first get it from the server before filling the fields; thanks to the internal GetRecipeTask :

  // Perform the HTTP GET request
  Log.i(TAG,"Getting the recipe with id : "+params[0] + " : " +url + params[0]);
  ResponseEntity<Recipe> responseEntity = restTemplate.exchange(url + params[0], HttpMethod.GET, requestEntity,	Recipe.class);
  return responseEntity.getBody();

  Nothing really new here, we want to get a single recipe, identified by its ID (params[0]).

  curl --user s4a:s4a  -H "Accept: application/json" -i http://www.restfulapp.appspot.com/rest/recipes/0
  {"id":0,"title":"Montreal's Poutine","description":"French fries are covered with fresh cheese curds, and topped with brown gravy.","type":"MAIN_DISH","author":"Anthony"}

• PUTting a recipe

  To update one recipe, we must request the recipe resource with the PUT HTTP verb.

  For that, we have, once again, a dedicated AsyncTask: UpdateRecipeTask, that will instantiate a RestTemplate instance, carrying the updated recipe (as soon as the user presses the Save button, we call the updateNote() method that syncs the content of the view, with the model of the current recipe).

  // Create a new RestTemplate instance
  RestTemplate restTemplate = new RestTemplate();
  restTemplate.getMessageConverters()
     .add(new MappingJacksonHttpMessageConverter());
  
  // Populate the headers in an HttpEntity object HttpEntity<Recipe> requestEntity = new HttpEntity<Recipe>(recipe,requestHeaders);
  try {
     // Perform the HTTP PUT request
     Log.i(TAG,"Updating the recipe with id : "
        +recipe.getId() + " : " + url);
     ResponseEntity<Void> responseEntity = 
        restTemplate.exchange(url, HttpMethod.PUT, requestEntity,
        Void.class);
     if(responseEntity.getStatusCode() != HttpStatus.OK) {
        throw new HttpServerErrorException(
           responseEntity.getStatusCode());
     }
  }
  catch (RestClientException e) {
     Log.d(TAG, e.getMessage(), e);
     exception = e;
  }

  You can see the real important part here is RequestEntity, that wraps our recipe: RestTemplate will pass it along to Jackson that will convert it into a JSON string.

  If the server does not respond with the HTTP Status 200 (OK), we can consider something went wrong and keep the exception for the user interface.

  curl --user s4a:s4a  -H "Accept: application/json" -H "Content-type: application/json"  -X PUT -d '{"id":"0", "title":"a title","description":"a description","type":"a type","author":"an author"}'  -i http://www.restfulapp.appspot.com/rest/recipes/

• POSTing a recipe

  To create one recipe, we must request the recipe resource with the POST HTTP verb.

  In the REST literature, you will also read about the usage of the PUT HTTP verb to create an entity too; but on one condition though – you would have to provide the ID (so that several PUT in a row do not change the resource state. PUT is idempotent just like GET and DELETE, and just as unsafe as DELETE and POST).

  Note

  In our case, we create a new resource, so POST reflects well our intention.

  Let's have a look at CreateRecipeTask, which is very similar to UpdateRecipeTask:

  // Populate the headers in an HttpEntity object 
  HttpEntity<Recipe> requestEntity = 
     new HttpEntity<Recipe>(recipe,requestHeaders);
  try {
     // Perform the HTTP POST request
     Log.i(TAG,"Posting the recipe with id : "
        +recipe.getId() + " : to " +url);
     ResponseEntity<Void> responseEntity = 
        restTemplate.exchange(url, HttpMethod.POST, requestEntity,
        Void.class);
     if(responseEntity.getStatusCode() != HttpStatus.CREATED) {
        throw new HttpServerErrorException(
           responseEntity.getStatusCode());
     }
  }
  catch (RestClientException e) {
     Log.d(TAG, e.getMessage(), e);
     exception = e;
  }
  return null;

  Some interesting things to notice: the recipe does not have any ID set since the user is creating a recipe from nothing. The web service will assign an ID to this recipe (and should return the URI of the created resource); and the expected status is not 200, but 201 (HttpStatus.CREATED).

  curl --user s4a:s4a  -H "Accept: application/json" -H "Content-type: application/json"  -X POST -d '{"title":"a title","description":"a description","type":"a type","author":"an author"}'  -i http://www.restfulapp.appspot.com/rest/recipes/

• DELETing a recipe

  To delete one recipe, we must request the recipe resource with the DELETE HTTP verb.

  The AsyncTask named DeleteRecipeTask is similar to GetRecipeTask in the way that it only requires the ID of the recipe to be appended to the resource URI (there is no need to carry the whole recipe as we did with PUT and POST).

  try {
     // Perform the HTTP DELETE request
     Log.i(TAG,"Deleting the recipe with id : "
        +recipe.getId() + " : from " +url +recipe.getId() );
     ResponseEntity<Void> responseEntity = 
        restTemplate.exchange(url+recipe.getId(), 
        HttpMethod.DELETE, requestEntity,	Void.class);
     if(responseEntity.getStatusCode() != HttpStatus.NO_CONTENT) {
        throw new HttpServerErrorException(
        responseEntity.getStatusCode());
     }
  }
  catch (RestClientException e) {
     Log.d(TAG, e.getMessage(), e);
     exception = e;
  }

  This request expects to have a response with a 204 HTTP code, meaning the request was a success, but there is nothing to return (HttpStatus.NO_CONTENT).

  Note

  HTTP code 200 would have been fine as a response to a successful DELETE request.

  Check with your web service documentation (or better, experiment with cURL for example) to make the best assumptions about what is supposed to return a web service.

  curl --user s4a:s4a  -H "Accept: application/json" -X DELETE   -i http://www.restfulapp.appspot.com/rest/recipes/1

You may have heard about this project available at https://github.com/excilys/androidannotations/ that aims at reducing the amount of code needed to inject views, activities, providers, services, and so on in an Android app.

The project leaders have decided to use Spring for Android's RestTemplate as the REST client library backing the REST annotations.

So, along with @Eactivity (to allow an activity to use Android annotations), @ViewById (to inject your views), you have @Get, @Post, @Put, and so on.

Let's have a look at how we can benefit from Android annotations with the JSON example (getting the IP address from Ifconfig.me).

@EActivity(R.layout.activity_main)
public class MainActivity extends Activity {

   private IfConfigMeJson all;

   //inject the view to the activity layout
    @ViewById(R.id.result_text)
    TextView resultTextView;
    
    //inject the Rest service that wraps RestTemplate
    @RestService
   IfConfigMeRestClient restClient;
    
    //Use the Rest Service in a background thread
    @Background
    @AfterInject
    void getAllInfo() {
       all = restClient.getAll();
    }
    
    //wait a few seconds for the service to finish
   @UiThread(delay = 5000)
   @AfterViews
   void afterViews() {
      resultTextView.setText("Your IP is : "+all.getIpAddr());
   }

}

There is definitely less code, right?

You may have noticed though that we are using a new class named IfConfigMeRestClient:

@Rest(rootUrl = "http://ifconfig.me", converters = 
      { MappingJacksonHttpMessageConverter.class })
public interface IfConfigMeRestClient {

   @Get("/all.json")
   @Accept(MediaType.APPLICATION_JSON)
   IfConfigMeJson getAll();

}

This class configures RestTemplate providing the converter class, the HTTP verb used, the mapping class (IfConfigMeJson), and the accepted media types.

Android annotations provides a good level of support to Spring for Android's RestTemplate (see https://github.com/excilys/androidannotations/wiki/Rest-API for the list of RestTemplate based annotations), and I suggest you try it to see if you prefer using it or not in your Spring for Android based project.

Have you ever noticed those Login with Facebook or Login with Google buttons on some websites (such as Deezer.com, StackOverFlow.com, and so on), or have you ever had a third-party Twitter app on an Android device (such as Twicca) request your Twitter credentials?

All those websites and apps use OAuth to get access to your data:

Usually if a website or app creator wants to benefit from a service providing OAuth authorization, he/she has to register it against the OAuth service provider (Google, Facebook, and so on) which in turn will give him/her a Client ID and Client secret value:

Using the Google API Console to register a new application and associate it with a client ID and a client secret

Let's discover how this client ID and client secret enables the app to access the user's data.

An Android app (or any other installed app) relies on an OAuth 2.0 service provider such as Google. Let's have a look at the workflow of the OAuth authorization process in the following five simple steps:

The OAuth workflow to access Google UserInfo Service, from https://developers.google.com/accounts/docs/OAuth2

The Spring for Android Auth module supports both OAuth 1.0a and OAuth 2.0.

In a nutshell:

The Spring for Android Auth module depends on the following:

The Auth module itself defines cryptography and SQL classes for Android (to enable you to persist the authorization tokens securely to a SQLite Android database).

We are going to build an Android app displaying information about a Google user: we are going to use Spring for Android Auth of course, but more importantly Spring Social and Spring Social Google.

Let's have a look at the pom.xml file of this project, in particular the inclusion of Spring Social Google:

<dependency>
  <groupId>org.springframework.social</groupId>
  <artifactId>spring-social-google</artifactId>
  <version>1.0.0.M1</version>
  <exclusions>
    <!-- Exclude in favor of Spring Android RestTemplate -->
    <exclusion>
      <artifactId>spring-web</artifactId>
      <groupId>org.springframework</groupId>
      </exclusion>
      <exclusion>
      <artifactId>spring-core</artifactId>
      <groupId>org.springframework</groupId>
    </exclusion>
  </exclusions>
</dependency>
[...]
<repository>
  <id>spring.social.google</id>
  <name>Spring Social Google</name>
  <url>https://github.com/GabiAxel/maven/raw/master/</url>
</repository>

You will notice here (in the repository section), this module is not hosted by Spring Source, because it is actually a community project not endorsed by Spring Source.

Now let's have a look at the AndroidManifest.xml file:

[...]
<application
    android:name=".MainApplication"
    android:icon="@drawable/app_notes"
    android:label="@string/app_name" >
    <activity
        android:name=".GoogleActivity"
        android:label="@string/title_main" >
        [...]
    </activity>
    <activity
        android:name=".GoogleWebOAuthActivity"
        android:excludeFromRecents="true"
        android:noHistory="true" />
    <activity android:name=".GoogleProfileActivity" />
</application>

For the first time in our examples, we are going to use an Application class, named here MainApplication.

This class will be used to prepare the two most important factories of our app (they will be accessed in all the activities): ConnectionFactoryRegistry and ConnectionRepository:

public class MainApplication extends Application {
  private ConnectionFactoryRegistry connectionFactoryRegistry;
  private SQLiteOpenHelper repositoryHelper;
  private ConnectionRepository connectionRepository;

  // ***************************************
  // Application Methods
  // ***************************************
  @Override
  public void onCreate() {
    // create a new ConnectionFactoryLocator and populate it with Google ConnectionFactory
    this.connectionFactoryRegistry = new ConnectionFactoryRegistry();
    this.connectionFactoryRegistry.addConnectionFactory(new GoogleConnectionFactory(getClientId(),
        getClientSecret()));

    // set up the database and encryption
    this.repositoryHelper = new SQLiteConnectionRepositoryHelper(this);
    this.connectionRepository = new SQLiteConnectionRepository(this.repositoryHelper,
        this.connectionFactoryRegistry, AndroidEncryptors.text("password", "5c0744940b5c369b"));
  }

As you can see, in the onCreate() method we initialize:

Let's have a look at the main activity of that project, GoogleActivity that will be launched at startup:

@Override
public void onStart() {
  super.onStart();
  if (isConnected()) {
    showGoogleOptions();
  } else {
    showConnectOption();
  }
}


private boolean isConnected() {
  return connectionRepository.findPrimaryConnection(Google.class) != null;
}

This activity will display a list of entries related to the user profile if he/she is connected or just a Connect button if the user is not connected yet (since GoogleConnectionFactoryRegistry is persisted in a database, just looking up a connection of type Google in ConnectionRepository is enough to know whether or not the access token is already fetched).

The GoogleActivity if the user has not yet logged in

So, in the case that we are not connected, taping on Connect will call displayGoogleAuthorization() which will launch GoogleWebOAuthActivity.

GoogleWebOAuthActivity is certainly the most important activity of this app. It is responsible for the OAuth 2.0 authentication and authorization.

@Override
public void onCreate(Bundle savedInstanceState) {
  super.onCreate(savedInstanceState);

  //javascript is mandatory
  getWebView().getSettings().setJavaScriptEnabled(true);

  // Using a custom web view client to capture the access token
  getWebView().setWebViewClient(new GoogleOAuthWebViewClient());

  this.connectionRepository = getApplicationContext().getConnectionRepository();
  this.connectionFactory = getApplicationContext().getGoogleConnectionFactory();
}

@Override
public void onStart() {
  super.onStart();

  // display the Google authorization page
  getWebView().loadUrl(getAuthorizeUrl());
}

// ***************************************
// Private methods
// ***************************************
private String getAuthorizeUrl() {
  String redirectUri = getString(R.string.google_oauth_callback_url);
  String scope = getString(R.string.google_scope);

  // Generate the Google authorization url to be used in the browser 
  OAuth2Parameters params = new OAuth2Parameters();
  params.setRedirectUri(redirectUri);
  params.setScope(scope);
  return this.connectionFactory.getOAuthOperations().buildAuthorizeUrl(GrantType.AUTHORIZATION_CODE, params);
}

When this activity is created, it configures the associated WebView (you will notice this activity extends AbstractWebViewActivity that injects a Chrome Browser instance into a WebView) to accept JavaScript ( the service provider and Google OAuth 2.0 requires JavaScript to authenticate the user) and injects a custom WebViewClient object that we will use to intercept OAuth flows (more on that in a moment).

Then, when the activity starts, we ask the WebView (the embedded Chrome browser) to request the authorization code for this app (see step 1 of The OAuth dance section).

This request is built using a callback URL, the scope of the authorizations needed for the app, and the client ID and secret (those two were already given to Spring OAuth when we created ConnectionFactoryRegistry).

<resources>
    <string name="google_app_id">508046100884-o6jgcn8e7c1g5gklhc8gibr80ouio8df.apps.googleusercontent.com</string>
    <string name="google_app_secret">RuUyrF5qoGYWTFm1r_o8Gs4F</string>
    <string name="google_oauth_callback_url">http://localhost</string>
    <string name="google_scope">https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/plus.me</string>
</resources>

If the user has not yet authenticated to any Google web services from his device, he/she should see a dialog inviting him/her to authenticate:

This dialog only appears if the user has not yet been authenticated to any Google services on his device

In all cases though, the user will see this authorization dialog which lists all the scopes the app has requested:

Google OAuth 2.0 service provider authorization dialog

Once the user accepts the requested authorizations, GoogleWebOAuthActivity will detect that the web client is being redirected to a localhost (the callback URI), with the authorization code:

private class GoogleOAuthWebViewClient extends WebViewClient {

  private static final String LOCALHOST = "localhost";
  private static final String CODE = "code";

  /*
   * The WebViewClient has another method called shouldOverridUrlLoading which does not capture the javascript 
   * redirect to the success page. So we're using onPageStarted to capture the url.
   */
  @Override
  public void onPageStarted(WebView view, String url, Bitmap favicon) {
    // parse the captured url
    Uri uri = Uri.parse(url);
     // log the url : very interesting for debugging the OAuth workflow
    Log.d(TAG, url);

    /*
     * The WebViewClient is launched to load an URL from the provider that will ask the user whether or not he accepts our app to access his data.
     * Once the provider successfully gets the approval from the user, it will redirect this WebViewClient to the callback_uri, with a query parameter named "code" : this is the authorization code
     */
    String host = uri.getHost();
    String code = uri.getQueryParameter(CODE);


    // The WebViewClient is redirected to the callback_uri, let's trade the authorization code for the access token
    if (LOCALHOST.equals(host)) {
      if(!exchangeAuthorizationCodeForAccessToken.getStatus().equals(AsyncTask.Status.RUNNING)) {
        exchangeAuthorizationCodeForAccessToken.execute(code);
        Toast.makeText(getApplicationContext(), "Redirecting you to the app main activity", Toast.LENGTH_LONG).show();
        //preparing to quit this activity for the main activity
        getWebView().setVisibility(View.INVISIBLE);
      }
    }
  }
}

exchangeAuthorizationCodeForAccessToken.execute(code) will execute the following AsyncTask (we are going to send back the authorization code from our app, using RestTemplate, relying on Java UrlConnection, so we need to code this call from a background thread):

private AsyncTask<String, Void, Void> exchangeAuthorizationCodeForAccessToken =  new AsyncTask<String, Void, Void>() {
  
  private Exception exception;

  @Override
  protected Void doInBackground(String... params) {
    // executed by a background thread
    //params[0] should contain the authorization code
    try {
      AccessGrant exchangeForAccess = connectionFactory.getOAuthOperations().exchangeForAccess(params[0], getString(R.string.google_oauth_callback_url), null);
      Connection<Google> connection = connectionFactory.createConnection(exchangeForAccess);
      connectionRepository.addConnection(connection);
    } catch (DuplicateConnectionException e) {
      Log.e(TAG,"something went wrong when adding the accessToken to the connection repository",e);
      exception = e;
    } catch (Exception e) {
      Log.e(TAG,"something went wrong when adding the accessToken to the connection repository",e);
      exception = e;
    }
    return null;
  }

  @Override
  protected void onPostExecute(Void result) {
    // executed by the UI thread once the background thread is done getting the result
    if(exception != null) {
      Toast.makeText(getApplicationContext(), exception.getMessage(), Toast.LENGTH_LONG).show();
    }
      // we go back to the main activity to display the options
      displayGoogleOptions();
  }

};

Once the exchangeForAccess method is called, we retrieve the user token and we persist it in the ConnectionRepository class.

Our app is finally authorized to access the user's Google profile!

The GoogleActivity if the user has not yet logged in

If the user clicks on Profile, he will launch GoogleProfileActivity, from which, as you may expect, we get the user profile.

To do so we are using an AsyncTask, named FetchProfileTask, that will hit two Google web services: UserOperations (to read the main profile of the user and his/her profile picture) and PersonOperations (to read his/her Google+ profile, here we will just access the about me description):

@Override
protected LegacyGoogleProfile doInBackground(Void... params) {

    LegacyGoogleProfile userProfile = google.userOperations().getUserProfile();
    aboutMe = google.personOperations().getGoogleProfile().getAboutMe();
    profileBitmap = BitmapFactory.decodeStream(new URL(userProfile.getProfilePictureUrl()).openConnection().getInputStream());
    return userProfile;

}

This information is then injected into the view:

The GoogleProfileActivity displaying the user profile picture, "about me" description and some profile info