update docs

add remove method on mongotemplate to MongoOperations
change Venue to use primitive arrays

spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoOperations.java

@@ -707,8 +707,8 @@ public interface MongoOperations {
   void remove(Query query);
   
   /**
-   * Remove all documents from the default collection that matchthe provided query document critera.  The
-   * Class parameter is use to help convert the Id of the object if it is present in the query.
+   * Remove all documents from the default collection that match the provided query document criteria.  The
+   * Class parameter is used to help convert the Id of the object if it is present in the query.
    * @param <T>
    * @param query
    * @param targetClass
@@ -722,5 +722,14 @@ public interface MongoOperations {
    * @param queryDoc       the query document that specifies the criteria used to remove a record
    */
   void remove(String collectionName, Query query);
+  
+  /**
+   * Remove all documents from the specified collection that match the provided query document criteria.
+   * The Class parameter is used to help convert the Id of the object if it is present in the query.
+   * @param collectionName
+   * @param query
+   * @param targetClass
+   */
+  <T> void remove(String collectionName, Query query, Class<T> targetClass);
 
 }

spring-data-mongodb/src/test/java/org/springframework/data/document/mongodb/PersonExample.java

@@ -76,5 +76,14 @@ public class PersonExample {
     
   }
   
+  public void doWork2() {
+    mongoOps.dropCollection("personexample");
+    
+    PersonWithIdPropertyOfTypeString p = new PersonWithIdPropertyOfTypeString();
+    p.setFirstName("Sven");
+    p.setAge(22);
+     
+  }
+  
   
 }

spring-data-mongodb/src/test/java/org/springframework/data/document/mongodb/Venue.java

