diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index 5c4c0252b..b7329de0b 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/src/docbkx/reference/mongodb.xml @@ -38,14 +38,16 @@ Template implemenattion - - As with many of Spring's template classes, MongoTemplate simplifies the use of accessing the database for common use-cases and infrastructure concerns such as exception translation. Features include integrated object mapping between documents and domain classes and fluent DSLs for query and update operations. The chapter + - As with many of Spring's template classes, MongoTemplate simplifies the use of accessing the database for common use-cases and infrastructure concerns such as exception translation. Features include integrated object mapping between documents and domain classes and fluent DSLs for query and update operations. The chapter - provides additional details. + provides additional details. + + Support Classes - that offer reusable components such as mapping support and exception translation. @@ -162,8 +164,8 @@ public class AppConfig { if you prefer to use the standard MongoDB API to create a com.mongodb.Mongo instance and have exception translation enabled on your @Repository instances, simply inherit from - MongoExceptionTranslationConfig as shown below. - + MongoExceptionTranslationConfig as shown + below. Registering a com.mongodb.Mongo object and enabling Spring's @@ -191,7 +193,7 @@ public class AppConfig extends MongoExceptionTranslationConfig { constructor arguments/names are not the most effective means to distinguish between configuraiton of replicat sets and replica pairs. o address these issues a XML namespace is available to simplify the - configuration of a com.mongodb.Mongo instance in XML. </para> + configuration of a com.mongodb.Mongo instance in XML.</para> <para>To use the Mongo namespace elements you will need to reference the Mongo schema:</para> @@ -207,7 +209,7 @@ public class AppConfig extends MongoExceptionTranslationConfig { xsi:schemaLocation= "http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd http://www.springframework.org/schema/data/mongo http://www.springframework.org/schema/data/mongo/spring-mongo-1.0.xsd -http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"> +http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"> <beans> @@ -248,7 +250,7 @@ http://www.springframework.org/schema/beans http://www.springframework.org/schem <programlisting language="xml"><beans> <mongo:mongo> - <! replica set TBD --> + <! replica set TBD -- should be available for release 1.0.0.M2 --> <mongo:mongo> </beans> @@ -269,7 +271,7 @@ http://www.springframework.org/schema/beans http://www.springframework.org/schem mapping between MongoDB JSON documents and your domain classes. Out of the box, <classname>MongoTemplate</classname> uses a Java-based default converter but you can also write your own converter classes to be used for - reading and storing domain objects. </para> + reading and storing domain objects.</para> <note> <para>Once configured, <classname>MongoTemplate</classname> is @@ -284,7 +286,7 @@ http://www.springframework.org/schema/beans http://www.springframework.org/schem <title>Instantiating MongoTemplate In Java based configuration using the driver's com.mongodb.Mongo - object + object Registering a com.mongodb.Mongo object and enabling Spring's @@ -344,8 +346,6 @@ public class AppConfig { <para>There are several overloaded constructors of MongoTemplate. These are</para> - <para></para> - <itemizedlist> <listitem> <para>MongoTemplate(Mongo mongo, String databaseName) - takes the @@ -375,7 +375,7 @@ public class AppConfig { <listitem> <para>MongoTemplate(Mongo mongo, String databaseName, String defaultCollectionName, WriteConcern writeConcern, - WriteResultChecking writeResultChecking) </para> + WriteResultChecking writeResultChecking)</para> </listitem> <listitem> @@ -384,7 +384,7 @@ public class AppConfig { </listitem> </itemizedlist> - <para>The</para> + <para></para> </example> <section> @@ -396,45 +396,443 @@ public class AppConfig { development and then end up with an application that looks like it ran successfully but the database was not modified according to your expectations. Setting the WriteResultChecking is an enum with the - following values, NONE, LOG, EXCEPTION. </para> + following values, NONE, LOG, EXCEPTION.</para> - <para></para> - - <para>TBD</para> - - <para></para> + <para>The default is to use a WriteResultChecking of NONE.</para> </section> </section> <section> <title>Overivew of MongoTemplate Methods - + The public methods for MongoTemplate are + defined by the interface MongoOperations. + They can be grouped into the following categories: + +
+ Methods for working with a Collection + + + + Set<String> getCollectionNames() A set of collection + names. + + + + boolean collectionExists(java.lang.String collectionName) + Check to see if a collection with a given name exists. + + + + com.mongodb.DBCollection createCollection(String + collectionName) Create an uncapped collection with the provided + name. + + + + com.mongodb.DBCollection createCollection(String + collectionName, CollectionOptions collectionOptions) Create a + collect with the provided name and options. + + + + void dropCollection(java.lang.String collectionName) Drop + the collection with the given name. + + + + com.mongodb.DBCollection getCollection(java.lang.String + collectionName) Get a collection by name, creating it if it + doesn't exist. + + + + com.mongodb.DBCollection getDefaultCollection() The + default collection used by this template. + + + + String getDefaultCollectionName() The default collection + name used by this template. + + + + com.mongodb.DBCollection getDefaultCollection() The + default collection used by this template. + + +
+ +
+ Methods for executing commands + + + + com.mongodb.CommandResult + executeCommand(com.mongodb.DBObject command) Execute a MongoDB + command. + + + + com.mongodb.CommandResult executeCommand(String + jsonCommand) Execute the a MongoDB command expressed as a JSON + string. + + + + <T> T execute(CollectionCallback<T> action) + Executes the given CollectionCallback on the default + collection. + + + + <T> T execute(CollectionCallback<T> action, + String collectionName) Executes the given CollectionCallback on + the collection of the given name. + + + + <T> T execute(DbCallback<T> action) Executes a + DbCallback translating any exceptions as necessary. + + + + <T> T executeInSession(DbCallback<T> action) + Executes the given DbCallback within the same connection to the + database so as to ensure consistency in a write heavy + environment where you may read the data that you wrote. + + +
+ +
+ Methods for creating an Index + + + + void ensureIndex(IndexSpecification indexSpecification) + Ensure that an index for the provided IndexSpecification exists + for the default collection. + + + + void ensureIndex(String collectionName, IndexSpecification + indexSpecification) Ensure that an index for the provided + IndexSpecification exists. + + +
+ +
+ Methods for inserting documents + + + + void insert(java.lang.Object objectToSave) Insert the + object into the default collection. + + + + void insert(java.lang.String collectionName, + java.lang.Object objectToSave) Insert the object into the + specified collection. + + + + void insertList(java.util.List<? extends + java.lang.Object> listToSave) Insert a list of objects into + the default collection in a single batch write to the + database. + + + + void insertList(java.lang.String collectionName, + java.util.List<? extends java.lang.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 querying for documents + + + + <T> List<T> getCollection(Class<T> + targetClass) Query for a list of objects of type T from the + default collection. + + + + <T> List<T> getCollection(String + collectionName, Class<T> targetClass) Query for a list of + objects of type T from the specified collection. + + + + <T> List<T> getCollection(String + collectionName, Class<T> targetClass, MongoReader<T> + reader) Query for a list of objects of type T from the specified + collection, mapping the DBObject using the provided + MongoReader. + + + + <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. + + + + <T> T findOne(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. + + + + <T> T findOne(java.lang.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. + + + + <T> T findOne(java.lang.String collectionName, Query + query, Class<T> targetClass, MongoReader<T> reader) + Map the results of an ad-hoc query on the specified collection + to a single instance of an object of the specified type. + + + + <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(Query query, Class<T> + targetClass, MongoReader<T> reader) 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> List<T> find(String collectionName, Query + query, Class<T> targetClass, MongoReader<T> reader) + Map the results of an ad-hoc query on the specified collection + to a List of the specified type. + + +
+ +
+ Methods for saving documents + + + + void save(Object objectToSave) Save the object to the + default collection. + + + + void save(String collectionName, Object objectToSave) Save + the object to the specified collection. + + + + <T> void save(T objectToSave, MongoWriter<T> + writer) Save the object into the default collection using the + provided writer. + + + + <T> void save(String collectionName, T objectToSave, + MongoWriter<T> writer) Save the object into the specified + collection using the provided writer. + + +
+ +
+ Methods for removing documents + + + + 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. + + +
+ +
+ Methods for executing updates for documents + + + + com.mongodb.WriteResult updateFirst(Query query, Update + update) Updates the first object that is found in the default + collection that matches the query document with the provided + updated document. + + + + com.mongodb.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. + + + + com.mongodb.WriteResult updateMulti(Query query, Update + update) Updates all objects that are found in the default + collection that matches the query document criteria with the + provided updated document. + + + + com.mongodb.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. + + +
Working with collections - ... + It's time to look at some code examples showing how to use the + MongoTemplate. First we look at creating our + first colection. + + + Working with collections using the MongoTemplate + + DBCollection collection = null; + if (!mongoTemplate.getCollectionNames().contains("MyNewCollection")) { + collection = mongoTemplate.createCollection("MyNewCollection"); + } + + mongoTemplate.dropCollection("MyNewCollection"); + +
Creating an index - ... + We can create an index on a collection to improve query + performance. + + + Creating an index using the MongoTemplate + + mongoTemplate.ensureIndex("MyCollection", new Index().on("name", Order.ASCENDING)); + +
Saving and retreiving objects as documents in a collection - ... + Once we have craeted 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. + + + Inserting and retrieving documents using the + MongoTemplate + + import static org.springframework.data.document.mongodb.query.Criteria.where; + +... + + Person p = new Person("Bob", 33); + mongoTemplate.insert("MyCollection", p); + + Person qp = mongoTemplate.findOne("MyCollection", + new Query(where("id").is(p.getId())), Person.class); + +
Querying documents in a collection - ... + We saw how to retrieve a single document. We can also query for a + collection of documents to be returned as domain objects in a list. + Assuming that we have a number of Person objects with name and age + stored as documents in a collection and that each person has an embedded + account document with a balance. We can now run a query using the + following code. + + + Querying for documents using the MongoTemplate + + import static org.springframework.data.document.mongodb.query.Criteria.where; + +... + List<Person> result = mongoTemplate.find( + new Query(where("age").lt(50)).and(where("accounts.balance").gt(1000.00d)), + Person.class); + + + + This query should return a list of Person objects that meet the + specified criteria.