1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!--
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
Copyright (c) 2010-2013 Oracle and/or its affiliates. All rights reserved.
The contents of this file are subject to the terms of either the GNU
General Public License Version 2 only ("GPL") or the Common Development
and Distribution License("CDDL") (collectively, the "License"). You
may not use this file except in compliance with the License. You can
obtain a copy of the License at
http://glassfish.java.net/public/CDDL+GPL_1_1.html
or packager/legal/LICENSE.txt. See the License for the specific
language governing permissions and limitations under the License.
When distributing the software, include this License Header Notice in each
file and include the License file at packager/legal/LICENSE.txt.
GPL Classpath Exception:
Oracle designates this particular file as subject to the "Classpath"
exception as provided by Oracle in the GPL Version 2 section of the License
file that accompanied this code.
Modifications:
If applicable, add the following below the License Header, with the fields
enclosed by brackets [] replaced by your own identifying information:
"Portions Copyright [year] [name of copyright owner]"
Contributor(s):
If you wish your version of this file to be governed by only the CDDL or
only the GPL Version 2, indicate your decision by adding "[Contributor]
elects to include this software in this distribution under the [CDDL or GPL
Version 2] license." If you don't indicate a single choice of license, a
recipient has the option to distribute your version of this file under
either the CDDL, the GPL Version 2 or to extend the choice of license to
its licensees as provided above. However, if you add GPL Version 2 code
and therefore, elected the GPL Version 2 license, then the option applies
only if the new code is made subject to such option by the copyright
holder.
-->
<html><head><title>Simple Atom Server Example</title></head>
<body>
<h1>Simple Atom Server Example</h1>
<p>This example demonstrates a simple
Atom server that partially conforms to the
<a href="http://tools.ietf.org/wg/atompub/">Atom Publishing Format and Protocol</a>.
</p>
<p>Atom Entries, Atom Media Link Entries, and media are persisted to the
file system. The <a href="https://github.com/rometools/rome">ROME</a> Java library provides support for the parsing
and serializing of Atom Feed and Entry documents.</p>
<h2>Contents</h2>
<p>The example consists of four web resources implemented by the following:
</p><dl>
<dt><code>com.sun.jersey.samples.atomserver.resources.ServiceResource</code></dt>
<dd>This Java class returns the Service Document describing the Workspace that
contains the Atom Collection that creates, reads, updates, and deletes
Atom Entries.
</dd>
<dt><code>com.sun.jersey.samples.atomserver.resources.FeedResource</code></dt>
<dd>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.
</dd>
<dt><code>com.sun.jersey.samples.atomserver.resources.EntryResource</code></dt>
<dd>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.
</dd>
<dt><code>com.sun.jersey.samples.atomserver.resources.EditEntryResource</code></dt>
<dd>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.
</dd>
</dl>
<p>The mapping of the URI path space is presented in the following table:</p>
<table border="1">
<tr>
<th>URI path</th>
<th>Resource class</th>
<th>HTTP methods</th>
</tr>
<tr>
<td>/service</td>
<td>ServiceResource</td>
<td>GET</td>
</tr>
<tr>
<td>/collection/</td>
<td>FeedResource</td>
<td>GET, POST</td>
</tr>
<tr>
<td>/collection/{entry}</td>
<td>EntryResource</td>
<td>GET</td>
</tr>
<tr>
<td>/collection/{entry}/media</td>
<td>EntryResource</td>
<td>GET</td>
</tr>
<tr>
<td>/collection/edit/{entry}</td>
<td>EditEntryResource</td>
<td>PUT, DELETE</td>
</tr>
<tr>
<td>/collection/edit/{entry}/media</td>
<td>EditEntryResource</td>
<td>PUT</td>
</tr>
</table>
<h2>File System Structure of Persisted Atom Feed, Atom Entries, and Media</h2>
<p>The Atom Feed/Entries and media are persisted to a file system.
The structure of the file system is as follows:
</p><dl>
<dt><code>collection</code></dt>
<dd>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.</dd>
<dt><code>collection/feed.xml</code></dt>
<dd>The persisted Atom Feed document.</dd>
<dt><code>collection/<uuid>/entry.xml</code></dt>
<dd>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 <code>atom:id</code> of the Atom Entry.</dd>
<dt><code>collection/<uuid>/media</code></dt>
<dd>The media (if present) of an Atom Media Link Entry.</dd>
</dl>
<p>To remove the Atom Feed document and all the Atom (or Atom Media Link)
Entries delete the <code>collection</code> directory.</p>
<h2>Running the Example</h2>
<p>Run the example as follows:</p>
<blockquote><pre>
mvn clean compile exec:java</pre></blockquote>
<p>This deploys the Atom server using
<a href="http://grizzly.java.net/">Grizzly</a>
</p>
<p>A <a href="http://wadl.java.net/#spec">WADL description</a> may be accessed at the URL:</p>
<blockquote><code><a href="http://localhost:9998/atom/application.wadl">http://localhost:9998/atom/application.wadl</a></code></blockquote>
<p>Following steps are using <a href="http://curl.haxx.se/">cURL</a> command line tool:
<p>Get the service document:</p>
<blockquote><pre>curl http://127.0.0.1:9998/atom/service</pre></blockquote>
<p>This returns the following sevice document:</p>
<blockquote><pre><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></pre></blockquote>
<p>The service document contains one workspace with one collection.</p>
<p>Create a media link entry:</p>
<blockquote><pre>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</pre></blockquote>
<p>Get the Atom Feed document:</p>
<blockquote><pre>curl http://127.0.0.1:9998/atom/collection</pre></blockquote>
<p>which returns the following:</p>
<blockquote><pre> <?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="<b>http://127.0.0.1:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd/media</b>" />
</entry>
</feed>
</pre></blockquote>
<p>The Atom Feed document contains one Atom Media Link Entry. The
<code>atom:content</code> 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 <code>entry</code>
element in the Atom Feed document, can be retrived from the URI of the
<code>link</code> element with the <code>self</code> or <code>edit</code> value
for the <code>rel</code> attribute. The <code>id</code> element contains the
unique ID of the entry, which is a UUID.
</p><p>Get the media:</p>
<blockquote><pre>curl http://127.0.0.1:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd/media</pre></blockquote>
<p>which returns:</p>
<blockquote><pre>Something is rotten in the state of Denmark</pre></blockquote>
<p>Updating the media:</p>
<blockquote><pre>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</pre></blockquote>
<p>The entry now has an updated time when the entry is retrieved:</p>
<blockquote><pre>curl http://127.0.0.1:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd</pre></blockquote>
<p>which returns:</p>
<blockquote><pre><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><b>2011-03-23T06:12:46Z</b></updated>
<content type="TEXT" src="http://localhost:9998/atom/collection/bdac4727-cbc3-4c37-ad1e-206672bc48dd/media" />
</entry></pre></blockquote>
<p>Delete the Atom Entry:</p>
<blockquote><pre>curl -X DELETE http://localhost:9998/atom/collection/edit/bdac4727-cbc3-4c37-ad1e-206672bc48dd</pre></blockquote>
<p>The <code>edit</code> link is used to delete the entry. Retrieving
the Atom Feed document:</p>
<blockquote><pre>curl http://localhost:9998/atom/collection</pre></blockquote>
<p>returns a feed with no entries:</p>
<blockquote><pre><?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></pre></blockquote>
</body></html>
|
