Add findAndModify to docs, update test to include findAndModify with upsert

spring-data-mongodb/src/test/java/org/springframework/data/mongodb/core/MongoTemplateTests.java

@@ -428,6 +428,12 @@ public class MongoTemplateTests {
 		assertThat(p.getAge(), is(26));
 		p = template.findOne(query, Person.class);
 		assertThat(p.getAge(), is(27));
+		
+		Query query2 = new Query(Criteria.where("firstName").is("Mary"));
+		p = template.findAndModify(query2, update, new FindAndModifyOptions().returnNew(true).upsert(true), Person.class);
+		assertThat(p.getFirstName(), is("Mary"));
+		assertThat(p.getAge(), is(1));
+		
 	}
 
 	@Test

src/docbkx/reference/mongodb.xml

@@ -1398,6 +1398,54 @@ import static org.springframework.data.mongodb.core.query.Update;
       <programlisting>template.upsert(query(where("ssn").is(1111).and("firstName").is("Joe").and("Fraizer").is("Update")), update("address", addr), Person.class);</programlisting>
     </section>
 
+    <section>
+      <title>Finding and Upserting documents in a collection</title>
+
+      <para>The findAndModify method on DBCollection can update a document and
+      return either the old or newly updated document in a single operation.
+      MongoTemplate provides a findAndModify method that takes Query and
+      Update classes and converts from DBObject to your POJOs. Here are the
+      methods</para>
+
+      <programlisting language="java">	&lt;T&gt; T findAndModify(Query query, Update update, Class&lt;T&gt; entityClass);
+
+	&lt;T&gt; T findAndModify(Query query, Update update, Class&lt;T&gt; entityClass, String collectionName);
+
+	&lt;T&gt; T findAndModify(Query query, Update update, FindAndModifyOptions options, Class&lt;T&gt; entityClass);
+
+	&lt;T&gt; T findAndModify(Query query, Update update, FindAndModifyOptions options, Class&lt;T&gt; entityClass, String collectionName);</programlisting>
+
+      <para>As an example usage, we will insert of few Person objects into the
+      container and perform a simple findAndUpdate operation</para>
+
+      <programlisting language="java">mongoTemplate.insert(new Person("Tom", 21));
+mongoTemplate.insert(new Person("Dick", 22));
+mongoTemplate.insert(new Person("Harry", 23));
+
+Query query = new Query(Criteria.where("firstName").is("Harry"));
+Update update = new Update().inc("age", 1);
+Person p = mongoTemplate.findAndModify(query, update, Person.class); // return's old person object
+
+assertThat(p.getFirstName(), is("Harry"));
+assertThat(p.getAge(), is(23));
+p = mongoTemplate.findOne(query, Person.class);
+assertThat(p.getAge(), is(24));
+
+
+// Now return the newly updated document when updating
+p = template.findAndModify(query, update, new FindAndModifyOptions().returnNew(true), Person.class);
+assertThat(p.getAge(), is(25));</programlisting>
+
+      <para>The <classname>FindAndModifyOptions</classname> lets you set the
+      options of returnNew, upsert, and remove. An example extending off the
+      previous code snippit is shown below</para>
+
+      <programlisting language="java">Query query2 = new Query(Criteria.where("firstName").is("Mary"));
+p = mongoTemplate.findAndModify(query2, update, new FindAndModifyOptions().returnNew(true).upsert(true), Person.class);
+assertThat(p.getFirstName(), is("Mary"));
+assertThat(p.getAge(), is(1));</programlisting>
+    </section>
+
     <section>
       <title>Methods for removing documents</title>
 
@@ -2311,7 +2359,7 @@ public class PersonWriteConverter implements Converter&lt;Person, DBObject&gt; {
       defined on the collectcion. Here is an example that defines an index on
       the Person class that has age property.</para>
 
-      <programlisting>template.indexOps(Person.class).ensureIndex(new Index().on("age", Order.DESCENDING).unique(Duplicates.DROP));
+      <programlisting language="java">template.indexOps(Person.class).ensureIndex(new Index().on("age", Order.DESCENDING).unique(Duplicates.DROP));
 
 List&lt;IndexInfo&gt; indexInfoList = template.indexOps(Person.class).getIndexInfo();