6.1 Installing Android Studio

Android applications are developed through Android Studio (AS). This tutorial was written using version 2.1.3 of AS and, as such, we strongly recommend downloading and using this version since newer versions may introduce discrepancies and incompatibilities. In this section we will perform the necessary tasks to properly install this IDE, including installing the Java SE Development kit, AS, and Android SDK.

At the time of writing, AS 2.1.3 requires the Java Development Kit (JDK) 7; in particular, we used Java SE Development Kit 7u79, which can be downloaded from http://www.oracle.com/technetwork/java/javase/downloads/jdk7-downloads-1880260.html. From the JDK, we will need the Development Tools and the Public JRE, as shown in Figure 6.1.

After installing the JDK, the installation of AS 2.1.3 requires the reader to visit the page http://tools.android.com/download/studio/builds/2-1-3, and download the Windows bundle with SDK installer package. Alternatively, it is also possible to download a zip package appropriate for other operating systems; however, in doing so, the reader becomes responsible for manually setting up the necessary environmental variables.

After downloading and running the bundle's executable, AS should begin its installation. As shown in Figure 6.2, the reader needs to install the Android SDK (by ticking the appropriate checkboxes, if needed). The Android virtual device, while useful for testing many types of applications, is not sufficient for this tutorial. Since we require the accelerometer, location and microphone sensors, the use of a real device is strongly encouraged.

After its installation is complete, AS may greet the reader with a Missing SDK window. As shown in Figure 6.3, we can safely cancel this setup wizard since we will be installing the necessary SDK by ourselves. Notice the update notification in the upper-right corner of the window; we advise the reader not to update, as newer versions introduce incompatibilities.

When you finally see AS's welcome screen, open the Android SDK manager by clicking on Configure and then SDK manager, as shown in Figure 6.4.

You should see a window similar to the one shown in Figure 6.5. Since in this tutorial we will be using Android API level 21, tick the corresponding checkbox as shown in Figure 6.5, and click the OK button to let AS install the associated components.

Afterwards, open the same window and click on Launch Standalone SDK manager, as highlighted in Figure 6.6.

On the Standalone SDK manager, check the box corresponding to Android SDK Build-tools 21.1.2, just as Figure 6.7 shows. We will need these Build-tools to compile HappyWalk properly.

Table 6.1 summarizes the steps we have taken so far.

6.2 Cloning the Android Project

In this section we will fetch and set up HappyWalk's base client application code. To do so, we will install Git, check out the HappyWalk client project, run the application for the first time, discover our Android debug key, and obtain a Google Maps Android API key.

The base HappyWalk app is available through Git¹. As such, you will need to install an appropriate Git distribution for your OS. You can download the appropriate Git release for your OS from http://git-scm.com/downloads. This tutorial was developed using Git version 2.7.1.2 for Windows, although it should also work with newer versions. We will now demonstrate how to properly install Git on Windows 7. Make sure to adapt these steps to your own OS.

After running the installation package, choose a folder to install Git on. Make sure to add Git to your PATH system variable so that AS can find and use it! On the Git Windows installation, this can be done easily by choosing the option Use Git from the Windows Command Prompt (see Figure 6.8a). We also recommend choosing the options Checkout Windows-style, commit Unix-style line endings (see Figure 6.8b), Use MinTTY (see Figure 6.9a), and uncheck Enable file system caching (see Figure 6.9b).

Now that Git is installed, let us import the HappyWalk project in AS. From the welcome screen, click on Check out project from Version Control Git as indicated in Figure 6.10 and fill the correct repository URL, as shown in Figure 6.11. Pick a Parent Directory of your choosing, but please take note of its location.

After AS clones the project, it should ask you if you want to open the checked-out Studio project file. As shown in Figure 6.12, respond “No” and, instead, select “Open an existing Android Studio Project”). Select HappyWalk's directory from the previously chosen Parent Directory, as shown in Figure 6.13. As AS loads the project it is likely that a “Gradle Update” and a “Gradle Plugin Update” window to appear, in which case you should answer “Don't remind me again for this project” to both (see Figure 6.14).

After AS finishes the project load process we can begin our deployment. The project's structure follows the general architecture presented in Section 5.2. As previously mentioned, HappyWalk's MapsActivity will serve the purpose of showing nearby POIs and displaying collaborative data from all users, in order to provide near real-time mood context. However, in order to use Google Maps within this activity, we must first perform some additional steps.

