# 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>