Spring Android and Maven (Part 1)

Posted on December 17th, 2010 by Roy Clarkson in Android , Spring .

We recently announced the M1 release of Spring Android , and with that release some questions have arisen around how to build an Android application utilizing the Spring Android Rest Template and Spring Android Commons Logging libraries. Google provides several methods for compiling an Android application, including SDK command line tools, and the ADT (Android Development Tools) Plugin for Eclipse. Unfortunately, neither of these methods includes integrated dependency management support.

Overview

As Java developers we have come to appreciate tools such as Maven and Gradle for managing external dependencies. While traditional Java applications run in a JVM, Android applications run on the Dalvik virtual machine.  The Dalvik VM executes files in the Dalvik Executable (.dex) format.  It runs classes compiled by a Java language compiler that have been transformed into the .dex format.  A build tool will need to support this process if it is going to be able to compile a compatible Android application with dependencies.

There are basically two options for including external libraries in your Android application. The first is to manually copy the jars into the libs directory within your project and update the classpath within Eclipse. This is the simplest solution, and the one most supported by the ADT plugin. The disadvantage is that you have to manage the dependencies manually. Alternatively, a third party plugin such as the Maven Android Plugin can be utilized to automatically include the dependencies from a Maven repository.

In this post I will walk through the process of using the Android command line tools, Maven, the Maven Android Plugin, and Android Maven artifacts to compile a sample application that utilizes the Spring Android libraries, and deploy it to the Android emulator. After you have configured Maven, it is easy to create a build, deploy it to the emulator, run tests, and package the app for deployment to the Android Market. Before running the sample code, we will first highlight the configuration settings necessary in the pom.xml. The components used in this example are listed below.

• SpringSource Tool Suite 2.5.2 (Eclipse 3.6.1)
• Android SDK Revision 9
• Maven Android Plugin 2.8.4

Maven Configuration

This section covers the parts of a pom.xml that are required for developing with Spring Android and the Maven Android Plugin.

Maven Android Plugin

In order to use Maven to build an Android application, you will need to configure the Maven Android Plugin within your pom.xml file. Android applications are deployed to the device as an apk file, not a jar. You must specify this in the the packaging configuration.

To configure the Maven Android and Maven Compiler Plugins in the build task, set the sdk platform to the desired level. In this example it is set to 9, which corresponds to Android version 2.3.1. The emulator avd value is the name of the AVD (Android Virtual Device) you defined in the AVD Manager. In this case, an AVD with the name "9", but the AVD can be named whatever you like, as long as it matches the name you specified when creating the AVD. This is a basic configuration for the plugin that is needed to build and run an Android application. There are additional parameters that can be included for more functionality.

Dependencies

The Android artifacts have been built and published to the Maven repository through the efforts of the Android for Maven project . Google prevented the official Android jars from being uploaded to Maven, so the, third party, Android for Maven project was started to provide an API compatible Android artifact that could be uploaded to the Maven repository. There are now artifacts for each major Android version available in the Maven repository. These are not functional, however, and only provide stubbed implementations of the API. All methods in all classes throw a runtime exception. Because an Android app runs on a device, it will never use these libraries for execution, but the API compatibility allows an app to be compiled as if it were the real library. More information can be found here .

To compile an Android application with dependencies you need to include the Android version you are targeting for your app. As stated previously, we are using level 9, which corresponds to version 2.3.1. Check the Maven Repository for the available versions. You must set the android dependency scope to provided , otherwise Maven will try to include the Android jar library into your apk.

Compile against the latest milestone release of Spring Android Rest Template by adding the following dependency.

Include the repositories for the snapshot and milestone builds to use the latest build or milestone release of either of the Spring Android libraries in your app.

Development Environment

The Android SDK is required for developing Android applications. As mentioned earlier, Google provides command line tools, and an Eclipse plugin for building Android applications, however you are not restricted to only those options. Other IDE's also provide support for building Android apps. The Maven Android Plugin makes use of the Android SDK command line tools to compile and deploy the app to the emulator, so there is no need for a separate IDE setup or configuration.

