This is sample code for Chapter 7 of Wiley's Enterprise Android. The sample
creates a RESTful Contacts service with backend persistence support from
Amazon web services (DynamoDB). This service provides an operational backend
for the syncAdapterContacts example from chapter 5. The example assumes that:

 * You are familiar with and have run the code in syncAdapterContacts and
   in springSyncServiceContacts.

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), EclipseEE (Kepler), and Tomcat (7.0.12)

This examples does not require mysql.

Prepare: Prerequisites and Getting Started

Chapter 6 covered all the requirements for developing a Java web application
based on Spring, Jackson, and the application container, Tomcat.  This
example requires Tomcat and Ant installation.

The Amazon Web Services DynamoDB service example leverages many of these same
tools, but also requires the presence of the Amazon Web Services SDK, an AWS
account, and credentials.


=== Prepare:

1. Create an Amazon Account

   Create an Amazon AWS account if you do not already have one. To create the
   account, go to:

    http://aws.amazon.com/

   and click the sign-up button. You should be able to follow the instructions
   from that point to create the account. You will need a credit card to
   complete sign-up.

2. Configure DynamoDB with Contacts Application Schema

   Once you have created an account, you can visit the AWS management console
   at:

   https://console.aws.amazon.com

   From there, click the DynamoDB link under the Database category. This takes
   you to the UI for managing the DynamoDB. Follow the instructions there to
   create application tables in DynamoDB - the create table wizard may pop
   up by default.

   Working with AWS is different than working with traditional SQL databases —
   schema management takes place in an online editing tool, rather than with a
   source code-based SQL language. At the top of the page in the Dynamo DB
   section, you should see a row of buttons. Find the one labeled Create Table
   and repeat the table creation process for the next tables. You need to
   create the following three tables:

   Contact, ContactFNameIndex, and ContactUpdateTimeIndex.

    * The Contact table stores contact data. When creating each table, you
      will need to decide whether the table will use a hash key and range key,
      or a hash key only. This table needs only a hash key, which the UI will
      prompt you to add as a hash attribute name. Click the appropriate radio
      button. The name should be id.

      Next, continue through the optional add indexes screen — nothing to add
      right now, none of the tables use a secondary index - then use Step 3
      for each table to specify read/write throughputs.

    * "ContactFNameIndex" stores the index for searching on the first name. This
      table needs a hash key and a range key, and you should define the type of
      the key as String.

      The hash attribute name is, "userId"

      The range attribute name is "firstName"

      Hit continue to skip adding indexes.

      Use step 3 to specify the read and write through-puts.

    * "ContactUpdateTimeIndex" stores the index for searching on update time.
      This table needs both hash and range keys.

      The hash and range attribute names are, "userId" and "updateTime",
      respectively. Again, the types of the keys are String.

      You may see a message regarding throughput warnings being sent to the
      designated e-mail recipient. Click continue if you haven’t responded
      to the confirmation e-mail yet.

      Hit continue to skip adding indexes.

      Use step 3 to specify the read and write through-puts.

   Note: One "interesting" characteristic of Amazon's pricing policy is that if
   you create a schema under a pricing plan, the existence of the schema
   itself, rather than actual traffic, can drive service charges! In other
   words, it's possible to define a schema, have no traffic, but still get a
   bill.

   Amazon has provided DynamoDB documentation on its developer site as well:

   http://aws.amazon.com/dynamodb/

3. Specify the Read/Write through-puts

   For each table you define, you need to specify the Read Throughput and the
   Write Throughput. If you are using the AWS free tier account, set both Read
   Throughput and Write Throughput to "2" to avoid being charged. The higher
   you go, the more you will pay. You can find specific AWS pricing details
   on their site:

   http://aws.amazon.com/dynamodb/pricing/

   Click Continue. The next screen optionally allows you to monitor your
   request rates and set throughput alarms. We won’t be doing that for our
   example, so just enter an e-mail address for notification and click
   Continue to finish table creation.

   The final page provides a summary for your review. Click Create, and
   you’ll be taken to the Services page, providing both editing capabilities
   and detailed information about the tables you just created.

4. Create Access Credentials

   Before your client can communicate with AWS, you need to create an access
   key, as follows:

   AWS Management Console ->
   Your Name Menu -> My Account -> Security Credentials (on the left)

   Note: You will need permission to modify the AWS account to edit Security
   Credentials.

   This brings you to the AWS security credentials page where you can create an
   access key, with:

   (Preferred)
   https://console.aws.amazon.com/iam/home?#security_credential ->
   Access Keys -> Create New Root Key

   Create the key and download its corresponding csv file, it contains the
   access and secret keys.

   OR

   (Deprecated)
   Access Credentials -> create a new access key

   The access key is displayed, use the UI to show the secret key.

5. Install Amazon Web Services SDK (Optional)

   To work with Amazon Web Services, you'll need to download the SDK from
   Amazon's development center from the following location:

   http://aws.amazon.com/sdkforjava/

   Note: Strictly speaking, you only need the SDK for its .jar file, which can
   be resolved in the project’s ivy.xml file. Thus, it’s optional for you to
   download the Amazon SDK.

6. Add Security Credentials

   Add the access key and secret access key to the file:

   $CODE/awsServiceContacts/src/main/resources/com/enterpriseandroid/awsContacts/dao/impl/AwsCredentials.properties

   By entering the keys as follows:

   accessKey=Insert your access key here
   secretKey=Insert your secret key here

   Note: Make certain not to accidentally swap the access and secret keys.

   Finally, change the following field:

   $CODE/awsServiceContacts/src/main/java/com/enterpriseandroid/awsContacts/rest/ContactController.USER_ID

   to be your amazon account username.

   Note: While it’s possible to run the contacts service with DynamoDB
   remotely, performance will improve signifi cantly by running the tomcat
   instance on an EC2 instance. See the AWS console for more information on
   EC2. It’s fine to run the examples on your local machine; contacts will
   save to DynamoDB remotely.

=== Deploy the Service

As you've seen, you can run the code using ant or eclipse.

== Deploy the code with ant:

1. Build the code with:

   cd $CODE/awsServiceContacts
   ant dist

2. Deploy the code to tomcat:

   cp dist/awsServiceContacts.war $CATALINA_HOME/webapps

3. Restart tomcat.

== Deploy the code with eclipse:

1. Run ant to initialize Eclipse

   As in the last chapter, you’ll need to use ant to initialize eclipse:

   cd $CODE/awsServiceContacts
   ant eclipse

2. Import the AWS project directory in Eclipse, as was done in chapter 6 for
   springServiceContacts:

   $CODE/awsServiceContacts

   Use:

   File->Import->General->Existing Projects into workspace

3. Add a run configuration

    Right click 'awsServiceContacts' in the Package Explorer.

    Select:

    Run As->Run on Server->Previously added (in ch6) Tomcat Configuration

    Wait for ivy to resolve dependencies.

    The AWS application should now be running, assuming you that the Amazon
    SDK can connect to AWS services.

    Note: If you need to add a tomcat configuration, please see the
    instructions for doing so in chapter 6.

== Clients:

Run the chapter 5 client syncAdapterContacts, the Chrome plug-in, or curl
against the following local endpoint:

http://localhost:8080/awsServiceContacts/Contacts

Release Note: Although the chapter states you can run both chapter 5 clients
against the $CODE/awsServiceContacts project, in fact, you can only use
$CODE/syncAdapterContacts.

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/awsServiceContacts/Contacts

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