From e5f2e4151f8b7a3cb5654a86e07309f4ef5a8903 Mon Sep 17 00:00:00 2001 From: Mark Pollack Date: Fri, 8 Apr 2011 01:37:29 -0400 Subject: [PATCH] update docs add remove method on mongotemplate to MongoOperations change Venue to use primitive arrays --- .../document/mongodb/MongoOperations.java | 13 +- .../data/document/mongodb/PersonExample.java | 9 + .../data/document/mongodb/Venue.java | 16 +- src/docbkx/reference/mongodb.xml | 367 +++++++++++++----- 4 files changed, 299 insertions(+), 106 deletions(-) diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoOperations.java b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoOperations.java index b83792ae6..6403231bf 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/MongoOperations.java +++ b/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 * @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 + */ + void remove(String collectionName, Query query, Class targetClass); } \ No newline at end of file diff --git a/spring-data-mongodb/src/test/java/org/springframework/data/document/mongodb/PersonExample.java b/spring-data-mongodb/src/test/java/org/springframework/data/document/mongodb/PersonExample.java index 7a8e32e06..ba238f456 100644 --- a/spring-data-mongodb/src/test/java/org/springframework/data/document/mongodb/PersonExample.java +++ b/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); + + } + } diff --git a/spring-data-mongodb/src/test/java/org/springframework/data/document/mongodb/Venue.java b/spring-data-mongodb/src/test/java/org/springframework/data/document/mongodb/Venue.java index 72a51137c..02320beec 100644 --- a/spring-data-mongodb/src/test/java/org/springframework/data/document/mongodb/Venue.java +++ b/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() { diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index 282e27593..ed7b70550 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/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. + The MongoTemplate class implements the + interface MongoOperations. In as much as + possible, the methods on MongoOperations + are named after methods available on the MongoDB driver + Collection 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 + MongoOperations. The difference in betwee + the two is that MongOperations can be passed domain objects instead of + DBObject and there are fluent APIs for + Query, Criteria, and + Update operations instead of + DBObject.. + + + The preferred way to reference the operations on + MongoTemplate instance is via its interface + MongoOperations. + + The default converter implementation used by MongoTemplate is SimpleMappingConverter, which as the name implies, @@ -401,11 +422,13 @@ public class AppConfig {
- Saving, Updating, and Deleting Documents + Saving, Updating, and Removing Documents 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 + MongoDB. + + Given a simple class such as Person public class Person { @@ -466,16 +489,49 @@ remove using query: { "_id" : { "$oid" : "4d9e82ac94fa72c65a9e7d5f"}} Number of people = : 0 There was implicit conversion using SimpleMongoConverter between a - String and ObjectId as stored in the database. + String and ObjectId as stored in the database and recognizing a convention + of the property "Id" name. + + + This example is meant to show the use of save, update and remove + operations on MongoTemplate and not to show complex mapping + functionality + + + The query stynax used in the example is explained in more detail in + the section Querying Documents.
- Methods for saving documents + Methods for saving and inserting documents - 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 - org.springframework.data.document.mongodb.query.Criteria.where - to make the query more readable. + There are several convenient methods on MongoTemplate for saving + and inserting your objects. In addition to using a + MongoCoverter to converter your domain + object to the database, you can also use an implementation of the + MongoWriter interface to have very fine + grained control over the conversion process. + + + The difference between insert and save operations is that a save + operation will perform an insert if the object is not already + present. + + + 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. + + 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 + String, ObjectId, or + BigInteger. + + Here is a basic example of using the save operation and retrieving + its contents. 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><T> void</literal> <emphasis + role="bold">insert </emphasis> <literal>(T objectToSave, + MongoWriter<T> writer) </literal> Insert the object into the + default collection using the provided writer.</para> + </listitem> + + <listitem> + <para><literal><T> void</literal> <emphasis + role="bold">insert </emphasis> <literal>(String collectionName, T + objectToSave, MongoWriter<T> 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 + + 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 + + + + void insertList (List<? extends + Object> listToSave) Insert a + list of objects into the default collection in a single batch + write to the database. + + + + void insertList (String + collectionName, List<? extends Object> + listToSave) Insert a list of + objects into the specified collection in a single batch write to + the database. + + + + <T> void insertList (List<? extends + T> listToSave, MongoWriter<T> writer) + Insert the object into the default + collection using the provided writer. + + + + <T> void insertList(String + collectionName, List<? extends T> listToSave, + MongoWriter<T> writer) Insert a list of objects + into the specified collection using the provided MongoWriter + instance + + +
Updating documents in a collection For updates we can elect to update the first document found using + MongoOperation's method updateFirst or we can update all documents that were - found to match the query usingupdateMulti. 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 $inc - operator. + found to match the query using the method + updateMulti. 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 $inc operator. Updating documents using the MongoTemplate 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)); @@ -672,81 +806,24 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
-
- Methods for inserting documents - - - - void insert - (Object objectToSave) Insert the - object into the default collection. - - - - void insert - (String collectionName, Object objectToSave) - Insert the object into the specified collection. - - - - void insertList - (List<? extends Object> listToSave) - Insert a list of objects into the default collection in - a single batch write to the database. - - - - void insertList - (String collectionName, List<? extends - Object> listToSave) Insert a list of objects into - the specified collection in a single batch write to the - database. - - - - <T> void insert (T objectToSave, - MongoWriter<T> writer) Insert the object into the - default collection. - - - - <T> void insert (String collectionName, T - objectToSave, MongoWriter<T> writer) Insert the - object into the specified collection. - - - - <T> void insertList (List<? extends - T> listToSave, MongoWriter<T> writer) Insert a - list of objects into the default collection using the provided - MongoWriter instance - - - - <T> void insertList (String - collectionName, List<? extends T> listToSave, - MongoWriter<T> writer) Insert a list of objects - into the specified collection using the provided MongoWriter - instance - - - - -
-
Methods for removing documents + You can use several overloaded methods to remove an object from + the database. + - void remove - (Query query) Remove all documents - from the default collection that match the provided query document - criteria. + void remove (Object object) + Remove the given object from the collection by Id + + + + void remove (Query query) + Remove all documents from the default collection that match the + provided query document criteria. @@ -755,16 +832,41 @@ import static org.springframework.data.document.mongodb.query.Criteria.query; Remove all documents from the specified collection that match the provided query document criteria. + + + <T> void remove (Query query, + Class<T> targetClass) 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. + + + + <T> void remove (String collectionName, + Query query, Class<T> targetClass)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 +
-
+
Querying Documents - Query, Criteria + 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. + + GeoSpatial queries are also supported and are described more in the + section GeoSpatial Queries. @@ -1115,10 +1217,91 @@ import static org.springframework.data.document.mongodb.query.Criteria.query;
-
+
GeoSpatial Queries - + MongoDB supports GeoSpatial queries through the use of operators + such as $near, $within, and + $nearSphere. Methods specific to geospatial queries + are available on the Criteria class. There are + also a few shape classes, Box, + Circle, and Point that are + used in conjunction with geospatial related Criteria methods. + + 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 MappingMongoConverter. + + @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) + "]"; + } +} + + To find locations within a circle, the following query can be + used. + + Circle circle = new Circle(-73.99171, 40.738868, 0.01); +List<Venue> venues = template.find(new Query(Criteria.where("location").withinCenter(circle)), Venue.class); + + To find venues within a circle using Spherical coordinates the + following query can be used + + Circle circle = new Circle(-73.99171, 40.738868, 0.003712240453784); +List<Venue> venues = template.find(new Query(Criteria.where("location").withinCenterSphere(circle)), Venue.class); + + To find venues within a Box the following query can be used + + Box box = new Box(new Point(-73.99756, 40.73083), new Point(-73.988135, 40.741404)); //lower-left then upper-right +List<Venue> venues = template.find(new Query(Criteria.where("location").withinBox(box)), Venue.class); + + To find venues near a Point, the following query can be + used + + Point point = new Point(-73.99171, 40.738868); +List<Venue> venues = template.find(new Query(Criteria.where("location").near(point).maxDistance(0.01)), Venue.class); + + To find venues near a Point using Spherical coordines the + following query can be used + + Point point = new Point(-73.99171, 40.738868); +List<Venue> venues = template.find(new Query(Criteria.where("location").nearSphere(point).maxDistance(0.003712240453784)), Venue.class); + + + + Support for the GeoNear command will be provided in the RC + release. +