The instructions for downloading and installing the Android SDK can be found on the Android web site. Please note that the Android SDK Revision 8 release changed the location of some of the tools. In addition to the tools directory, you must also add the platform-tools directory to your path.

For example, a .bash_profile on a Mac may look like the following.

Configure an Android Virtual Device

To run an Android app, you must have an Android Virtual Device (AVD) configured. An AVD is a configuration of emulator options. In other words, you are defining the settings to use when running the emulator. You can save a configuration with a name and use it later. You can also define multiple AVD's for testing against different Android versions or hardware configurations.

The pom.xml file included with the sample Android client app specifies an AVD with the name "9". In order for Maven to be able to deploy the Android app, you must have an AVD configured with that same name. This is of particular interest, as all developer machines will need to have the same AVD configured, since the pom.xml is typically committed to source control.

1. From the command line, type android and hit return. This opens the Android SDK and AVD Manager window.
2. Select Virtual devices in the left hand column and click the New… button
3. Enter 9 in the Name field
4. Select Android 2.3.1- API Level 9 in the Target selector
5. Click Create AVD to finish

Sample Application

We've set up a samples repository for the Spring Mobile projects. From the command prompt, clone the repository to your local machine with the following command.

Start the Server

If you would like to run the server component of the sample application, to see the interaction between the Android client and a Spring MVC website, the easiest way to do so is from within the STS IDE. Navigate to the spring-android-showcase directory. There are two directories, "client" for a client Android application, and "server" for a Spring MVC server application. The client app makes network requests to the server to illustrate RestTemplate functionality, so the server must be running for the client to function.

1. From STS, select File -> Import…
2. In the General folder, select Existing Projects into Workspace and click Next
3. Click Browse and navigate to the Server directory of the spring-android-showcase directory
4. Click Open to add the project to your workspace
5. Highlight the spring-android-showcase-server project in the Package Explorer view and drag it to SpringSource tc Server Developer Edition in the Servers view to deploy the web app
6. Finally, click the Run button to start the server

Run the Android Client

To build the client app enter the following command from the command line

Enter the following command to start the Android emulator. Maven tries to start the AVD with the name configured in the pom.xml, which is why the name needs to match with the name of the actual AVD you created.

Finally, deploy the application to the emulator with the following command.

The app is deployed to the emulator as S2Android Showcase. Before running the app, start up the Android log viewer to see the activity of the application. You will spend a lot of time with the Android logs when doing development. To view the logs, execute the following command at the command prompt.

Congratulations! You have now built and deployed an Android app with Maven managed dependencies.

Conclusion

Adding Maven to your Android development process adds extra complexity, but it provides the ability to compile an Android app that includes external dependencies from a Maven repository. Without it, you would manually have to download the dependencies needed to compile and run your application. We've shown the benefit of using it for dependency management to build with the Spring Android libraries. In the Part 2 post I will cover Android development in Eclipse with the Maven Integration for Android Development Tools plugin, and the ADT (Android Developer Tools) Plugin for Eclipse . Neither the m2eclipse nor ADT plugins support building Android applications with Maven dependencies. The Maven Integration for Android Development Tools plugin provides a bridge to the Maven Android Plugin, enabling Maven dependency management within Eclipse for Android projects. If you prefer using Eclipse for development, I'll discuss how to use these plugins in the next post .

Additional Resources

The Android Chapter of Maven: The Complete Reference contains a lot of good information about the Android Maven Plugin.

 

Spring Android and Maven (Part 2)

Posted on February 9th, 2011 by Roy Clarkson in Android , Spring .

In Spring Android and Maven (Part 1) , I described how to build an Android application from the command-line using Maven. In this post, I will show you how to build an Android application with Maven dependency management from the Eclipse IDE. The application will also showcase the latest features in Spring Android 1.0.0.M2 , which was released this week.

Overview

The Maven Android Plugin lets you build your Android applications with Maven and benefit from dependency management. Google's Android Development Tools (ADT) plugin allows you to develop and build Android applications within the Eclipse IDE. To get Maven dependency management within Eclipse, the Maven Integration for Android Development Tools plugin is required, which integrates m2eclipse , the ADT Plugin, and the Maven Android Plugin . This post will show you how to install this plugin and use it to get Maven-based dependency management working in the Eclipse IDE.

