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.ws.rest.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.ws.rest.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 statically references the EntryResource and EditEntryResource resources using the SubResources annotation declared on the class.

com.sun.ws.rest.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.ws.rest.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:

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.

Running the Example

Run the example as follows:

cd samples/SimpleAtomServer
ant run-server

This deploys the Atom server using the Lightweight HTTP Server included in Sun's Java Platform, Standard Edition 6 (Java SE 6) release.

A WADL description is automatically generated. Visit the following URL to see the generated description:

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

Get the service document:

java -jar dist/SimpleAtomServer.jar GET 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>
        </collection>
    </workspace>
</service>

The service document contains one workspace with one collection.

Create a media link entry:

echo "Something is rotten in the state of Denmark" | java -jar dist/SimpleAtomServer.jar POST http://127.0.0.1:9998/atom/collection text/plain

Get the Atom Feed document:

java -jar dist/SimpleAtomServer.jar GET http://127.0.0.1:9998/atom/collection

which returns the following:

<feed xmlns="http://www.w3.org/2005/Atom" >
    <title>Feed</title>
    <link rel="self"
        href="http://localhost:9998/atom/collection" />
    <entry>
        <title>Media Entry</title>
        <link rel="self"
            href="http://localhost:9998/atom/collection/9b871a01-4780-40cf-b457-2c54c566b6b1"/>
        <link rel="edit"
            href="http://localhost:9998/atom/collection/edit/9b871a01-4780-40cf-b457-2c54c566b6b1"/>
        <link rel="edit-media"
            href="http://localhost:9998/atom/collection/edit/9b871a01-4780-40cf-b457-2c54c566b6b1/media"/>
        <id>9b871a01-4780-40cf-b457-2c54c566b6b1</id>
        <updated>2007-01-11T11:12:06Z</updated>
        <content type="text/plain"
            src="http://localhost:9998/atom/collection/9b871a01-4780-40cf-b457-2c54c566b6b1/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:

java -jar dist/SimpleAtomServer.jar GET http://localhost:9998/atom/collection/9b871a01-4780-40cf-b457-2c54c566b6b1/media

which returns:

Something is rotten in the state of Denmark

Updating the media:

echo "Hamlet said: Something is rotten in the state of Denmark" | java -jar dist/SimpleAtomServer.jar PUT http://127.0.0.1:9998/atom/collection/edit/9b871a01-4780-40cf-b457-2c54c566b6b1/media text/plain

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

java -jar dist/SimpleAtomServer.jar GET http://localhost:9998/atom/collection/9b871a01-4780-40cf-b457-2c54c566b6b1

which returns:

<entry xmlns="http://www.w3.org/2005/Atom" >
    <title>Media Entry</title>
    <link rel="self"
        href="http://localhost:9998/atom/collection/9b871a01-4780-40cf-b457-2c54c566b6b1"/>
    <link rel="edit"
        href="http://localhost:9998/atom/collection/edit/9b871a01-4780-40cf-b457-2c54c566b6b1"/>
    <link rel="edit-media"
        href="http://localhost:9998/atom/collection/edit/9b871a01-4780-40cf-b457-2c54c566b6b1/media"/>
    <id>9b871a01-4780-40cf-b457-2c54c566b6b1</id>
    <updated>2007-01-11T11:16:32Z</updated>
    <content type="text/plain"
        src="http://localhost:9998/atom/collection/9b871a01-4780-40cf-b457-2c54c566b6b1/media"/>
</entry>

Delete the Atom Entry:

java -jar dist/SimpleAtomServer.jar DELETE http://localhost:9998/atom/collection/edit/9b871a01-4780-40cf-b457-2c54c566b6b1

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

java -jar dist/SimpleAtomServer.jar GET http://127.0.0.1:9998/atom/collection

returns a feed with no entries:

<feed xmlns="http://www.w3.org/2005/Atom" >
    <title>Feed</title>
    <link rel="self"
        href="http://localhost:9998/atom/collection" />
</feed>