This is sample code for Chapter 6 of Wiley's Enterprise Android. The sample
creates a RESTful Contacts service using the Spring framework for Java. This
service provides an operational backend for the client examples in chapter
5.

You can use any of the three major operating systems for PCs to develop the
web backend: Linux, Mac OS, or Windows. The OS is not particularly relevant
for backend services. The code is likely to work on a variety of software
versions, but was specifically tested on:

Java (1.7.0_25),  MySQL(5.7), Ant(1.9.1),
EclipseEE (Kepler), and Tomcat (7.0.12)

Note: The CODE variable refers to the location of the Wiley Enterprise Android
Examples directory. The reader should interpret CODE references as a
shorthand for this directory. It’s optional for readers to actually set
this variable in their shell of choice. For example, with Windows cmd,
you might use %CODE%/<Example>, or in bash you could use $CODE/<Example>
for example $CODE/springServiceContacts — but only if you set the
variable yourself.

 The example assumes that:

 * You are familiar with the code in restfulCachingProviderContacts which
   provides the Android client code for this service.

Instructions for running the Spring Service Contacts example using ant:

=== Prepare:

Note: If you are using Windows, its a good idea to check out the file
README_windows and follow the simple instructions it contains.

1. Install MySQL Community Server Edition

   The data tier of this example relies on mysql for SQL persistence;
   consequently, you’ll need to download it after creating an Oracle
   account:

   http://dev.mysql.com/downloads/mysql/

   Select your platform in the list at the bottom of the page, and then pick
   an appropriate download, like .msi for Windows or .dmg for MacOS. If you
   need more detailed instructions, see the following URL:

   http://dev.mysql.com/doc/refman/5.7/en/installing.html

   Note: Make sure to set the root password to be “mysql”, or edit the file
   $CODE/springContactsService/src/jdbc.properties to use a root password
   of your choosing. You will also need to use the default mysql port 3306,
   though you should not need to explicitly configure it.

   If you are installing on MacOS, make sure to get the DMG archive and
   install it using the setup script. On Windows, execute the .msi file and
   complete the wizard. If asked during the install, indicate that the
   service should start on boot.

   Note: If you are having trouble with mysql, see the file, README_mysql

2. Install the latest version of the Java JDK on the host that will run the service
   example. You can download it from the following location:

   http://www.oracle.com/technetwork/java/javase/downloads/index.html

3. Install Tomcat Version 7

   The code uses Apache Tomcat as its application server, so you’ll start by downloading
   Tomcat from the following location:

   http://tomcat.apache.org/download-70.cgi

   And then follow the installation instructions on the Tomcat site:

   http://tomcat.apache.org/tomcat-7.0-doc/appdev/installation.html

   Basically, just uncompress the download archive where you would like
   Tomcat to reside. Then set the shell variable, CATALINA_HOME to that
   directory. There’s lots of documentation about Tomcat online:

   http://tomcat.apache.org/tomcat-7.0-doc/index.html

   After you install it, Tomcat is very easy to use. To install an
   application, you just need to place the application’s war file into
   $CATALINA_HOME/webapps and then restart Tomcat with:

   $CATALINA_HOME/bin/shutdown.sh
   $CATALINA_HOME/bin/startup.sh

   On windows, these scripts end with .bat

   Set CATALINA_HOME to the directory where you unpack Tomcat.

   Note: Throughout the chapters on server development, the book will say to
   “restart Tomcat” as a shorthand for restarting the server if it’s running or
   starting it if it’s not.

   Of course, if you’ll be using Eclipse, it’s even easier than that — the IDE
   will deploy your application and handle the installation for you.

4. Install Apache Ant from:

   http://ant.apache.org/bindownload.cgi

   ANT_HOME is the directory where you install ant, you should probably
   set this environment variable.

   Put the directory $ANT_HOME/bin in your Path environment variable.

5. Build the project using ant, and setup the database:

   Build the project distribution war archive using:

   cd $CODE/springServiceContacts
   ant dist

   This command will compile project source files and will download
   required jar dependencies using the ivy dependency manager. The output
   of the command is the file:

   dist/springServiceContacts.war

   Setup the database using:

   ant builddb

   This command creates the springContact database, and the tables:
   contact, and contact_hbm.

   Note: When running the ivy installation (part of the build.xml), you need
   internet connectivity, otherwise, it will silently fail without installing
   the ivy binary jar file, and may even corrupt the ivy far file already
   present.

   Note: If you deploy a war file to a cloud server using these instructions,
   dont forget that you need to run "ant buildb" on the cloud service as well,
   which will require copying the chapter project,
   springServiceContacts to the cloud host.


=== Run with the command line:

1. Build the project:

   ant dist

2. Copy the war file to tomcat:

   $CODE/springServiceContacts/dist/springServiceContacts.war

   to

   $CATALINA_HOME/webapps

   Note: CATALINA_HOME is the home directory where tomcat is installed.

3. Restart Tomcat

=== Run with Eclipse

To build the project using Eclipse, proceed as follows:

Perform steps 1-5 of of the Prepare section running the example with ant.