The specific versions of each component used in this post are listed below:

• Android SDK Revision 9
• Maven Android Plugin 2.8.4
• SpringSource Tool Suite 2.5.2 (Eclipse 3.6.1)
• ADT Plugin for Eclipse 9.0.0
• Maven Integration for Eclipse 0.12.0
• Maven Integration for Android Development Tools 0.2.4

Configure Eclipse

Before building or compiling any code, we need to install and configure the required Eclipse plugins. In Part 1 I discussed installing the Android SDK, so I will assume you have already done so. However, if you have not, then you will need to install it before continuing. Additionally, you will need to have already installed Eclipse 3.5 or newer. In this example I am using SpringSource Tool Suite 2.5.2 which is based on Eclipse 3.6.1.

There are three Eclipse plugins that need to be installed, the ADT Plugin for Eclipse, Maven Integration for Eclipse, and Maven Integration for Android Development Tools. You have two options for installing these plugins, either by using the Eclipse Marketplace Client , or by manually installing each plugin.

Installing Plugins using the Eclipse Marketplace Client

Depending on your version of Eclipse, you may already have the Eclipse Marketplace Client installed. The Marketplace Client will simplify the plugin installation, because it will transitively include any required plugins.

1. Open the Eclipse Marketplace Client by selecting Help -> Eclipse Marketplace…
2. Enter m2eclipse-android in the Find: field, and click the Go button.
3. Click the Install button next to Maven Integration for Android Development Tools .
   
4. Click the Next button to confirm the selected features. Note that Android Development Tools and Maven Integration for Eclipse are dependencies.
   
5. Accept the license agreements and click the Finish button to complete the installation.
6. After you restart Eclipse, you need to set the Android SDK Location as specified in the ADT Plugin installation in the next section.

Manual Plugin Installation

The alternative to using the Marketplace Client is to manually install each plugin. If you installed the plugins from the Marketplace, then you can skip down to the Sample Android Application section. For each plugin, from the Eclipse Help menu, select Install New Software… and click the Add… button.

ADT Plugin for Eclipse

The first step is to install the ADT (Android Developer Tools) Plugin for Eclipse. This is the official plugin provided by Google for developing Android applications. If you already have the ADT Plugin installed, then verify you have the latest version by running Check for Updates from the Eclipse Help menu.

1. Enter ADT Plugin for the Name , and the following URL for the Location . Click OK to continue.
   

   1	https://dl-ssl.google.com/android/eclipse

2. In the Available Software dialog, select the checkbox next to Developer Tools and click Next.
   
3. In the next window, you'll see a list of the tools to be downloaded. Click Next .
4. Read and accept the license agreements, then click Finish .
5. When the installation completes, restart Eclipse.
6. After Eclipse restarts, set the Android SDK Location by selecting Preferences from the Eclipse menu and selecting Android in the left column. On my machine, the SDK folder is located in my profile folder. Once the location is configured you should see a list of SDK Targets.
   

Note: If you have any trouble with the ADT installation, the Android web site can provide additional information.

Maven Integration for Eclipse

The next step is to install the m2eclipse plugin. STS 2.5.2 comes with this plugin. However, if you have a previous release, or if you already have the plugin installed, you need to verify you have the latest version. The Maven Integration for Android Development Tools requires version 0.12.0 or higher.

1. Enter m2eclipse Core Update Site for the Name , and the following URL for the Location . Click OK to continue.
   

   1	http://m2eclipse.sonatype.org/sites/m2e

2. In the Available Software dialog, select the checkbox next to Maven Integration for Eclipse and click Next .
   
3. In the next window, you'll see a list of the components to be downloaded. Click Next .
4. Read and agree to the terms of the Eclipse Public License v1.0, then click Finish .
5. When the installation completes, restart Eclipse.

Maven Integration for Android Development Tools

We've got one more plugin to install, and this is the one that brings all this functionality together. After you have set up the Android SDK and configured the ADT Plugin in Eclipse, install the Maven Integration for Android Development Tools plugin.

