logo AtomServer, Getting Started

Chris Berry, Bryon Jacob. Updated 05/01/08

This document describes some specific details about getting started with AtomServer.

For a further, detailed description of the actual protocol, either
This document does not explain the underlying concepts behind AtomServer; REST, Atom, and OpenSearch. That information can be found in the AtomServer General Introduction document. It is highly recommended that you read this document first.

Nor does this document explain the basics of XML, namespaces, syndicated feeds, and the GET, POST, PUT, and DELETE requests in HTTP, as well as HTTP's concept of a "resource." For more information about those things, see the Additional resources section of this document.


Installing AtomServer

AtomServer is usable right out of the box. It is simply a Java Web Application packaged into a standard WAR file. But to make things easier for the first time user. AtomServer provides a standalone implementation which runs in a embedded Jetty server, complete with a sample Atom workspace that contains a few Entries. The only prerequisite is, of course, Java. AtomServer will build and run with Java 1.5, but Java 1.6 is highly recommended.

The standalone AtomServer implementation requires zero configuration. For this discussion, let's assume that you are installing to a directory identified by $ATOMSERVER_HOME.
So, to get started with AtomServer, you just

1) Download the AtomServer tarball.

$ curl -G http://snapshots.repository.codehaus.org/org/codehaus/atomserver/2.0/atomserver-2.0-install.tar.gz

2) Expand it.

$ tar -zxvf

3) Type a single command;

$ ./bin/atomserver -seed

And you're up-and-running. It's that easy. By the way, the -seed switch tells AtomServer to seed the HSQLDB database with data to match the few Entries provided in $ATOMSERVER_HOME/data. You only need to use -seed this the first time you run atomserver.sh.

Now you can see your AtomServer in action. Bring up your favorite browser and hit the following URL; http://localhost:7890/atomserver/v1/pets/dogs.  This URL asks for a Feed of the dogs Collection from the pets Workspace. Dont' worry, in a later section we'll explore how to setup your AtomServer to deliver your own workspaces.

Because AtomServer is an Atom Data StoreAtomServer requires a relational database to run. AtomServer currently supports; PostgresSQL, SQLServer, and hsql. Installing database software is somewhat out of scope for this document. Once you've installed your database, you will need to setup the required AtomServer database tables. DDLs are provided for each supported database to make this relatively painless.

But the out-of-the-box, standalone AtomServer spins up HSQLDB - an embeddable Java database - and thus, requires no configuration. Unfortunately HSQLDB does not provide realistic database isolation levels, and is not recommended for high load, heavily concurrent applications, although its perfectly acceptable for our standalone demonstration AtomServer.

Exploring the Distribution

Let's explore the distribution you just unpacked. Again, for the sake of discussion, let's assume that you've chosen to install into a directory location identified by the environment variable; $ATOMSERVER_HOME. After a successful deployment, AtomServer will lay out the following directory structure in $ATOMSERVER_HOME. (Directories in green. Files in red)

Exploring the Configuration.

First let's look at the Spring configuration for our Demo AtomServer. As mentioned above, these Beans are contained in the file; $ATOMSERVER_HOME/conf/classes/org/atomserver/spring/ext/workspaceBeans.xml We are not going to get into all the details here. There is another configuration document  that explains it all in gory detail. Here is the definition of our example  pets Workspace.

    <util:set id="org.atomserver-workspaces">

        <bean class="org.atomserver.core.WorkspaceOptions">
            <property name="name" value="pets"/>
            <property name="defaultProducingEntryCategoriesFeedElement" value="true"/>
            <property name="defaultProducingTotalResultsFeedElement" value="true"/>
            <property name="defaultContentStorage" ref="org.atomserver-contentStorage"/>
            <property name="defaultContentValidator">
                <bean class="org.atomserver.core.validators.RelaxNGValidator">
                    <property name="schemaLocation"
            <property name="defaultCategoriesHandler" ref="
            <property name="defaultAutoTagger">
                <bean class="org.atomserver.core.autotaggers.XPathAutoTagger">
                    <property name="performanceLog" ref="
                    <property name="entryCategoriesDAO" ref="
                    <property name="script">
                    NAMESPACE pets = http://schemas.atomserver.org/pets/v1/rev0;
                    DELETE SCHEME {urn:pets.breeds};
                    MATCH "//pets:breed" {urn:pets.breeds}$;


Most of the properties in this Bean are wired to the AtomServer defaults settings, but let's take a look at what's here. Although before we get started, you're probably wondering why the all these properties start with the word "default". Well, that's because AtomServer will let you configure things at either the Workspace and/or the Collection level, and the values set at the Workspace level act as the defaults for all of its Collections, unless the Collection itself overrides that property.

