| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| 2 |
<!-- |
| 3 |
|
| 4 |
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. |
| 5 |
|
| 6 |
Copyright (c) 2010-2012 Oracle and/or its affiliates. All rights reserved. |
| 7 |
|
| 8 |
The contents of this file are subject to the terms of either the GNU |
| 9 |
General Public License Version 2 only ("GPL") or the Common Development |
| 10 |
and Distribution License("CDDL") (collectively, the "License"). You |
| 11 |
may not use this file except in compliance with the License. You can |
| 12 |
obtain a copy of the License at |
| 13 |
http://glassfish.java.net/public/CDDL+GPL_1_1.html |
| 14 |
or packager/legal/LICENSE.txt. See the License for the specific |
| 15 |
language governing permissions and limitations under the License. |
| 16 |
|
| 17 |
When distributing the software, include this License Header Notice in each |
| 18 |
file and include the License file at packager/legal/LICENSE.txt. |
| 19 |
|
| 20 |
GPL Classpath Exception: |
| 21 |
Oracle designates this particular file as subject to the "Classpath" |
| 22 |
exception as provided by Oracle in the GPL Version 2 section of the License |
| 23 |
file that accompanied this code. |
| 24 |
|
| 25 |
Modifications: |
| 26 |
If applicable, add the following below the License Header, with the fields |
| 27 |
enclosed by brackets [] replaced by your own identifying information: |
| 28 |
"Portions Copyright [year] [name of copyright owner]" |
| 29 |
|
| 30 |
Contributor(s): |
| 31 |
If you wish your version of this file to be governed by only the CDDL or |
| 32 |
only the GPL Version 2, indicate your decision by adding "[Contributor] |
| 33 |
elects to include this software in this distribution under the [CDDL or GPL |
| 34 |
Version 2] license." If you don't indicate a single choice of license, a |
| 35 |
recipient has the option to distribute your version of this file under |
| 36 |
either the CDDL, the GPL Version 2 or to extend the choice of license to |
| 37 |
its licensees as provided above. However, if you add GPL Version 2 code |
| 38 |
and therefore, elected the GPL Version 2 license, then the option applies |
| 39 |
only if the new code is made subject to such option by the copyright |
| 40 |
holder. |
| 41 |
|
| 42 |
--> |
| 43 |
<html><head><title>Storage Service Example</title></head> |
| 44 |
|
| 45 |
|
| 46 |
<body> |
| 47 |
<h1>Storage Service Example</h1> |
| 48 |
<p>This example demonstrates a simple |
| 49 |
in-memory web storage service. |
| 50 |
</p> |
| 51 |
<p>The web storage service enables clients to create and delete containers. |
| 52 |
Containers are used to create, read, update, and delete items of |
| 53 |
arbitrary content, and to search for items containing certain content. |
| 54 |
A container can be thought of as a hash map of items. The key of |
| 55 |
an item is a URI path. |
| 56 |
</p> |
| 57 |
<p>The web storage service ensures that content can be cached (by browsers |
| 58 |
and proxies) by supporting the HTTP features <code>Last-Modified</code> |
| 59 |
and <code>ETag</code>. |
| 60 |
</p> |
| 61 |
|
| 62 |
<h2>Contents</h2> |
| 63 |
<p>The example consists of three web resources implemented by the following: |
| 64 |
</p><dl> |
| 65 |
<dt><code>com.sun.jersey.samples.storageservice.resources.ContainersResource</code></dt> |
| 66 |
<dd>This Java class provides meta-data information on the containers. |
| 67 |
The resource references the ContainerResource resource using the |
| 68 |
Path annotation declared on the ContainersResource.getContainerResource method. |
| 69 |
</dd> |
| 70 |
<dt><code>com.sun.jersey.samples.storageservice.resources.ContainerResource</code></dt> |
| 71 |
<dd>This Java class provides read, create and delete of a container. |
| 72 |
Searching of items is supported using a URI query parameter. |
| 73 |
The resource dynamically references the ItemResource resource using the |
| 74 |
getItemResource method that is annotated with Path. |
| 75 |
</dd> |
| 76 |
<dt><code>com.sun.jersey.samples.storageservice.resources.ItemResource</code></dt> |
| 77 |
<dd>This Java class provides read, create, update, and delete of an item. |
| 78 |
The last modified time and entity tag are supported such that |
| 79 |
it conditionally returns content only if the browser |
| 80 |
or proxy has an older version of the content. |
| 81 |
</dd> |
| 82 |
</dl> |
| 83 |
<p>The mapping of the URI path space is presented in the following table:</p> |
| 84 |
<table border="1"> |
| 85 |
<tr> |
| 86 |
<th>URI path</th> |
| 87 |
<th>Resource class</th> |
| 88 |
<th>HTTP methods</th> |
| 89 |
</tr> |
| 90 |
<tr> |
| 91 |
<td>/containers</td> |
| 92 |
<td>ContainersResource</td> |
| 93 |
<td>GET</td> |
| 94 |
</tr> |
| 95 |
<tr> |
| 96 |
<td>/containers/{container}</td> |
| 97 |
<td>ContainerResource</td> |
| 98 |
<td>GET, PUT, DELETE</td> |
| 99 |
</tr> |
| 100 |
<tr> |
| 101 |
<td>/containers/{container}/{item}</td> |
| 102 |
<td>ItemResource</td> |
| 103 |
<td>GET, PUT, DELETE</td> |
| 104 |
</tr> |
| 105 |
</table> |
| 106 |
|
| 107 |
<h2>Running the Example</h2> |
| 108 |
<p>Run the example as follows:</p> |
| 109 |
<blockquote><pre> |
| 110 |
mvn clean compile exec:java</pre></blockquote> |
| 111 |
<p>This deploys the web storage service using |
| 112 |
<a href="http://grizzly.java.net/">Grizzly</a> |
| 113 |
</p> |
| 114 |
<p>A <a href="http://wadl.java.net/#spec">WADL description</a> may be accessed at the URL:</p> |
| 115 |
<blockquote><code><a href="http://127.0.0.1:9998/storage/application.wadl">http://127.0.0.1:9998/storage/application.wadl</a></code></blockquote> |
| 116 |
|
| 117 |
<p>Following steps are using <a href="http://curl.haxx.se/">cURL</a> command line tool: |
| 118 |
<p>Get the containers:</p> |
| 119 |
<blockquote><pre>curl http://127.0.0.1:9998/storage/containers</pre></blockquote> |
| 120 |
<p>This returns the following XML document:</p> |
| 121 |
<blockquote><pre><containers/></pre></blockquote> |
| 122 |
<p>No containers are present.</p> |
| 123 |
<p>Create a container:</p> |
| 124 |
<blockquote><pre>curl -X PUT http://127.0.0.1:9998/storage/containers/quotes</pre></blockquote> |
| 125 |
<p>This creates a container called 'quotes'. Getting the containers:</p> |
| 126 |
<blockquote><pre>curl http://127.0.0.1:9998/storage/containers</pre></blockquote> |
| 127 |
<p>returns information about the 'quotes' container:</p> |
| 128 |
<blockquote><pre><containers> |
| 129 |
<container> |
| 130 |
<name>quotes</name> |
| 131 |
<uri>http://127.0.0.1:9998/storage/containers/quotes</uri> |
| 132 |
</container> |
| 133 |
</containers></pre></blockquote> |
| 134 |
<p>Create some content:</p> |
| 135 |
<blockquote><pre>curl -X PUT -HContent-type:text/plain --data "Something is rotten in the state of Denmark" http://127.0.0.1:9998/storage/containers/quotes/1 |
| 136 |
curl -X PUT -HContent-type:text/plain --data "I could be bounded in a nutshell" http://127.0.0.1:9998/storage/containers/quotes/2 |
| 137 |
curl -X PUT -HContent-type:text/plain --data "catch the conscience of the king" http://127.0.0.1:9998/storage/containers/quotes/3 |
| 138 |
curl -X PUT -HContent-type:text/plain --data "Get thee to a nunnery" http://127.0.0.1:9998/storage/containers/quotes/4 </pre></blockquote> |
| 139 |
<p>The 'quotes' container has four items associated with keys 1, 2, 3, and 4 when GETing the quotes container:</p> |
| 140 |
<blockquote><pre>curl http://127.0.0.1:9998/storage/containers/quotes</pre></blockquote> |
| 141 |
<p>it returns: |
| 142 |
<blockquote><pre><container> |
| 143 |
<item> |
| 144 |
<digest>7a54c57975de11bffcda5bc6bd92a0460d17ad03</digest> |
| 145 |
<lastModified>2007-01-10T15:07:48+01:00</lastModified> |
| 146 |
<mimeType>text/plain</mimeType> |
| 147 |
<name>1</name> |
| 148 |
<uri>http://127.0.0.1:9998/storage/containers/quotes/1</uri> |
| 149 |
</item> |
| 150 |
<item> |
| 151 |
<digest>4769363fcf4d0513619c6a30724daab396a1d196</digest> |
| 152 |
<lastModified>2007-01-10T15:08:37+01:00</lastModified> |
| 153 |
<mimeType>text/plain</mimeType> |
| 154 |
<name>2</name> |
| 155 |
<uri>http://127.0.0.1:9998/storage/containers/quotes/2</uri> |
| 156 |
</item> |
| 157 |
<item> |
| 158 |
<digest>-71240529c42b5b92e3086e624618d19164658616</digest> |
| 159 |
<lastModified>2007-01-10T15:11:51+01:00</lastModified> |
| 160 |
<mimeType>text/plain</mimeType> |
| 161 |
<name>3</name> |
| 162 |
<uri>http://127.0.0.1:9998/storage/containers/quotes/3</uri> |
| 163 |
</item> |
| 164 |
<item> |
| 165 |
<digest>493388267529403c84628e12141ffe9a013205a4</digest> |
| 166 |
<lastModified>2007-01-10T15:12:08+01:00</lastModified> |
| 167 |
<mimeType>text/plain</mimeType> |
| 168 |
<name>4</name> |
| 169 |
<uri>http://127.0.0.1:9998/storage/containers/quotes/4</uri> |
| 170 |
</item> |
| 171 |
<name>quotes</name> |
| 172 |
<uri>http://127.0.0.1:9998/storage/containers/quotes</uri> |
| 173 |
</container></pre></blockquote> |
| 174 |
<p>Search the container for all items containing the word 'king':</p> |
| 175 |
<blockquote><pre>curl "http://127.0.0.1:9998/storage/containers/quotes?search=king"</pre></blockquote> |
| 176 |
<p>which returns the following XML document containing one item, 3:</p> |
| 177 |
<blockquote><pre><container> |
| 178 |
<item> |
| 179 |
<digest>-71240529c42b5b92e3086e624618d19164658616</digest> |
| 180 |
<lastModified>2007-01-10T15:11:51+01:00</lastModified> |
| 181 |
<mimeType>text/plain</mimeType> |
| 182 |
<name>3</name> |
| 183 |
<uri>http://127.0.0.1:9998/storage/containers/quotes/3</uri> |
| 184 |
</item> |
| 185 |
<name>quotes</name> |
| 186 |
<uri>http://127.0.0.1:9998/storage/containers/quotes</uri> |
| 187 |
</container></pre></blockquote> |
| 188 |
<p>Get the contents of item 3:</p> |
| 189 |
<blockquote><pre>curl http://127.0.0.1:9998/storage/containers/quotes/3</pre></blockquote> |
| 190 |
<p>which returns the following:</p> |
| 191 |
<blockquote><pre>catch the conscience of the king</pre></blockquote> |
| 192 |
<p>Update the contents of item 3:</p> |
| 193 |
<blockquote><pre>curl -X PUT -HContent-type:text/plain --data "The play's the thing Wherein I'll catch the conscience of the king" http://127.0.0.1:9998/storage/containers/quotes/3 </pre></blockquote> |
| 194 |
<p>A new search shows that the content has been updated, because the digest is different and the last modified time is more recent:</p> |
| 195 |
<blockquote><pre><container> |
| 196 |
<item> |
| 197 |
<digest><b>36d586647af7886aadbc21f238cee7740cf319e9</b></digest> |
| 198 |
<lastModified><b>2007-01-10T15:46:46+01:00</b></lastModified> |
| 199 |
<mimeType>text/plain</mimeType> |
| 200 |
<name>3</name> |
| 201 |
<uri>http://127.0.0.1:9998/storage/containers/quotes/3</uri> |
| 202 |
</item> |
| 203 |
<name>quotes</name> |
| 204 |
<uri>http://127.0.0.1:9998/storage/containers/quotes</uri> |
| 205 |
</container></pre></blockquote> |
| 206 |
<p>Get the updated contents of item 3:</p> |
| 207 |
<blockquote><pre>curl http://127.0.0.1:9998/storage/containers/quotes/3</pre></blockquote> |
| 208 |
<p>which returns the following:</p> |
| 209 |
<blockquote><pre>The play's the thing Wherein I'll catch the conscience of the king</pre></blockquote> |
| 210 |
<p>Delete item 3:</p> |
| 211 |
<blockquote><pre>curl -X DELETE http://127.0.0.1:9998/storage/containers/quotes/3</pre></blockquote> |
| 212 |
<p>A new search using 'king' returns no items.</p> |
| 213 |
<p>Delete container 'quotes':</p> |
| 214 |
<blockquote><pre>curl -X DELETE http://127.0.0.1:9998/storage/containers/quotes</pre></blockquote> |
| 215 |
<p>The state of the service is now equivalent to that of a newly started storage service.</p> |
| 216 |
|
| 217 |
<h2>Caching of content</h2> |
| 218 |
<p>The getting of item 3 in the previous example supports the HTTP features <code>Last-Modified</code> |
| 219 |
and <code>ETag</code>. The following shows a set of HTTP requests and responses |
| 220 |
from the Firefox web browser to the web storage service that highlights the |
| 221 |
caching mechanism. (The headers can be viewed using Firefox's <a href="https://addons.mozilla.org/en-US/firefox/addon/live-http-headers/">LiveHTTPHeaders</a> plugin, |
| 222 |
available from the Firefox Tools menu after installation.)</p> |
| 223 |
<p>Request, initial query to <a href="http://127.0.0.1:9998/storage/containers/quotes/3">http://127.0.0.1:9998/storage/containers/quotes/3</a>:</p> |
| 224 |
<blockquote><pre>GET /storage/containers/quotes/3 HTTP/1.1 |
| 225 |
Host: 127.0.0.1:9998 |
| 226 |
User-Agent: Mozilla/5.0 (X11; U; SunOS i86pc; en-US; rv:1.8.1) Gecko/20061024 Firefox/2.0 |
| 227 |
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5 |
| 228 |
Accept-Language: en-us,en;q=0.5 |
| 229 |
Accept-Encoding: gzip,deflate |
| 230 |
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7 |
| 231 |
Keep-Alive: 300 |
| 232 |
Connection: keep-alive |
| 233 |
</pre></blockquote> |
| 234 |
<p>Response</p> |
| 235 |
<blockquote><pre>HTTP/1.1 200 OK |
| 236 |
Last-modified: Wed, 10 Jan 2007 15:12:05 GMT |
| 237 |
Content-type: text/plain |
| 238 |
Etag: "-71240529c42b5b92e3086e624618d19164658616" |
| 239 |
Transfer-encoding: chunked |
| 240 |
|
| 241 |
21 |
| 242 |
catch the conscience of the king |
| 243 |
|
| 244 |
0 |
| 245 |
</pre></blockquote> |
| 246 |
<p>The response includes the <code>Last-Modified</code> and <code>ETag</code> |
| 247 |
header fields in the response.</p> |
| 248 |
<p>Getting the same item again:</p> |
| 249 |
<p>Request</p> |
| 250 |
<blockquote><pre>GET /storage/containers/quotes/3 HTTP/1.1 |
| 251 |
Host: 127.0.0.1:9998 |
| 252 |
User-Agent: Mozilla/5.0 (X11; U; SunOS i86pc; en-US; rv:1.8.1) Gecko/20061024 Firefox/2.0 |
| 253 |
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5 |
| 254 |
Accept-Language: en-us,en;q=0.5 |
| 255 |
Accept-Encoding: gzip,deflate |
| 256 |
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7 |
| 257 |
Keep-Alive: 300 |
| 258 |
Connection: keep-alive |
| 259 |
If-Modified-Since: Wed, 10 Jan 2007 15:12:05 GMT |
| 260 |
If-None-Match: "-71240529c42b5b92e3086e624618d19164658616" |
| 261 |
|
| 262 |
</pre></blockquote> |
| 263 |
<p>Response</p> |
| 264 |
<blockquote><pre>HTTP/1.1 304 Not Modified |
| 265 |
Content-length: 0 |
| 266 |
Etag: "-71240529c42b5b92e3086e624618d19164658616" |
| 267 |
|
| 268 |
</pre></blockquote> |
| 269 |
|
| 270 |
<p>The request contains the <code>Last-Modified</code> and <code>ETag</code> |
| 271 |
returned in the first response in the <code>If-Modified-Since</code> |
| 272 |
and <code>If-None-Match</code> header fields. The response contains |
| 273 |
no content, and a 304 status code is returned because the item has not |
| 274 |
been modified (updated).</p> |
| 275 |
<p>Getting the updated item:</p> |
| 276 |
<p>Request</p> |
| 277 |
<blockquote><pre>GET /storage/containers/quotes/3 HTTP/1.1 |
| 278 |
Host: 127.0.0.1:9998 |
| 279 |
User-Agent: Mozilla/5.0 (X11; U; SunOS i86pc; en-US; rv:1.8.1) Gecko/20061024 Firefox/2.0 |
| 280 |
Accept: text/xml,application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,image/png,*/*;q=0.5 |
| 281 |
Accept-Language: en-us,en;q=0.5 |
| 282 |
Accept-Encoding: gzip,deflate |
| 283 |
Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7 |
| 284 |
Keep-Alive: 300 |
| 285 |
Connection: keep-alive |
| 286 |
If-Modified-Since: Wed, 10 Jan 2007 15:12:05 GMT |
| 287 |
If-None-Match: "-71240529c42b5b92e3086e624618d19164658616" |
| 288 |
|
| 289 |
</pre></blockquote> |
| 290 |
<p>Response</p> |
| 291 |
<blockquote><pre>HTTP/1.1 200 OK |
| 292 |
Last-modified: Wed, 10 Jan 2007 15:14:17 GMT |
| 293 |
Content-type: text/plain |
| 294 |
Etag: "36d586647af7886aadbc21f238cee7740cf319e9" |
| 295 |
Transfer-encoding: chunked |
| 296 |
|
| 297 |
43 |
| 298 |
The play's the thing Wherein I'll catch the conscience of the king |
| 299 |
|
| 300 |
0 |
| 301 |
|
| 302 |
</pre></blockquote> |
| 303 |
<p>Since item 3 has been updated, the <code>If-Modified-Since</code> |
| 304 |
and <code>If-None-Match</code> of the request do not result in |
| 305 |
a 304 response being returned. The updated content is returned |
| 306 |
with the latest <code>Last-Modified</code> and <code>ETag</code> |
| 307 |
values.</p> |
| 308 |
</body></html> |