Simple Atom Server Example

This example demonstrates a simple Atom server that partially conforms to the Atom Publishing Format and Protocol.

Atom Entries, Atom Media Link Entries, and media are persisted to the file system. The ROME Java library provides support for the parsing and serializing of Atom Feed and Entry documents.

Contents

The example consists of four web resources implemented by the following:

com.sun.jersey.samples.atomserver.resources.ServiceResource
This Java class returns the Service Document describing the Workspace that contains the Atom Collection that creates, reads, updates, and deletes Atom Entries.
com.sun.jersey.samples.atomserver.resources.FeedResource
This Java class provides the Feed Document describing the Atom Entries in the feed. It also provides support to create Atom Entries and Atom Media Link Entries. The resource references the EntryResource and EditEntryResource resources using the Path annotation declared on the FeedResource.getEntryResource and FeedResource.getEditEntryResource methods respectively.
com.sun.jersey.samples.atomserver.resources.EntryResource
This Java class supports the reading of an Atom Entry or Atom Media Link Entry. The reading of the media, associated with a Media Link Entry, is supported by a sub-resource HTTP method.
com.sun.jersey.samples.atomserver.resources.EditEntryResource
This Java class supports the read, update, and delete of an Atom Entry or Atom Media Link Entry, and via a sub-resource HTTP method the read and update of the media. This resource extends EntryResource to inherit the reading support.

The mapping of the URI path space is presented in the following table:

URI path Resource class HTTP methods
/service ServiceResource GET
/collection/ FeedResource GET, POST
/collection/{entry} EntryResource GET
/collection/{entry}/media EntryResource GET
/collection/edit/{entry} EditEntryResource PUT, DELETE
/collection/edit/{entry}/media EditEntryResource PUT

File System Structure of Persisted Atom Feed, Atom Entries, and Media

The Atom Feed/Entries and media are persisted to a file system. The structure of the file system is as follows:

collection
The directory where all Atom Entries and media are stored. This directory is created in the current working directory where the Atom Server is run.
collection/feed.xml
The persisted Atom Feed document.
collection/<uuid>/entry.xml
Each Atom Entry document for the Collection is stored under a unique directory (a UUID) from which the Atom Entry document is persisted. The UUID corresponds to the atom:id of the Atom Entry.
collection/<uuid>/media
The media (if present) of an Atom Media Link Entry.

To remove the Atom Feed document and all the Atom (or Atom Media Link) Entries delete the collection directory.

Running the Example

Run the example as follows:

mvn clean compile exec:java

This deploys the Atom server using Grizzly

A WADL description may be accessed at the URL:

http://localhost:9998/atom/application.wadl

Following steps are using cURL command line tool:

Get the service document:

curl http://127.0.0.1:9998/atom/service

This returns the following sevice document:

<service xmlns="http://purl.org/atom/app#"
        xmlns:atom="http://www.w3.org/2005/Atom">
    <workspace>
        <atom:title>Service</atom:title>
        <collection href="http://localhost:9998/atom/collection">
            <atom:title>Entries</atom:title>
            <categories>
                <atom:category term="storage" scheme="urn:storage" label="storage" />
            </categories>
        </collection>
    </workspace>
</service>

The service document contains one workspace with one collection.

Create a media link entry:

curl -i -X POST --data "Something is rotten in the state of Denmark" -HContent-type:text/plain  http://127.0.0.1:9998/atom/collection

Get the Atom Feed document:

curl http://127.0.0.1:9998/atom/collection

which returns the following:

    <?xml version="1.0" encoding="UTF-8"?>
    <feed xmlns="http://www.w3.org/2005/Atom" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:sy="http://purl.org/rss/1.0/modules/syndication/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:taxo="http://purl.org/rss/1.0/modules/taxonomy/">
      <title>Feed</title>
      <link rel="self" href="http://127.0.0.1:9998/atom/collection" />
      <entry>
        <title>Media Entry</title>
        <link rel="self" href="http://127.0.0.1:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd" />
        <link rel="edit" href="http://127.0.0.1:9998/atom/collection/edit/bdac4727-cbc3-4c37-ad1e-206672bc48dd" />
        <link rel="edit-media" href="http://127.0.0.1:9998/atom/collection/edit/bdac4727-cbc3-4c37-ad1e-206672bc48dd/media" />
        <id>bdac4727-cbc3-4c37-ad1e-206672bc48dd</id>
        <updated>2011-03-23T05:51:28Z</updated>
        <content type="TEXT" src="http://127.0.0.1:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd/media" />
      </entry>
    </feed>

The Atom Feed document contains one Atom Media Link Entry. The atom:content contains a link to the media. (Note that the UUIDs and hence the URIs will be different than those shown in this example. Substitute the UUID in the example for the one returned rather than copying and pasting these commands directly.) The Atom Entry document, which will be the same as the entry element in the Atom Feed document, can be retrived from the URI of the link element with the self or edit value for the rel attribute. The id element contains the unique ID of the entry, which is a UUID.

Get the media:

curl http://127.0.0.1:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd/media

which returns:

Something is rotten in the state of Denmark

Updating the media:

curl -X PUT --data "Hamlet said: Something is rotten in the state of Denmark" -HContent-type:text/plain http://127.0.0.1:9998/atom/collection/edit/bdac4727-cbc3-4c37-ad1e-206672bc48dd/media

The entry now has an updated time when the entry is retrieved:

curl http://127.0.0.1:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd

which returns:

<entry xmlns="http://www.w3.org/2005/Atom">
  <title>Media Entry</title>
  <link rel="self" href="http://localhost:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd" />
  <link rel="edit-media" href="http://localhost:9998/atom/collection/edit/bdac4727-cbc3-4c37-ad1e-206672bc48dd/media" />
  <link rel="edit" href="http://localhost:9998/atom/collection/edit/bdac4727-cbc3-4c37-ad1e-206672bc48dd/" />
  <id>bdac4727-cbc3-4c37-ad1e-206672bc48dd</id>
  <updated>2011-03-23T06:12:46Z</updated>
  <content type="TEXT" src="http://localhost:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd/media" />
</entry>

Delete the Atom Entry:

curl -X DELETE http://localhost:9998/atom/collection/edit/bdac4727-cbc3-4c37-ad1e-206672bc48dd

The edit link is used to delete the entry. Retrieving the Atom Feed document:

curl http://localhost:9998/atom/collection

returns a feed with no entries:

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:sy="http://purl.org/rss/1.0/modules/syndication/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:taxo="http://purl.org/rss/1.0/modules/taxonomy/">
  <title>Feed</title>
  <link rel="self" href="http://localhost:9998/atom/collection" />
</feed>