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 restfulCachingProviderContacts
client example from chapter 5. The code in this project is a clone of the
springServiceContacts project, with the addition of contact synchronization
support, and the use of UUIDs to replace integer object identifiers.

You can use any of the three major operating systems for PCs to develop a
web service 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)

 The example assumes that:

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

Before getting started:

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/springSyncServiceContacts — but only if you set the
variable yourself.

Instructions for running the Spring Service Contacts example using ant:

=== Prepare:

1. Install MySQL Community Server Edition

   (See: $CODE/springServiceContacts/README)

2. Install the latest version of the Java JDK on the host that will run the service
   example.

   (See: $CODE/springServiceContacts/README)

3. Install Apache Tomcat.

   (See: $CODE/springServiceContacts/README)

4. Install ant.

   (See: $CODE/springServiceContacts/README)

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

   Open a shell prompt, on Windows, use cygwin.

   Build the project distribution war archive using:

   cd $CODE/springSyncServiceContacts
   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/springSyncServiceContacts.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,
   springSyncServiceContacts to the cloud host.

=== Deploying Using Ant:

1. Build the project:

   ant dist

2. Copy the war file to tomcat:

   $CODE/springSyncServiceContacts/dist/springSyncServiceContacts.war

   to

   $CATALINA_HOME/webapps

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

3. Restart Tomcat

=== Building and deploying using 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. If its not already running, start the Eclipse IDE for Java EE Developers from:

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

   Just start Eclipse EE if its already installed.

   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.

2. Run the following commands in a shell:
   cd $CODE/springSyncServiceContacts
   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. Select 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 if its not running. Import the project with

       File -> General -> Import Existing Project.

    b. Click the Browse button, and choose the $CODE/springSyncServiceContacts
       directory; then check the checkbox to select the springSyncServiceContacts.

       Click the Finish button.

    c. Click Next.

5. Configure Eclipse to use Tomcat:

   (See: $CODE/springServiceContacts/README)

6. Show the server's view:

    Window -> show view -> server -> servers -> OK

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

   Select the server type (your previously configured Tomcat7)

   Leave the variables unchanged.

   Click Next -> Select springSyncServiceContacts.

   Click Add.

   Click Finish.

5. Create a new configuration and run:

   a. Right-click springSyncServiceContacts 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/springSyncServiceContacts/Contacts in a browser.

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

=== Run the service using Ant:

1. Start a shell for your platform (for example, on windows use cygwin). Then
   build the project:

   cd $CODE/springSyncServiceContacts
   ant dist

2. Copy the war file to tomcat, copy:

   $CODE/springSyncServiceContacts/dist/springSyncServiceContacts.war

   to

   $CATALINA_HOME/webapps

3. Restart Tomcat.


=== Clients:

You can run the chapter 5 syncAdapterContacts client against the
following local endpoint:

http://localhost:8080/springSyncServiceContacts/Contacts

And you can run the syncAdapterContacts client against

http://localhost:8080/springSyncServiceContacts/Contacts

To run these clients, follow the instructions in:

$CODE/restfulCachingProviderContacts/README
$CODE/syncAdapterContacts/README

Test your service using the following commands:

Create contacts for the sync service:

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

Get contacts:

curl -X GET http://localhost:8080/springSyncServiceContacts/Contacts

or

curl -X GET http://localhost:8080/springSyncServiceContacts/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/springSyncServiceContacts/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