@@ -27,10 +27,10 @@ public class Venue {
   @Id
   private String id;
   private String name;
-  private Double[] location;
+  private double[] location;
   
   @PersistenceConstructor
-  Venue(String name, Double[] location) {
+  Venue(String name, double[] location) {
     super();
     this.name = name;
     this.location = location;    
@@ -39,24 +39,16 @@ public class Venue {
   public Venue(String name, double x, double y) {
     super();
     this.name = name;
-    this.location = new Double[] { x, y };    
+    this.location = new double[] { x, y };    
   }
 
   public String getName() {
     return name;
   }
 
-  public Double[] getLocation() {
+  public double[] getLocation() {
     return location;
   }
-  
-  public String getId() {
-    return id;
-  }
-
-  public void setId(String id) {
-    this.id = id;
-  }
 
   @Override
   public String toString() {

src/docbkx/reference/mongodb.xml

@@ -268,6 +268,27 @@ public class AppConfig {
     own converter. Please refer to the section on MongoCoverters for more
     detailed information.</para>
 
+    <para>The <classname>MongoTemplate</classname> class implements the
+    interface <interfacename>MongoOperations</interfacename>. In as much as
+    possible, the methods on <interfacename>MongoOperations</interfacename>
+    are named after methods available on the MongoDB driver
+    <classname>Collection</classname> object. For example, you will find
+    methods such as "find", "findAndModify", "findOne", "insert", "remove",
+    "save", "update" and "updateMulti". The design goal was to make it as easy
+    as possible to transition between the use of the base MongoDB driver and
+    <interfacename>MongoOperations</interfacename>. The difference in betwee
+    the two is that MongOperations can be passed domain objects instead of
+    <classname>DBObject</classname> and there are fluent APIs for
+    <classname>Query</classname>, <classname>Criteria</classname>, and
+    <classname>Update</classname> operations instead of
+    <classname>DBObject</classname>..</para>
+
+    <note>
+      <para>The preferred way to reference the operations on
+      <classname>MongoTemplate</classname> instance is via its interface
+      <interfacename>MongoOperations</interfacename>.</para>
+    </note>
+
     <para>The default converter implementation used by
     <classname>MongoTemplate</classname> is
     <classname>SimpleMappingConverter</classname>, which as the name implies,
@@ -401,11 +422,13 @@ public class AppConfig {
   </section>
 
   <section>
-    <title>Saving, Updating, and Deleting Documents</title>
+    <title>Saving, Updating, and Removing Documents</title>
 
     <para>MongoTemplate provides a simple way for you to save, update, and
     delete your domain objects and map those objects to documents stored in
-    MongoDB. Given a simple class such as Person</para>
+    MongoDB. </para>
+
+    <para>Given a simple class such as Person</para>
 
     <programlisting>public class Person {
 
@@ -466,16 +489,49 @@ remove using query: { "_id" : { "$oid" : "4d9e82ac94fa72c65a9e7d5f"}}
 Number of people = : 0</programlisting>
 
     <para>There was implicit conversion using SimpleMongoConverter between a
-    String and ObjectId as stored in the database.</para>
+    String and ObjectId as stored in the database and recognizing a convention
+    of the property "Id" name. </para>
+
+    <note>
+      <para>This example is meant to show the use of save, update and remove
+      operations on MongoTemplate and not to show complex mapping
+      functionality</para>
+    </note>
+
+    <para>The query stynax used in the example is explained in more detail in
+    the section <link linkend="mongo.query">Querying Documents</link>.</para>
 
     <section>
-      <title>Methods for saving documents</title>
+      <title>Methods for saving and inserting documents</title>
 
-      <para>Once we have created the collection and maybe an index we can
-      start using the collection to store our domain objects as documents.
-      Note that we are using a static import for
-      <classname>org.springframework.data.document.mongodb.query.Criteria.where</classname>
-      to make the query more readable.</para>
+      <para>There are several convenient methods on MongoTemplate for saving
+      and inserting your objects. In addition to using a
+      <interfacename>MongoCoverter</interfacename> to converter your domain
+      object to the database, you can also use an implementation of the
+      <interfacename>MongoWriter</interfacename> interface to have very fine
+      grained control over the conversion process.</para>
+
+      <note>
+        <para>The difference between insert and save operations is that a save
+        operation will perform an insert if the object is not already
+        present.</para>
+      </note>
+
+      <para>The simple case of using the save operation is to pass in as an
+      argument only the object to save. In this case the default collection
+      assigned to the template will be used unless the converter overrides
+      this default through the use of more specific mapping metadata. You may
+      also call the save operation with a specific collection name. </para>
+
+      <para>When inserting or saving, if the Id property is not set, the
+      assumption is that its value will be autogenerated by the database. As
+      such, for autogeneration of an ObjectId to succeed the type of the Id
+      property/field in your class must be either a
+      <classname>String</classname>, <classname>ObjectId</classname>, or
+      <classname>BigInteger</classname>.</para>
+
+      <para>Here is a basic example of using the save operation and retrieving
+      its contents.</para>
 
       <example>
         <title>Inserting and retrieving documents using the
@@ -489,10 +545,13 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
           Person p = new Person("Bob", 33);
           mongoTemplate.insert("MyCollection", p);
 
-          Person qp = mongoTemplate.findOne("MyCollection", query(where("id").is(p.getId())), Person.class);
+          Person qp = mongoTemplate.findOne("MyCollection", query(where("age").is(33)), Person.class);
         </programlisting>
       </example>
 
+      <para>The four save operations available to you are listed below.
+      </para>
+
       <para><itemizedlist>
           <listitem>
             <para><literal>void</literal> <emphasis role="bold">save
@@ -521,29 +580,104 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
           </listitem>
         </itemizedlist></para>
 
-      <para></para>
+      <para>A similar set of insert operations is listed below </para>
+
+      <para><itemizedlist>
+          <listitem>
+            <para><literal>void</literal> <emphasis
+            role="bold">insert</emphasis> <literal>(Object objectToSave)
+            </literal> Insert the object to the default collection.</para>
+          </listitem>
+
+          <listitem>
+            <para><literal>void</literal> <emphasis role="bold">insert
+            </emphasis> <literal>(String collectionName, Object objectToSave)
+            </literal> Insert the object to the specified collection.</para>
+          </listitem>
+
+          <listitem>
+            <para><literal>&lt;T&gt; void</literal> <emphasis
+            role="bold">insert </emphasis> <literal>(T objectToSave,
+            MongoWriter&lt;T&gt; writer) </literal> Insert the object into the
+            default collection using the provided writer.</para>
+          </listitem>
+
+          <listitem>
+            <para><literal>&lt;T&gt; void</literal> <emphasis
+            role="bold">insert </emphasis> <literal>(String collectionName, T
+            objectToSave, MongoWriter&lt;T&gt; writer) </literal> Insert the
+            object into the specified collection using the provided
+            writer.</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <section>
+        <title>Inserting Lists of objects in batch</title>
+
+        <para>The MongoDB driver supports inserting a collection of documents
+        in one operation. The methods in the MongoOperations interface that
+        support this functionality are listed below</para>
+
+        <para><itemizedlist>
+            <listitem>
+              <para><literal>void</literal> <emphasis
+              role="bold">insertList</emphasis><literal> (List&lt;? extends
+              Object&gt; listToSave)</literal><literal> </literal> Insert a
+              list of objects into the default collection in a single batch
+              write to the database.</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>void</literal> <emphasis
+              role="bold">insertList</emphasis> <literal>(String
+              collectionName, List&lt;? extends Object&gt;
+              listToSave)</literal><literal> </literal>Insert a list of
+              objects into the specified collection in a single batch write to
+              the database.</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>&lt;T&gt; void</literal> <emphasis
+              role="bold">insertList</emphasis><literal> (List&lt;? extends
+              T&gt; listToSave, MongoWriter&lt;T&gt; writer)</literal>
+              <literal></literal> Insert the object into the default
+              collection using the provided writer.</para>
+            </listitem>
+
+            <listitem>
+              <para><literal>&lt;T&gt; void</literal> <emphasis
+              role="bold">insertList</emphasis><literal>(String
+              collectionName, List&lt;? extends T&gt; listToSave,
+              MongoWriter&lt;T&gt; writer)</literal> Insert a list of objects
+              into the specified collection using the provided MongoWriter
+              instance</para>
+            </listitem>
+          </itemizedlist></para>
+      </section>
     </section>
 
     <section id="mongodb-template-update">
       <title>Updating documents in a collection</title>
 
       <para>For updates we can elect to update the first document found using
+      <interfacename>MongoOperation</interfacename>'s method
       <literal>updateFirst</literal> or we can update all documents that were
-      found to match the query using<literal>updateMulti</literal>. Here is an
-      example of an update of all SAVINGS accounts where we are adding a one
-      time $50.00 bonus to the balance using the <literal>$inc</literal>
-      operator.</para>
+      found to match the query using the method
+      <literal>updateMulti</literal>. Here is an example of an update of all
+      SAVINGS accounts where we are adding a one time $50.00 bonus to the
+      balance using the <literal>$inc</literal> operator.</para>
 
       <example>
         <title>Updating documents using the MongoTemplate</title>
 
         <programlisting language="java">import static org.springframework.data.document.mongodb.query.Criteria.where;
+import static org.springframework.data.document.mongodb.query.Query.query;
+import static org.springframework.data.document.mongodb.query.Update
 
           ...
 
-          WriteResult wr = mongoTemplate.updateMulti(
-          new Query(where("accounts.accountType").is(Account.Type.SAVINGS)),
-          new Update().inc("accounts.$.balance", 50.00));
+          WriteResult wr = mongoTemplate.updateMulti(query(where("accounts.accountType").is(Account.Type.SAVINGS)),
+                                                     update.inc("accounts.$.balance", 50.00));
         </programlisting>
       </example>
 
@@ -672,81 +806,24 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
       </section>
     </section>
 
-    <section>
-      <title>Methods for inserting documents</title>
-
-      <para><itemizedlist>
-          <listitem>
-            <para><literal>void</literal> <emphasis role="bold">insert
-            </emphasis> <literal>(Object objectToSave) </literal> Insert the
-            object into the default collection.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>void</literal> <emphasis role="bold">insert
-            </emphasis> <literal>(String collectionName, Object objectToSave)
-            </literal> Insert the object into the specified collection.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>void</literal> <emphasis role="bold">insertList
-            </emphasis> <literal>(List&lt;? extends Object&gt; listToSave)
-            </literal> Insert a list of objects into the default collection in
-            a single batch write to the database.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>void</literal> <emphasis role="bold">insertList
-            </emphasis> <literal>(String collectionName, List&lt;? extends
-            Object&gt; listToSave) </literal> Insert a list of objects into
-            the specified collection in a single batch write to the
-            database.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>&lt;T&gt; void</literal> <emphasis
-            role="bold">insert </emphasis> <literal>(T objectToSave,
-            MongoWriter&lt;T&gt; writer) </literal> Insert the object into the
-            default collection.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>&lt;T&gt; void</literal> <emphasis
-            role="bold">insert </emphasis> <literal>(String collectionName, T
-            objectToSave, MongoWriter&lt;T&gt; writer) </literal> Insert the
-            object into the specified collection.</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>&lt;T&gt; void</literal> <emphasis
-            role="bold">insertList </emphasis> <literal>(List&lt;? extends
-            T&gt; listToSave, MongoWriter&lt;T&gt; writer) </literal> Insert a
-            list of objects into the default collection using the provided
-            MongoWriter instance</para>
-          </listitem>
-
-          <listitem>
-            <para><literal>&lt;T&gt; void</literal> <emphasis
-            role="bold">insertList </emphasis> <literal>(String
-            collectionName, List&lt;? extends T&gt; listToSave,
-            MongoWriter&lt;T&gt; writer) </literal> Insert a list of objects
-            into the specified collection using the provided MongoWriter
-            instance</para>
-          </listitem>
-        </itemizedlist></para>
-
-      <para></para>
-    </section>
-
     <section>
       <title>Methods for removing documents</title>
 
+      <para>You can use several overloaded methods to remove an object from
+      the database. </para>
+
       <para><itemizedlist>
           <listitem>
-            <para><literal>void</literal> <emphasis role="bold">remove
-            </emphasis> <literal>(Query query)</literal> Remove all documents
-            from the default collection that match the provided query document
-            criteria.</para>
+            <para><literal>void</literal> <emphasis
+            role="bold">remove</emphasis> <literal>(Object object)</literal>
+            Remove the given object from the collection by Id</para>
+          </listitem>
+
+          <listitem>
+            <para><literal>void</literal> <emphasis
+            role="bold">remove</emphasis> <literal>(Query query)</literal>
+            Remove all documents from the default collection that match the
+            provided query document criteria.</para>
           </listitem>
 
           <listitem>
@@ -755,16 +832,41 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
             </literal> Remove all documents from the specified collection that
             match the provided query document criteria.</para>
           </listitem>
+
+          <listitem>
+            <para><literal>&lt;T&gt; void </literal><emphasis
+            role="bold">remove</emphasis> <literal>(Query query,
+            Class&lt;T&gt; targetClass)</literal> Same behavior as the
+            remove(Query) method but the Class parameter is used to help
+            convert the Id of the object if it is present in the query.</para>
+          </listitem>
+
+          <listitem>
+            <para><literal>&lt;T&gt; void </literal><emphasis
+            role="bold">remove</emphasis> <literal>(String collectionName,
+            Query query, Class&lt;T&gt; targetClass)</literal>Same behavior as
+            remove(Query, Class) but the Class parameter is used to help
+            convert the Id of the object if it is present in the uqery</para>
+          </listitem>
         </itemizedlist></para>
 
       <para></para>
     </section>
   </section>
 
-  <section>
+  <section id="mongo.query">
     <title>Querying Documents</title>
 
-    <para>Query, Criteria</para>
+    <para>You can express you queries using the Query and Criteria classes
+    which have method names that mirror the native MongoDB operator names such
+    as lt, lte, is, and others. The Query and Criteria classes follow a fluent
+    API style so that you can easily chain together multiple method criteria
+    and queries while having easy to understand code. Static imports in Java
+    are used to help remove the need to see the 'new' keyword for creating
+    Query and Criteria instances so as to improve readability. </para>
+
+    <para>GeoSpatial queries are also supported and are described more in the
+    section <link linkend="mongo.geospatial">GeoSpatial Queries</link>.</para>
 
     <para></para>
 
@@ -1115,10 +1217,91 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
       <para></para>
     </section>
 
-    <section>
+    <section id="mongo.geospatial" lang="">
       <title>GeoSpatial Queries</title>
 
-      <para></para>
+      <para>MongoDB supports GeoSpatial queries through the use of operators
+      such as <literal>$near</literal>, <literal>$within</literal>, and
+      <literal>$nearSphere</literal>. Methods specific to geospatial queries
+      are available on the <classname>Criteria</classname> class. There are
+      also a few shape classes, <classname>Box</classname>,
+      <classname>Circle</classname>, and <classname>Point</classname> that are
+      used in conjunction with geospatial related Criteria methods. </para>
+
+      <para>To understand how to perform GeoSpatial queries we will use the
+      following Venue class taken from the integration tests.which relies on
+      using the rich <classname>MappingMongoConverter</classname>.</para>
+
+      <programlisting language="java">@Document(collection="newyork")
+public class Venue {
+    
+  @Id
+  private String id;
+  private String name;
+  private double[] location;
+  
+  @PersistenceConstructor
+  Venue(String name, double[] location) {
+    super();
+    this.name = name;
+    this.location = location;    
+  }
+  
+  public Venue(String name, double x, double y) {
+    super();
+    this.name = name;
+    this.location = new double[] { x, y };    
+  }
+
+  public String getName() {
+    return name;
+  }
+
+  public double[] getLocation() {
+    return location;
+  }
+
+  @Override
+  public String toString() {
+    return "Venue [id=" + id + ", name=" + name + ", location="
+        + Arrays.toString(location) + "]";
+  } 
+}</programlisting>
+
+      <para>To find locations within a circle, the following query can be
+      used.</para>
+
+      <programlisting lang="java">Circle circle = new Circle(-73.99171, 40.738868, 0.01);
+List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").withinCenter(circle)), Venue.class);</programlisting>
+
+      <para>To find venues within a circle using Spherical coordinates the
+      following query can be used</para>
+
+      <programlisting lang="java">Circle circle = new Circle(-73.99171, 40.738868, 0.003712240453784);
+List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").withinCenterSphere(circle)), Venue.class);</programlisting>
+
+      <para>To find venues within a Box the following query can be used</para>
+
+      <programlisting>Box box = new Box(new Point(-73.99756, 40.73083), new Point(-73.988135, 40.741404));  //lower-left then upper-right
+List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").withinBox(box)), Venue.class);</programlisting>
+
+      <para>To find venues near a Point, the following query can be
+      used</para>
+
+      <programlisting>Point point = new Point(-73.99171, 40.738868);
+List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").near(point).maxDistance(0.01)), Venue.class);</programlisting>
+
+      <para>To find venues near a Point using Spherical coordines the
+      following query can be used</para>
+
+      <programlisting>Point point = new Point(-73.99171, 40.738868);
+List&lt;Venue&gt; venues = template.find(new Query(Criteria.where("location").nearSphere(point).maxDistance(0.003712240453784)), Venue.class);
+</programlisting>
+
+      <note>
+        <para>Support for the GeoNear command will be provided in the RC
+        release.</para>
+      </note>
     </section>
   </section>