Dr. Dobb's is part of the Informa Tech Division of Informa PLC

This site is operated by a business or businesses owned by Informa PLC and all copyright resides with them. Informa PLC's registered office is 5 Howick Place, London SW1P 1WG. Registered in England and Wales. Number 8860726.

Channels ▼

JVM Languages

Amazon SimpleDB: A Simple Way to Store Complex Data

The presence of the last two letters in the name "Amazon SimpleDB" is perhaps unfortunate; it immediately invokes images of everything we have learned about databases; unless, like me, you cut your teeth on a hierarchical database like IMS, that means relational databases and all of the baggage that comes with them: strictly defined fields, constraints, referential integrity and having most of what you are allowed to do defined and controlled by a DBA -- hardly deserving of being described as simple. To allay any apprehensions even thinking of such things might arouse, let me state that Amazon SimpleDB is not just another relational database. So just what is SimpleDB? The most effective way I have found to understand SimpleDB is to think about it in terms of something else we all use and understand -- a spreadsheet. Look at the spreadsheet in Figure 1.

Figure 1: Common spreadsheet.

Typically, you organize spreadsheets into worksheets. In the world of SimpleDB, the approximate counterpart of a spreadsheet is a "domain", which is why I've labeled the tabs at the bottom Domain1, Domain2, etc. instead of more familiar Sheet1, Sheet2, etc.. In a spreadsheet, a worksheet contains a number of rows; SimpleDB has items. When you set up your spreadsheet, you usually create column headers whose names indicate the kind of data that appears in a given column. In SimpleDB, you would call the column headers attribute names.

But when you start putting data into individual cells, the similarity between a spreadsheet and SimpleDB ends. You can almost think of SimpleDB as a 3D spreadsheet, where every cell can contain multiple values. Each such value is expressed as a name-value pair called an "attribute". If you consider sets of attributes as tuples, you could describe SimpleDB as a "domain/item/attribute tuple space model."

Before rolling up your sleeves and getting started with SimpleDB, you will need a pay-as-you-go Amazon Web Services (AWS) account. When you create your account, you will be given an access ID and a secret key. You will need these to use the sample code I present in exploring SimpleDB.

SimpleDB Client Libraries

Interaction between a client and the SimpleDB engine is in the form of a web service. Application programmers prefer not to deal with the low level details of web services but rather to use an API that shields them from the underlying infrastructure and reduces their effort to simply creating instances of Java objects and invoking their methods. There are a number of client libraries that deliver such an API for SimpleDB for the major programming languages. The apparent winner in the Java world appears to be Typica, which provides access to several other Amazon services in addition to SimpleDB. In this article, I use the Java Library for Amazon SimpleDB from Amazon. This does not imply any endorsement nor should it be construed as a recommendation. It just happens to be the one I first started using. The right library for you will be the one that experimentation proves is the right library for you.

Creating and Listing Domains

CreateDomain.java (available here along with the source code and related files) takes three command line arguments. The first two are the AWS access ID and secret key respectively; the third is the name of the domain to be created. The essence of the program can be found in the following lines of code:

AmazonSimpleDBClient client;
client = new AmazonSimpleDBClient(args[0], args[1]);
CreateDomainRequest request = new CreateDomainRequest();
CreateDomainResponse response = client.createDomain(request);

The code is so simple that a detailed explanation is unnecessary -- and the good news is that the code I present in this article is almost as easy to understand and use.

Once you have created the domain, you can use ListDomains.java (available here) to obtain a list of all of the domains that have been created for the account. The code is similar to the code we just saw in CreateDomains.java. It creates an instance of AmazonSimpleDB to which it sends a ListDomainsRequest object as an argument. The list of the domains is returned in a ListDomainsResponse object. To reinforce the fact that the response is really an XML message, I displayed the String that was returned when I invoked the ListDomainsResponse object's toXML() method. It looks like this:

<ListDomainsResponse xmlns="http://sdb.amazonaws.com/doc/2007-11-07/">

Notice that the list of domains (in this case only one) is returned as a collection of <DomainName> nodes, each of which is a child node of the <ListDomainsResult> node. We retrieve the list of domains from the ListDomainsResponse object using the following code:

if (response.isSetListDomainsResult()) {
       ListDomainsResult listDomainsResult =
       domainsList = listDomainsResult.getDomainName();
if (domainsList.isEmpty()) {
       System.err.println("no domains found");
} else {
       System.out.println("found the following " + 
       domainsList.size() + " domains:");
     for (String domain : domainsList) {
     	System.out.println("\t" + domain);

Notice that we do not proceed blindly to get the domain list from the response but first invoke its isSetListDomainsResult() method. The output of the program looks like this:

found the following 1 domains:

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.