First of all, we first need to run our application at least once. This will allow AS to generate the necessary debug certificates. We can launch our Android application by making sure that app is selected from the dropdown list near the small Android logo and by clicking on Run app (the green “play” button), as shown in Figure 6.15.

Make sure your device appears on the Select Deployment Target window. In the Windows operating systems, this may require installing the appropriate Android Debug Bridge drivers for your device. For more information on this, check the Android Developer's website.² If AS was able to properly install the application on your device, you should see a screen similar to what is shown in Figure 6.16.

Notice that Figure 6.16 shows an empty map screen. To use Google Maps, the reader needs to acquire his/her own Google Maps Android API key. To do so, a Google Account is required and it is also necessary to find the development computer's Android Debug Key. Figure 6.17 shows how this may be accomplished from within AS. With the HappyWalk project open, first open up the Gradle right-side panel (1). Click on its refresh button (2) and double-click on “happywalk/happywalk(root)/Tasks/android/signingReport” (3). The required SHA1 key takes the form XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX and shall appear on the Run console, at the bottom (4).

We cannot guarantee accurate instructions for the next few steps, since they may have changed by the time the reader is following this sentence. At the time of writing, the reader could follow the link below, replacing the XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX on the URL with the SHA1 acquired above:

https://console.developers.google.com/flows/enableapi?apiid=maps_android_backend&keyType=CLIENT_SIDE_ANDROID&r=XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX:XX%3Bhitlexamples.happywalk

Here, the reader should be able to log in to his/her own Google Account and follow the provided directions to acquire a Google Maps Android API key. This involves creating a project (Figure 6.18), creating a new Android API key (Figure 6.19), and obtaining the mentioned key (Figure 6.20).

In case the above instructions do not work, we advise the reader to search for the Google Console Developers page.³ Either way, the reader should be able to log in to his/her own Google Account and follow the provided directions to acquire a Google Maps Android API key. At the end, Google should provide a development key free of charge (it starts with “AIza”).

Let us now use the key by looking into the contents of the HappyWalk's file app/debug/res/values/google_maps_api.xml. To do so, it is easier to view the entire project using the project tab's Project view. By default, it should be set in Android view; you can change the project tab's view by clicking on the buttons shown in Figure 6.21. In this perspective, navigate to and double-click the app/debug/res/values/google_maps_api.xml file, as shown in Figure 6.22. As soon as you double-click google_maps_api.xml, you should see the following contents:

In place of YOUR_KEY_HERE, your google_maps_api.xml should contain your own development key. Once the proper Google Maps API key is in place, we can fully utilize the Maps interface on our application.

Table 6.2 summarizes the steps we have taken in this section.

6.3 Deploying the Server

As previously discussed in Section 5.2.2, to compile and use our server, we will be using the following technologies:

• PostgreSQL 9.3, for hosting our database
• Eclipse Mars IDE for Java EE Developers
• Apache Tomcat 7.

As we also mentioned in Section 5.2.2, the server needs to communicate with Foursquare® to acquire POI information. Therefore, the machine hosting it needs to have an active Internet connection. This is essential for the proper functioning of the HappyWalk system.

In the next section we will perform the necessary tasks to properly install Eclipse Mars and PostgreSQL, import HappyWalk's server project, obtain a Foursquare® client ID and secret, set up the database, and deploy the server on Tomcat 7.

6.3.1 Installing the Software and Cloning the Server's Project

Installing the Eclipse Mars is trivial; visit https://eclipse.org/mars/, download the Eclipse IDE for Java EE Developers package, and extract it to a location of your choice.

As for PostgreSQL, browse to http://www.postgresql.org/download/ and download the appropriate 9.3 installer for your OS. Several installers are available in http://www.enterprisedb.com/products-services-training/pgdownload. During installation, make sure to take note of the superuser password that is requested in the screen shown in Figure 6.23, we will need it later on. Uncheck Launch Stack Builder at exit, as it is not necessary (Figure 6.24).

After installing both of these tools, open the Eclipse Mars IDE and select a path of your choice for the workspace. Then, import a new Git project by clicking on File Import Git Projects from Git. You should see a window similar to the one in Figure 6.25.

Select Clone URI and then fill the URI field, as shown in Figure 6.26. The Host and Repository path fields will then be automatically filled.