1. From the Eclipse Help menu, select Install New Software… and click the Add… button
2. Enter Maven Integration for Android Development Tools Update Site for the Name , and the following URL for the Location . Click OK to continue.
   

   1	https://svn.codespot.com/a/eclipselabs.org/m2eclipse-android-integration/updates/m2eclipse-android-integration/

3. In the Available Software dialog, select the checkbox next to Maven Integration for Android Development Tools and click Next .
   
4. In the next window, you'll see a list of the components to be downloaded. Click Next .
5. Read and accept the license agreements, then click Finish .
6. When the installation completes, restart Eclipse.

Sample Android Application

Now that we have all the necessary plugins installed and configured, we are ready to try out our setup with a sample Android application. We will use the same sample app created for the Part 1 blog post, however the sample app has been updated to run on the latest Android platform SDK, 2.3.1 API Level 9. If you do not have this SDK platform installed, you will need to do so before building the sample code.

Fetch the Sample Project

Run the following command to clone the Spring Mobile samples repository.

If the git:// URL is not accessible, you may need to try the alternate URL for the samples repository.

Before opening the source code in Eclipse, navigate to the spring-android-showcase/client project directory and verify the project builds with the Android Maven Plugin.

Open the Project in Eclipse

Assuming that the project built from the command line successfully, we are ready to open the project in Eclipse.

1. From the Eclipse File menu, select select New and Project…
2. Select the Android Project wizard from the Android folder and click Next . If the Android wizard is not available, then the ADT Plugin has not been installed.
   
3. In the New Android Project window, enter spring-android-showcase-client for the Project name . Select Create project from existing source , and browse to the Location of the sample client. Click Finish to add the project to Eclipse.
   

Enabling Maven Dependency Management

The sample project is now loaded into Eclipse. The first thing you will notice is the big red 'X' over the project in the Package Explorer, which indicates it currently does not build. Since we have yet to configure Maven for this project, this is expected behavior.

To enable Maven dependency management, right-click on the spring-android-showcase-client in the Package Explorer , and select Maven -> Enable Dependency Management from the context menu.

The sample project already includes the following Maven POM file. If you did not have an existing POM in your project, Eclipse would have prompted you to create one. Note the use of the maven-android-plugin and maven-compiler plugin in the build section.

Maven will now update the required dependencies and Eclipse should successfully build the project. Once Eclipse is finished building the project, you should now see the Maven Dependencies classpath container in the Package Explorer window.

There are a couple things to note. First you may see there is a bin folder in the project. You can see from the Java Build Path properties (below) that the default output folder is the Target folder. So it is safe to remove the bin folder.

Second, you may also notice that there is a JRE System Library classpath container that was added to the project. Since we are building an Android app that utilizes the Android JVM you should not need to reference the JRE. If you have created a new Android app in Eclipse with the ADT, you know that it does not add a classpath container for the JRE. I have discussed this with the Maven Integration for Android Development Tools developer, Ricardo Gladwell, and he created a ticket to research the issue. I have removed the JRE from the sample project without any obvious, negative effects. But you may want to keep watch on that issue for more information.

Start the Spring Android Showcase Sample App

To run the sample application, simply select the spring-android-showcase-client in the Package Explorer , and click the Run button. The Maven POM file in the sample client is configured to look for an Android Virtual Device (AVD) named "9". As mentioned earlier, the samples project has been updated to run on the Android Platform SDK 2.3.1. You need to have an AVD configured for this platform for the samples to run.

The first time you run the app, you should see something like the following in the Eclipse console:

The AVD will start and display the locked screen. Slide the green lock from left to right to "open" the Android device. Once opened, the app should now display:

Conclusions

In this post we've reviewed how to build a sample Android application in Eclipse that utilizes Maven dependency management. To accomplish this, we've used Eclipse, the Android Development Tools (ADT) Plugin for Eclipse, the Maven Android Plugin, the Maven Integration for Android Development Tools plugin, and the Maven Integration for Eclipse (m2eclipse) plugin. There are a lot of pieces involved, but once you have everything configured, it is easy to build and deploy to the Android emulator. If you are using third party libraries within your Android application, you should consider using these tools to help manage those dependencies.