# Optimistic Concurrency Example

This example demonstrates how to apply optimistic concurrency to a web resource. Optimistic concurrency control prevents the locking of a web resource that will be updated, ensuring that other users can concurrently access or update that web resource. The clients must resolve any conflict reported by the server. This ensures that clients cannot overwrite each other's changes to that web resource.

This example follows a design like the one in the Google Data API for the update of Atom entries.

## Contents

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

`com.sun.jersey.samples.optimisticconcurrency.resources.ItemResource`
  This resource class provides meta-data information on the URIs to content resources that can be read and updated. JAXB is used to represent the meta-data as an XML document. The resource references the ItemContentResource resource using the Path annotation declared on the ItemResource.getItemContentResource method.
`com.sun.jersey.samples.optimisticconcurrency.resources.ItemContentResource`
  This resource class provides read and update ccess to the content. In this example, the content is stored in memory as a byte array and is not persisted to a file system or database. Update occurs using a sub-resource that implements the PUT method.

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

URI path | Resource class | HTTP methods
--- | --- | ---
/item | ItemResource | GET
/item/content | ItemContentResource | GET
/item/content/{version} | ItemContentResource | PUT

## Running the Example

Run the example as follows:

>     mvn clean compile exec:java

This deploys the Optimistic Concurrency example using Grizzly

A WADL description may be accessed at the URL:

> `http://127.0.0.1:9998/occ/application.wadl`

Following steps are using cURL command line tool:

Get the item meta-data:

>     curl http://127.0.0.1:9998/occ/item

This returns the following XML document:

>     <item>
>         <mediaType>text/plain</mediaType>
>         <updateUri>http://127.0.0.1:9998/occ/item/content/0</updateUri>
>         <uri>http://127.0.0.1:9998/occ/item/content</uri>
>     </item>

The URI to obtain the content is within the `uri` element.

Get the content:

>     curl http://127.0.0.1:9998/occ/item/content

This will return the following text:

>     Today is the first day of the REST of my life

Update the content:

>     curl -i -X PUT --data "All play and no REST makes me a dull boy" -HContent-type:text/plain http://127.0.0.1:9998/occ/item/content/0

The content is updated by PUTing to the URI within the `updateUri` element of the XML document.

Get the item meta-data:

>     curl http://127.0.0.1:9998/occ/item

This returns the following XML document:

>     <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
>     <item>
>         <mediaType>text/plain</mediaType>
>         <updateUri>http://127.0.0.1:9998/occ/item/content/1</updateUri>
>         <uri>http://127.0.0.1:9998/occ/item/content</uri>
>     </item>

The update URI has now changed. Clients updating using the previous URI receive a `409 Conflict` in response.

Repeating the initial update fails:

>     curl -i -X PUT --data "All play and no REST makes me a dull boy" -HContent-type:text/plain http://127.0.0.1:9998/occ/item/content/0

With:

>     HTTP/1.1 409 Conflict
>     server: grizzly/1.8.1
>     Content-Type: text/plain
>     Transfer-Encoding: chunked
>     Date: Tue, 19 Aug 2008 09:52:51 GMT

>     Conflict