Afterwards, just select the master branch (Figure 6.27) and select master as the initial branch, origin as the remote name, and choose a directory to save the project (Figure 6.28).

Eclipse will begin to receive the objects associated with our server. We now need to tell it to import the Eclipse project (Figures 6.29 and 6.30).

6.3.2 Obtaining a Foursquare®'s Client ID and Client Secret

Now that we have cloned the HappyWalk Server project, we will need to make a few modifications to the server's code. First, we will need to create a Foursquare® Client ID and a Client Secret.

Browse to the address https://developer.foursquare.com/. The steps herein described are valid for the version of the Foursquare® website available in the beginning of 2016. We cannot account for future changes in website design but, hopefully, the functionality will remain the same for the foreseeable future.

First, click on My Apps and create an account (if you do not already possess one). After that, click on the button that says Create a new app. Fill the Your app name and Download / welcome page url fields as you desire. You can leave the other fields empty, as they are not relevant for our purposes. Afterwards, click on Save changes, shown in Figure 6.31. Now, when you navigate into the MyApps menu, Foursquare® will provide you with a Client ID and a Client Secret (Figure 6.32), which we will need in our server.

To do so, use Eclipse's Project Explorer to browse and double-click the src/utilities/GlobalVariables.java class, as shown in Figure 6.33.

Here, it is necessary to replace the FOURSQUARE_CLIENT_ID and FOURSQUARE_CLIENT_SECRET strings with the values provided by Foursquare®, from the page shown in Figure 6.32.

6.3.3 Setting up the Database

Now, let us set up our PostgreSQL database. To do so, we will use the pgAdmin III tool which usually accompanies a PostgreSQL installation. If, for some reason, you are unable to use pgAdmin, it is also possible to create our database using the command line as we will show later on.

Using pgAdmin III, we first login by double-clicking on the PostgreSQL 9.3 server, highlighted by the circle in Figure 6.34. When the login menu pops up, use the superuser credentials obtained during the installation step shown in Figure 6.23.

Afterwards, right-click on Databases and select New Database, as shown in Figure 6.35. Name the database “happywalk” and set its owner as your superuser (by default, it should be postgres; see Figure 6.36).

After creating the database, we need to populate it. To do so, we will need to provide the database creation SQL file contained within the server's git repository. Since we have already fetched the project files using Eclipse, the root of our server's project files rests on the directory selected in the step depicted by Figure 6.28. To begin, click on the SQL button while having the happywalk database selected, as shown in Figure 6.37.

On the Query window that appears, go to File Open and select the file located in⁴ <root of HappyWalk's server Git>/Database/HappyWalkDB.sql. Afterwards, click on the Execute Query button (shown in Figure 6.38). If everything went well, the server should output something akin to Query returned successfully with no result in xx ms. With this, our database is fully operational.

As an alternative to pgAdmin III, you can also create the database through the command line. To do so, you need to either have the PostgreSQL binaries in your PATH system variable or navigate to <PostgreSQL's installation folder>/9.3/bin/ from the command prompt. Afterwards, just use the following command:

createdb -U <your superuser> -O <your superuser> happywalk

to create the database, and then the command:

psql -U <your superuser> -d happywalk -f <root of HappyWalk's server Git >/Database/HappyWalkDB.sql

to populate it.

Now that the database has been created, let us return to our server. In Eclipse, browse to the src/hibernate.cfg.xml file:

Here, you will need to replace the hibernate.connection.password and hibernate.connection.username properties with your PostgreSQL superuser credentials (chosen in the step shown in Figure 6.23). If necessary, also adjust the hibernate.connection.url property to match your server's URL and PostgreSQL port. If you have been following this tutorial from a single computer without changing default installation values, you should be connecting to a local PostgreSQL server and, thus, the default URL and port should be localhost:5432. This information should match the one shown in pgAdminIII, next to the PostgreSQL 9.3 server (see Figure 6.34).

6.3.4 Deploying the Server on Tomcat 7

Finally, we need to deploy our server on Tomcat 7. To do so, let us define a new server on Eclipse through the menu File New Other Server (Figure 6.39), where we choose a new Tomcat v7.0 Server (Figure 6.40).