1. Install the Eclipse IDE for Java EE Developers from:

   http://www.eclipse.org/downloads/

   Warning: Make sure you are using Eclipse Enterprise Edition (standard
   edition is not sufficient for service development). Also make sure that
   the build of Java, 32- or 64-bit, matches that of Eclipse.

   Just start Eclipse EE if its already installed.

2. Run the following command:

   ant eclipse

   Like other chapters, this command copies the Eclipse project files from the
   tools directory to the root directory. Note that if you do not run this
   step, Eclipse will not see the project folder as an Eclipse project, and you will not
   be able to open the project in Eclipse.

3. Add ivy support to eclipse:

   a. Help -> "Install new software"
      Work with:  http://www.apache.org/dist/ant/ivyde/updatesite

      Check the following for install:

      Apache Ivy Library
      Apache IvyDE Eclipse plugins

   b. Click next.
   c. Accept the terms, finish, and restart Eclipse

4. Import the Eclipse project

	a. Start Eclipse
	b. Import the project with:

	   "File -> General -> Import Existing Project"

	c. Click the Browse button, and choose the springServiceContacts
	   directory, then check the checkbox to select the
	   springServiceContacts, then click the "Finish" button.

	d. Click next.

5. Configure Eclipse to use Tomcat with:

   Use Window -> Preferences -> Server (on the left) -> Runtime
   Environments -> Server -> Runtime Environments.

   Select Add -> Apache Tomcat v7.0. Click Next.

   Select the Tomcat Installation directory CATALINA_HOME.

   Browse to the directory where you previously unpacked Tomcat and select
   it.

   Select a JRE: Make sure to use the previously installed “JDK” Java
   installation — a JRE is not sufficient. If you don’t see a JDK choice in
   the JRE drop-down, click the installed JRE’s button.

      a. Click the Add button.
      b. Select Standard VM -> Click Next.
      c. Click Directory to edit the JRE home.
      d. Browse and select the directory where you previously installed the Java JDK
      e. Click Finish.

   If a JRE is selected, un-select it, and select the JDK instead.

   Click OK.

   Back in the Tomcat Server window under the JRE drop-down, if the JDK is not
   selected, make sure you select it now.

   Click Finish again to complete server configuration.
   Click OK again to leave preferences.

6. Show the server's view:

    Window -> show view -> server -> servers

7. Click the link in the server view to create a new server.

    Select tomcat7 with the configure tomcat7 environment.

    Add springServiceContacts and Finish

5. Create a new configuration and run:

   a. Right-click springServiceContacts in the package
   explorer.

   b. Select Run as -> Run Configurations.

   Select Apache Tomcat on the left.

   Click the New icon on the upper left.

   c. Enter the server name, contact_configuration; replace New_configuration.

   Then click Apply.

   Then click Run.

   Note: Windows firewall will/may block the server, so hit "Allow Access" when
   dialog opens.

   Watch the log file for errors, and keep in mind that it will take a few
   minutes for ivy to download dependencies the first time the service runs.
   To see that each service is running correctly, load the
   URL http://localhost:8080/springServiceContacts/Contacts in a browser.

   If you see an empty array symbol ( that is, “[ ]”) then it's working.

=== Clients:

You can install this particular tool in the Chrome browser from Google:

using:
https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo/related?hl=en-US


Once you have installed the extension, you can run it using the following URL:


chrome-extension://hgmloofddffdnphfgcellkdfbfbjeloo/RestClient.html

===

Run the chapter 5 clients, and curl against the following local endpoint:

http://localhost:8080/springServiceContacts/Contacts

Follow the instructions in:

$CODE/restfulCachingProviderContacts/README


Test your service using the following commands:

Create contacts:
curl -H "Content-Type: application/json" -X POST -d '{"firstName":"John", "lastName":"Smith", "phone":2345678901, "email":"jsmith@nosuchhost.com" }' http://localhost:8080/springServiceContacts/Contacts

Get contacts:
curl -X GET http://localhost:8080/springServiceContacts/Contacts

=== Advanced REST Client Chrome REST Extension:

Since you’ve just written a simple web service, it’s possible to drive
its operation using only a web browser using the endpoint URL:

http://localhost:8080/springServiceContacts/Contacts

If the servers are running correctly, when you load this URL, the browser
will simply show "[]" for an empty array - indicating an empty contacts
database.

Another convenient way to drive the operation of the browser is to use a
command like curl:

http://en.wikipedia.org/wiki/cURL

You can also install the Advanced Rest Client Chrome extension — a third
convenient way to run REST requests.

Figure 6-8 shows the output of a request to list contacts in a web-based
REST invocation tool. This service contains two contacts, “John Smith”, and
“Mark Jackson”.

You can install this particular tool in the Chrome browser from Google using:

https://chrome.google.com/webstore/detail/advanced-rest-client/hgmloofddffdnphfgcellkdfbfbjeloo/related?hl=en-US

Once you have installed the extension, you can run it using the
following URL:

chrome-extension://hgmloofddffdnphfgcellkdfbfbjeloo/RestClient.html