Some Example Feed Requests

Assuming that you have followed the simple steps above, you should now have our Demo AtomServer running against the sample pets Workspace. So now let's explore a bit further. Bring up a browser and type in the following URL; http://localhost:7890/atomserver/v1/pets/dogs. You should see something like this in your browser window;

This output is from FireFox. It may look different in your browser of choice. Regardless, the browser should likely have a built-in Atom Feed Reader, such as Live BookMarks shown above, and should display the Atom Feed you requested. Note that a list of links is displays. Each of these is a link to an Atom Entry. Click on one of these links, say, Entry: dogs fido, and you should get the following Atom XML downloaded. Note that this output has been reformatted for readability. The actual output will not have much whitespace in it)

<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns="http://www.w3.org/2005/Atom">
   <title type="text"> Entry: dogs fido</title>
   <author><name>AtomServer APP Service</name></author>
   <link href="/atomserver/v1/pets/dogs/fido.xml" rel="self" />
   <link href="/atomserver/v1/pets/dogs/fido.xml/0" rel="edit" />
   <category scheme="urn:pets.breeds" term="Mixed" />
   <content type="application/xml">
      <pet xmlns="" type="dog">
         <owner>Chris Berry</owner>

If we examine this Atom Entry, we can see that we do have one Category applied (urn:pets.breed)Mixed, as defined in the AutoTagger setup above. And you can also verify that the <content> returned matches that in the Content storage ($ATOMSERVER_HOME/data/dogs/fi/fido/fido.xml.r0).

Next, let's do a Category query. In your browser, type in the following URL; http://localhost:7890/atomserver/v1/pets/dogs/-/(urn:pets.breeds)Mixed  Here we are asking for all Entries in the Workspace; pets and the Collection; dogs, which have the Category; (urn:pets.breed)Mixed defined. And you should get something like this output returned;

Notice that this time we only get two Entries returned. If you look at the corresponding XML in the Content storage you can verify that both fido and spike have <breed>Mixed</breed>, while sparky is <breed>Collie</breed>.  Thus, only those two Entries are returned.

Of course, we've only scratched the surface of what AtomServer can do. It has an impressive list of features. But we hope that we've piqued your interest enough for you to get your hands dirty digging under the covers.

Building AtomServer

Most people will never need to actually build AtomServer, instead they will simply deploy the AtomServer WAR and configure it to their needs.  That said, if you do wish to build it, its easy to do. AtomServer uses Maven for its build, so there are very few prerequisites to building. Maven will download all of AtomServer's dependencies for you, and build everything into standard locations using standard Maven commands. (e.g. mvn clean, mvn install, mvn jetty:run, etc.). If you are not already familiar with Maven, you should probably consider reading some introductory Maven documentation before starting.

Prerequisites (in addition to those identified above)


Building is simple, just type;

$ mvn clean install

If you need to use another environment, like, say, Postgresql, you'll need to supply the "-env" switch

$ mvn clean install -Denv=postgres

Configuring Postgresql

Let's assume that you've already installed Postgresql on your computer, and that you're ready to install the AtomServer database. It is assumed that you have the conventional Postgresql admin user; "postgres"

1) You'll need to create a user on your computer named "atomserver". The scripts below assume this user with the password; "atomserver". Obviously, you can create your own versions of any of these scripts, and use any username/password you'd like.

2) Create the database;

$ su postgres
$ createdb atomserver_dev

3) Create the database tables, indexes, etc.;

$ su postgres
$ psql atomserver_dev -f $ATOMSERVER_HOME/webapps/atomserver-X.X/WEB-INF/classes/postgres_ddl.sql

4) Create the "atomserver" user in Postgresql;

$ su postgres
$ psql atomserver_dev
# CREATE USER atomserver WITH PASSWORD 'atomserver';
# \q

5) Grant permissions in atomserver_dev to atomserver;

$ su postgres
$ psql atomserver_dev -f $ATOMSERVER_HOME/webapps/atomserver-X.X/WEB-INF/classes/grant_perms.sql

6) (Optional) Edit pg_hba.conf. Depending on how you've set up your Postgresql security, you may need to add permissions to atomserver in this file.

7) Restart Postgresql;

$ su postgres
$ pg_ctl restart

Additional resources

You may find the following third-party documents useful:

    * Overview of Atom from IBM
    * HTTP 1.1 method definitions; specification for GET, POST, PUT, and DELETE
    * HTTP 1.1 status code definitions
    * Atom Syndication Reference (from Atom-enabled)
    * Getting to know the Atom Publishing Protocol (from IBM)