DATAMONGO-1275 - Added documentation for optimistic locking.

Original pull request: #318.

Author: christophstrobl

src/main/asciidoc/reference/mapping.adoc

@@ -211,6 +211,7 @@ The MappingMongoConverter can use metadata to drive the mapping of objects to do
 * `@PersistenceConstructor` - marks a given constructor - even a package protected one - to use when instantiating the object from the database. Constructor arguments are mapped by name to the key values in the retrieved DBObject.
 * `@Value` - this annotation is part of the Spring Framework . Within the mapping framework it can be applied to constructor arguments. This lets you use a Spring Expression Language statement to transform a key's value retrieved in the database before it is used to construct a domain object. In order to reference a property of a given document one has to use expressions like: `@Value("#root.myProperty")` where `root` refers to the root of the given document.
 * `@Field` - applied at the field level and described the name of the field as it will be represented in the MongoDB BSON document thus allowing the name to be different than the fieldname of the class.
+* `@Version` - applied at field level is used for optimistic locking and checked for modification on save operations. The initial value is `zero` which is bumped automatically on every update.
 
 The mapping metadata infrastructure is defined in a seperate spring-data-commons project that is technology agnostic. Specific subclasses are using in the MongoDB support to support annotation based metadata. Other strategies are also possible to put in place if there is demand.
 

src/main/asciidoc/reference/mongodb.adoc

@@ -938,6 +938,40 @@ You can use several overloaded methods to remove an object from the database.
 
 * *remove* Remove the given document based on one of the following: a specific object instance, a query document criteria combined with a class or a query document criteria combined with a specific collection name.
 
+[[mongo-template.optimistic-locking]]
+=== Optimistic locking
+
+The `@Version` annotation provides a JPA similar semantic in the context of MongoDB and makes sure updates are only applied to documents with matching version. Therefore the actual value of the version property is added to the update query in a way that the update won't have any effect if another operation altered the document in between. In that case an `OptimisticLockingFailureException` is thrown.
+
+====
+[source,java]
+----
+@Document
+class Person {
+
+  @Id String id;
+  String firstname;
+  String lastname;
+  @Version Long version;
+}
+
+Person daenerys = template.insert(new Person("Daenerys"));                           <1>
+
+Person tmp = teplate.findOne(query(where("id").is(daenerys.getId())), Person.class); <2>
+
+daenerys.setLastname("Targaryen");
+template.save(daenerys);                                                             <3>
+
+template.save(tmp); // throws OptimisticLockingFailureException                      <4>
+----
+<1> Intially insert document. `version` is set to `0`.
+<2> Load the just inserted document `version` is still `0`.
+<3> Update document with `version = 0`. Set the `lastname` and bump `version` to `1`.
+<4> Try to update previously loaded document sill having `version = 0` fails with `OptimisticLockingFailureException` as the current `version` is `1`.
+====
+
+IMPORTANT: Using MongoDB driver version 3 requires to set the `WriteConcern` to `ACKNOWLEDGED`. Otherwise `OptimisticLockingFailureException` can be silently swallowed.
+
 [[mongo.query]]
 == Querying Documents