From 9a0e45de837cd71470edf732c9a9ceaaaabeec8a Mon Sep 17 00:00:00 2001 From: Thomas Risberg Date: Thu, 2 Jun 2011 11:54:54 -0400 Subject: [PATCH] DATADOC-147 - Updated reference documentation to cover changes from M2 to M3 --- src/docbkx/reference/mongodb.xml | 358 +++++++++++-------------------- 1 file changed, 128 insertions(+), 230 deletions(-) diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index e1ea1e320..f48e013e4 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/src/docbkx/reference/mongodb.xml @@ -246,19 +246,23 @@ public class MongoApp { Required Jars - The following jars are required to use Sping Mongo + The following jars are required to use Spring Data Mongo spring-data-mongodb-1.0.0.M3.jar + + + spring-data-commons-1.1.0.M1.jar + In addition to the above listed Spring Data jars you need to provide the following dependencies: - com.springsource.org.aopalliance-1.0.0.jar + aopalliance-1.0.0.jar @@ -328,6 +332,12 @@ public class MongoApp { class name or via mapping metadata. + + Reordered parameters in some + MongoTemplate methods to make signatures more + consistent across the board. + + Removed MongoTemplate methods that use MongoReader and @@ -337,14 +347,6 @@ public class MongoApp { details. - - MongoTemplate's update method - arguements from (Query, Update) - to(Class<?>, Query, Update)was updateFirst - takes a java.lang.Class argument as the first - argument. - - Added findById methods to MongoTemplate. @@ -964,7 +966,7 @@ public class MongoApp { log.info("Found: " + p); // Update - mongoOps.updateFirst(Person.class, query(where("name").is("Joe")), update("age", 35)); + mongoOps.updateFirst(query(where("name").is("Joe")), update("age", 35), Person.class); p = mongoOps.findOne(query(where("name").is("Joe")), Person.class); log.info("Updated: " + p); @@ -972,11 +974,11 @@ public class MongoApp { mongoOps.remove(p); // Check that deletion worked - List<Person> people = mongoOps.getCollection(Person.class); + List<Person> people = mongoOps.findAll(Person.class); log.info("Number of people = : " + people.size()); - mongoOps.dropCollection("person"); + mongoOps.dropCollection(Person.class); } } @@ -985,14 +987,14 @@ public class MongoApp { messages from MongoTemplate itself) DEBUG apping.MongoPersistentEntityIndexCreator: 80 - Analyzing class class org.spring.example.Person for index information. -DEBUG work.data.document.mongodb.MongoTemplate: 632 - insert DBObject containing fields: [_class, age, name] in collection: Person +DEBUG work.data.document.mongodb.MongoTemplate: 632 - insert DBObject containing fields: [_class, age, name] in collection: person INFO org.spring.example.MongoApp: 30 - Insert: Person [id=4ddc6e784ce5b1eba3ceaf5c, name=Joe, age=34] -DEBUG work.data.document.mongodb.MongoTemplate:1246 - findOne using query: { "_id" : { "$oid" : "4ddc6e784ce5b1eba3ceaf5c"}} in db.collection: database.Person +DEBUG work.data.document.mongodb.MongoTemplate:1246 - findOne using query: { "_id" : { "$oid" : "4ddc6e784ce5b1eba3ceaf5c"}} in db.collection: database.person INFO org.spring.example.MongoApp: 34 - Found: Person [id=4ddc6e784ce5b1eba3ceaf5c, name=Joe, age=34] -DEBUG work.data.document.mongodb.MongoTemplate: 778 - calling update using query: { "name" : "Joe"} and update: { "$set" : { "age" : 35}} in collection: Person -DEBUG work.data.document.mongodb.MongoTemplate:1246 - findOne using query: { "name" : "Joe"} in db.collection: database.Person +DEBUG work.data.document.mongodb.MongoTemplate: 778 - calling update using query: { "name" : "Joe"} and update: { "$set" : { "age" : 35}} in collection: person +DEBUG work.data.document.mongodb.MongoTemplate:1246 - findOne using query: { "name" : "Joe"} in db.collection: database.person INFO org.spring.example.MongoApp: 39 - Updated: Person [id=4ddc6e784ce5b1eba3ceaf5c, name=Joe, age=35] -DEBUG work.data.document.mongodb.MongoTemplate: 823 - remove using query: { "id" : "4ddc6e784ce5b1eba3ceaf5c"} in collection: Person +DEBUG work.data.document.mongodb.MongoTemplate: 823 - remove using query: { "id" : "4ddc6e784ce5b1eba3ceaf5c"} in collection: person INFO org.spring.example.MongoApp: 46 - Number of people = : 0 DEBUG work.data.document.mongodb.MongoTemplate: 376 - Dropped collection [database.person] @@ -1112,13 +1114,14 @@ import static org.springframework.data.document.mongodb.query.Criteria.query; ... Person p = new Person("Bob", 33); - mongoTemplate.insert("MyCollection", p); + mongoTemplate.insert(p); - Person qp = mongoTemplate.findOne("MyCollection", query(where("age").is(33)), Person.class); + Person qp = mongoTemplate.findOne(query(where("age").is(33)), Person.class); - The four save operations available to you are listed below. + The insert/save operations available to you are listed + below. @@ -1129,7 +1132,7 @@ import static org.springframework.data.document.mongodb.query.Criteria.query; void save - (String collectionName, Object objectToSave) + (Object objectToSave, String collectionName) Save the object to the specified collection. @@ -1145,13 +1148,26 @@ import static org.springframework.data.document.mongodb.query.Criteria.query; void insert - (String collectionName, Object objectToSave) + (Object objectToSave, String collectionName) Insert the object to the specified collection.
- Inserting Lists of objects in batch + Which collection will my documents be saved into? + + There are two ways to manage the collection name that is used + for operating on the documents. The default collection name that is + used is the class name changed to start with a lower-case letter. So a + com.test.Person class would be stored in the + "person" collection. You can customize this by providing a different + collection name using the @Document annotation. You can also override + the collection name by providing your own collection name as the last + parameter for the selected MongoTemplate method calls. +
+ +
+ Inserting or saving individual objects The MongoDB driver supports inserting a collection of documents in one operation. The methods in the MongoOperations interface that @@ -1159,20 +1175,39 @@ import static org.springframework.data.document.mongodb.query.Criteria.query; - void insertList (List<? extends - Object> listToSave) Insert a - list of objects into the default collection in a single batch - write to the database. + insert + Insert an object. If there is an existing document + with the same id then an error is generated. - 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. + insertAll Takes a + Collection of objects as the first parameter. + This method ispects each object and inserts it to the + appropriate collection based on the rules specified + above. + + + + save Save the object + ovewriting any object that might exist with the same id. + + +
+ +
+ Inserting several objects in a 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 + + + + insert methods + that take a Collection as the first + argument.This inserts a list of objects in a single + batch write to the database.
@@ -1198,8 +1233,9 @@ import static org.springframework.data.document.mongodb.query.Update; ... - WriteResult wr = mongoTemplate.updateMulti(Account.class, new Query(where("accounts.accountType").is(Account.Type.SAVINGS)), - new Update().inc("accounts.$.balance", 50.00)); + WriteResult wr = mongoTemplate.updateMulti(new Query(where("accounts.accountType").is(Account.Type.SAVINGS)), + new Update().inc("accounts.$.balance", 50.00), + Account.class); @@ -1217,39 +1253,15 @@ import static org.springframework.data.document.mongodb.query.Update; - WriteResult updateFirst (Class class, Query - query, Update update) Updates the first object that - is found in the collection corresponding to the class that - matches the query document with the provided updated - document. + updateFirst Updates the + first document that matches the query document criteria with the + provided updated document. - WriteResult updateFirst (String - collectionName, Query query, Update update) Updates - the first object that is found in the specified collection that - matches the query document criteria with the provided updated - document. - - - - WriteResult updateMulti (Class class, Query - query, Update update) Updates all objects that are - found in the collection corresponding to the class that matches - the query document criteria with the provided updated - document. - - - - WriteResult updateMulti (String - collectionName, Query query, Update update) Updates - all objects that are found in the specified collection that - matches the query document criteria with the provided updated - document. + updateMulti Updates all + objects that match the query document criteria with the provided + updated document. @@ -1344,39 +1356,11 @@ import static org.springframework.data.document.mongodb.query.Update; - 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. - - - - void remove - (String collectionName, Query 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 query + 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. @@ -1420,7 +1404,7 @@ import static org.springframework.data.document.mongodb.query.Query.query; ... - List<Person> result = mongoTemplate.find(query(where("age").lt(50).and("accounts.balance").gt(1000.00d)),Person.class); + List<Person> result = mongoTemplate.find(query(where("age").lt(50).and("accounts.balance").gt(1000.00d)), Person.class); @@ -1583,7 +1567,7 @@ import static org.springframework.data.document.mongodb.query.Query.query; Criteria withinCenter - (Circle circle)Creates a geospatial + (Circle circle) Creates a geospatial criterion using $within $center operators @@ -1597,14 +1581,14 @@ import static org.springframework.data.document.mongodb.query.Query.query; Criteria withinBox - (Box box)Creates a geospatial + (Box box) Creates a geospatial criterion using a $within $box operation Criteria near - (Point point)Creates a geospatial + (Point point) Creates a geospatial criterion using a $near operation @@ -1678,103 +1662,40 @@ import static org.springframework.data.document.mongodb.query.Query.query;
Methods for querying for documents + The query methods need to specify the target type T that will be + returned and they are also overloaded with an explicit collection name + for queries that should operate on a collection other than the one + indicated by the return type. + - <T> List<T> getCollection (Class<T> - targetClass) Query for a list of objects of type T from - the default collection. + findAll Query for a list + of objects of type T from the collection. - <T> List<T> getCollection (String - collectionName, Class<T> targetClass) Query for a - list of objects of type T from the specified collection. + findOne Map the results of + an ad-hoc query on the collection to a single instance of an + object of the specified type. - <T> T findOne - (Query query, Class<T> targetClass) - Map the results of an ad-hoc query on the default - MongoDB collection to a single instance of an object of the - specified type. + findById Return an object + of the given id and target class. - <T> T findOne - (String collectionName, Query query, - Class<T> targetClass) Map the results of an - ad-hoc query on the specified collection to a single instance of - an object of the specified type. + find Map the results of an + ad-hoc query on the collection to a List of the specified + type. - <T> T findById (Object id, - Class<T> targetClass) Return an object of the - given id and target class. - - - - <T> T findById (String collectionName, - Object id,Class<T> targetClass) Return an object - in the collection for a given id and target class. - - - - <T> List<T> find (Query query, Class<T> - targetClass) Map the results of an ad-hoc query on the - default MongoDB collection to a List of the specified type. - - - - <T> List<T> find (String collectionName, - Query query, Class<T> targetClass) Map the - results of an ad-hoc query on the specified collection to a List - of the specified type. - - - - <T> List<T> find (String collectionName, - Query query, Class<T> targetClass, CursorPreparer preparer) - Map the results of an ad-hoc query on the specified - collection to a List of the specified type. - - - - <T> T findAndRemove (Query query, - Class<T> targetClass) Map the results of an - ad-hoc query on the default MongoDB collection to a single - instance of an object of the specified type. The first document - that matches the query is returned and also removed from the - collection in the database. - - - - <T> T findAndRemove (Query query, - Class<T> targetClass, MongoReader<T> reader) - Map the results of an ad-hoc query on the default - MongoDB collection to a single instance of an object of the - specified type. The first document that matches the query is - returned and also removed from the collection in the - database. - - - - <T> T findAndRemove (String - collectionName, Query query, Class<T> targetClass) - Map the results of an ad-hoc query on the specified - collection to a single instance of an object of the specified - type. The first document that matches the query is returned and - also removed from the collection in the database. + findAndRemove Map the + results of an ad-hoc query on the collection to a single instance + of an object of the specified type. The first document that + matches the query is returned and also removed from the collection + in the database.
@@ -1983,22 +1904,14 @@ public class PersonWriteConverter implements Converter<Person, DBObject> { Creating an index using the MongoTemplate - mongoTemplate.ensureIndex("MyCollection", new Index().on("name",Order.ASCENDING)); + mongoTemplate.ensureIndex(new Index().on("name",Order.ASCENDING), Person.class); - void ensureIndex - (IndexDefinition indexDefintion) - Ensure that an index for the provided IndexDefinition exists for - the default collection. - - - - void ensureIndex - (String collectionName, IndexDefinition - indexSpecification) Ensure that an index for the - provided IndexDefinition exists. + ensureIndex Ensure that an + index for the provided IndexDefinition exists for the + collection. @@ -2008,7 +1921,7 @@ public class PersonWriteConverter implements Converter<Person, DBObject> { the Venue class defined in a previous section, you would declare a geospatial query as shown below - mongoTemplate.ensureIndex(new GeospatialIndex("location")); + mongoTemplate.ensureIndex(new GeospatialIndex("location"), Venue.class);
@@ -2031,43 +1944,28 @@ mongoTemplate.dropCollection("MyNewCollection"); - Set<String> getCollectionNames () A - set of collection names. + getCollectionNames Returns + a set of collection names. - boolean collectionExists (String - collectionName) Check to see if a collection with a - given name exists. + collectionExists Check to + see if a collection with a given name exists. - DBCollection createCollection (String - collectionName) Create an uncapped collection with the - provided name. + createCollection Create an + uncapped collection - DBCollection createCollection (String - collectionName, CollectionOptions collectionOptions) - Create a collect with the provided name and options. + dropCollection Drop the + collection - void dropCollection - (String collectionName) Drop the - collection with the given name. - - - - DBCollection getCollection (String - collectionName) Get a collection by name, creating it - if it doesn't exist. + getCollection Get a + collection by name, creating it if it doesn't exist.
@@ -2076,10 +1974,10 @@ mongoTemplate.dropCollection("MyNewCollection");
Executing Commands - You can also get at the Mongo driver's collection.command( ) method - using the executeCommand methods on MongoTemplate. These will also perform - exception translation into Spring's Data Access Exception - hierarchy. + You can also get at the Mongo driver's DB.command( + ) method using the executeCommand methods on MongoTemplate. + These will also perform exception translation into Spring's Data Access + Exception hierarchy.
Methods for executing commands @@ -2240,7 +2138,7 @@ public class BeforeSaveListener<BeforeSaveEvent, Person> extends AbstractM <T> T execute (Class<?> entityClass, CollectionCallback<T> action) Executes the given - CollectionCallback for the entitye collection of the specified + CollectionCallback for the entity collection of the specified class.