This article highlights the benefits of connecting mobile devices to the cloud while also presenting an Amazon SimpleDB use case. Amazon SimpleDB is a highly available, flexible, and scalable non-relational data store that offloads the work of database administration. The app described here demonstrates how to store a high score list or leader board in SimpleDB. The app enables the user to view the high scores sorted by name or score, add and remove scores, and more. This article shows sample code for the Android platform. The complete sample code and project files are included in the AWS SDK for Android. A link to the SDK is available at the end of this article.

To use the AWS SDK for Android, you will need your AWS credentials, that is, your Access Key ID and Secret Access Key. If you haven't already signed up for Amazon Web Services (AWS), you will need to do that first to get your AWS credentials. You can sign up for AWS here. After you have signed up, you can retrieve your credentials at this page.

Overview

SimpleDB stores data in domains. Each domain is a collection of items and each item is a collection of attribute/value pairs. For the app, we create a single domain to store our high score list. Each item in the domain represents an individual player. The items will have two attributes, the player's name and their score. Items also have a unique identifier called the item name that, in this case, is equal to the player's name. Storing the player's name and score as item attributes enables us to sort the items by name or score.

The app demonstrates how to add and remove individual players, sort the scores by player name or score, and retrieve a single item from the domain. The app also demonstrates how to create and delete SimpleDB domains.

Creating a SimpleDB Client

Making requests to SimpleDB requires a client. Creating a SimpleDB client for Android is shown below.

AWSCredentials credentials = new BasicAWSCredentials(ACCESS_KEY_ID, SECRET_KEY);AmazonSimpleDBClient sdbClient = new AmazonSimpleDBClient( credentials);

High Score List Creation (Domain Creation)

Individual player scores are stored as items in a SimpleDB domain. This requires that we create the domain first. Using the appropriate client that we created above, we can use the following code to create the domain.

CreateDomainRequest cdr = new CreateDomainRequest( HIGH_SCORES_DOMAIN );sdbClient.createDomain( cdr );

Add Score (Item Creation)

An item is a collection of attribute/value pairs. For our items, we create two attributes, one for the player's name and one for the player's score. These are added to a request along with an item name in order to create the item. Because a player appears at most only once on the high score list, we use the player's name to uniquely identify each item. All data in SimpleDB are stored as strings, therefore numbers must be zero padded if you want to sort them properly. The AWS SDK for Android includes a utility to pad numbers, used below.

String paddedScore = SimpleDBUtils.encodeZeroPadding( score, 10 );		ReplaceableAttribute playerAttribute =     new ReplaceableAttribute(PLAYER_ATTRIBUTE, player, Boolean.TRUE);ReplaceableAttribute scoreAttribute =     new ReplaceableAttribute(SCORE_ATTRIBUTE, paddedScore, Boolean.TRUE);		List attrs = new ArrayList(2);attrs.add( playerAttribute );attrs.add( scoreAttribute );		PutAttributesRequest par = new PutAttributesRequest(HIGH_SCORES_DOMAIN, player, attrs);		sdbClient.putAttributes( par );

Remove Score (Item Deletion)

Removing a score from the list simply means deleting an item from the domain. Deleting an item requires the unique name for the item you wish to delete. In SimpleDB, deleting an item is done by removing all the attributes from that item. Invoking deleteAttributes with no specified attributes removes all the attributes by default.

DeleteAttributesRequest dar = new DeleteAttributesRequest( HIGH_SCORES_DOMAIN, player );sdbClient.deleteAttributes( dar );

Player View (Getting an Item)

Knowing an item's name makes it easy to find the item. This next snippet shows how to get all the attributes for an item using the item name. Note that items may contain many attributes and values.

GetAttributesRequest gar = new GetAttributesRequest( HIGH_SCORES_DOMAIN, player );GetAttributesResult response = sdbClient.getAttributes(gar);

List View and Sorting (Select)

Getting a collection of scores, sorted by player name or the score itself requires the use of a select request. A select request uses a simple query language to determine which items to match and what data to return and how. Select requests are paginated because the number of items matching the query can be large. Therefore, select requests return a next token that enables you to "page" through the data in an ordered fashion. The code here shows how to return items ordered by score from highest to lowest. Only the score and player attributes are returned. More information regarding SimpleDB queries can be found in a reference article linked below.

String select = "select player, score from HighScores where score >= '0' order by score desc";SelectRequest selectRequest = new SelectRequest( select ).withConsistentRead( true );selectRequest.setNextToken( nextToken );		SelectResult response = sdbClient.select( selectRequest );nextToken = response.getNextToken();

List Deletion (Domain Deletion)

The quickest and easiest way to remove the entire high score list would be to delete the SimpleDB domain. Here is how to do that.

DeleteDomainRequest ddr = new DeleteDomainRequest( HIGH_SCORES_DOMAIN );sdbClient.deleteDomain(ddr);

Conclusion

The code in this article demonstrates how to use Amazon SimpleDB as an indexed storage device for your app. The complete sample app is included as part of the AWS mobile SDKs, which are linked below. The reference section also contains a link to a SimpleDB article which discusses writing queries for SimpleDB in detail.

References

Find more information about SimpleDB here.

A sample app that includes this code is provided with the AWS SDK for Android

For more information about using AWS credentials with apps see the article, Authenticating Users of AWS Mobile Applications with a Token Vending Machine
 

Questions?

Please feel free to ask questions or provide comments in the Mobile Development Forum.