Eclipse allows you to download and install the latest version of Apache Tomcat 7 from within the IDE. To do so, click on the Download and Install... button, as shown in Figure 6.41, and choose a folder to install the server on. If you get a grayed out Next button together with an error message saying Unknown version of Tomcat was specified, try to wait for a little while. Eclipse downloads Tomcat in the background (you can check the download progress in the bottom-right corner of Eclipse's main window) and it does not recognize the server until it has been fully downloaded.

Alternatively, you can also manually download Tomcat 7⁵ and indicate its path to Eclipse.

Finally, add our HappyWalkServer project to the newly created server by selecting it and pressing Add > (figure 6.42) and then Finish.

Happywalk's server should now be ready to be run. To test the server, try to run it by pressing the Run as... button on Eclipse, choosing Run on server (Figure 6.43) and selecting the newly created Tomcat 7 server (Figure 6.44).

At the bottom of Eclipse's main window, click on the tab that says Console. If everything is correctly configured, you should see a window similar to the one presented in Figure 6.45, where the Console tab is highlighted by a circle. The bottom output of the console should read something similar to INFO: Server startup in xx ms. Do check the rest of the console's output for any exceptions being thrown during the server's startup, which would indicate a configuration issue. Do not be alarmed by a possible browser window showing an HTTP status 404, as it simply means that we are not running any web interface within our server.

Table 6.3 summarizes the steps we have taken in this section.

Step	Summarized Objective
Install Eclipse Mars	Downloaded and extracted the Eclipse IDE for Java EE Developers package from https://eclipse.org/mars/
Install PostgreSQL 9.3	Downloaded a PostgreSQL 9.3 installer by visiting http://www.postgresql.org/download/
Import HappyWalk's server	Used Eclipse to import HappyWalk's server project from https://git.dei.uc.pt/dsnunes/happywalk.git
Obtain a Foursquare® client ID and secret	Visited https://developer.foursquare.com/, created an account and a new app to obtain a Client ID and a Client Secret, and replaced the appropriate variables within the server's GlobalVariables.java class
Set up the database	Used pgAdmin III to create a new “happywalk” database, populated this database using the project's HappyWalkDB.sql query, and updated the server's hibernate.cfg.xml file
Deploy the server on Tomcat 7	Used Eclipse to install Tomcat 7, added the HappyWalkServer project to it, and tested the server

6.4 Testing the Sample App

To finalize our preparatory work, we will now attempt to launch HappyWalk's base system. This involves allowing communication between the server and the Android app. As such, we will need to discover the server's IP address and set that information in the client application.

The exchange of information between the server and the Android client requires a communication channel between the machine hosting the server and your Android phone. This may be achieved within a local network (e.g. both devices connected to the same wireless network) or by having both devices connected to the Internet and knowing the server's public IP. Either way, as mentioned in Section 6.3, the server needs an active Internet connection, to communicate with Foursquare®.

In Windows 7 (and most other Windows operating systems), knowing your computer's IP address can be easily achieved through the command line. Click on the Start menu, on the search box type cmd, and open cmd.exe. On the command prompt type ipconfig and press the ENTER key. As shown in Figure 6.46, the command will display several IP addresses; in the example, this computer was connected to a router giving access to a WiFi network to which our Android phone was connected. Thus, in this case, we were interested in the IPv4 address, which represents the address of the computer within the local area network.

The Linux and MacOSX operating systems have their own equivalent command for displaying IP information; typically, one can execute the ifconfig command in the terminal.

Figuring out the correct IP address to provide to HappyWalk is a process that is highly dependent on your network configuration. If your server and your Android phone can communicate through the Internet, you can use websites such as www.myipaddress.com to discover your server's external IP.

After taking note of the server's IP, we will need to set this information in our Android app. In AS, change back to the Android view, just like we did a while back to change to Project view in Figure 6.21, and open the file hitlexamples.happywalk/utilities/GlobalVariables.java:

Change the field <IP_of_Server> within the URL variable to match the location of your server. Now, we should attempt to run HappyWalk once more by clicking on the Run app button (refer to Figure 6.15 back on page ??).

If both the server and the app have been properly configured and assuming that your Android device has an active Internet connection and location services enabled, you should see an image similar to the one presented in Figure 6.47.

During development and testing, remember that your device needs to have an active connection to the server and location services enabled. If it doesn't, the app will not work properly.

Table 6.4 summarizes the steps we have taken in this section.