From d8ce9189f114561484d3bb6d085ff379ea45d9a0 Mon Sep 17 00:00:00 2001 From: Mark Pollack Date: Thu, 7 Apr 2011 19:24:51 -0400 Subject: [PATCH] documentation updates --- src/docbkx/reference/mapping.xml | 10 +- src/docbkx/reference/mongodb.xml | 354 ++++++++++++++++++++----------- 2 files changed, 240 insertions(+), 124 deletions(-) diff --git a/src/docbkx/reference/mapping.xml b/src/docbkx/reference/mapping.xml index 478bdbf68..b1c5c7bdc 100644 --- a/src/docbkx/reference/mapping.xml +++ b/src/docbkx/reference/mapping.xml @@ -4,7 +4,15 @@ Mapping support - The object mapping support for MongoDB + Rich maping support is provided by the + MongoMappingConverter. + MongoMappingConverter has a rich metadata model that + provides a full feature set of functionality to map domain objects into + MongoDB documents. The mapping metadata model is populated using annotations + on your domain objects but is not limited to using annotations as the only + source of metadata information. In this section we will describe the + features of the MongoMappingConverter and how to specify annotation based + mapping metadata.
MongoDB Mapping Configuration diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index db8a873cc..53ae8706c 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/src/docbkx/reference/mongodb.xml @@ -113,18 +113,16 @@ Registering a com.mongodb.Mongo object using Java based bean metadata - @Configuration public class AppConfig { /* - * Factory bean that creates the com.mongodb.Mongo instance + * Use the standard Mongo driver API to create a com.mongodb.Mongo instance. */ public @Bean Mongo mongo() throws UnknownHostException, MongoException { return new Mongo("localhost"); } -} -]]> +} This approach allows you to use the standard @@ -238,7 +236,7 @@ public class AppConfig { <beans> <mongo:mongo> - <! replica set TBD -- should be available for release 1.0.0.M2 --> + <! replica set TBD -- should be available for release 1.0.0.RC1 --> <mongo:mongo> </beans> @@ -250,38 +248,59 @@ public class AppConfig {
Introduction to MongoTemplate - - - Most users are likely to use MongoTemplate - and its corresponding package - org.springframework.data.document.mongodb - the - template is in fact the central class of the MongoDB module due to its - rich feature set. The template offers convenience methods and automatic - mapping between MongoDB JSON documents and your domain classes. Out of the - box, MongoTemplate uses a Java-based default - converter but you can also write your own converter classes to be used for - reading and storing domain objects. + The class MongoTemplate, located in the + package org.springframework.data.document.mongodb, is + the central class of the Spring's MongoDB support providng a rich feature + set. The template offers convenience operations to create, update, delete + and query for MongoDB document and provide a mapping between your domain + objects and MongoDB documents. Once configured, MongoTemplate is thread-safe and can be reused across multiple instances. - Let's look at a couple of examples for how to work with the + The mapping between Mongo documents and domain classes is done by + delegating to an implementation of the interface + MongoConverter. Spring provides two + implementations, SimpleMappingConverter and + MongoMappingConverter, but you can also write your + own converter. Please refer to the section on MongoCoverters for more + detailed information. + + The default converter implementation used by + MongoTemplate is + SimpleMappingConverter, which as the name implies, + is simple. SimpleMapingConverter does not use any + additional mapping metadata to converter a domain object to a MongoDB + document. As such, it does not support functionality such as DBRefs or + creating indexes using annotations on domain classes. For a detailed + description of the MongoMappingConverter read the section on Mapping Support. + + Another central feature of MongoTemplate is exception translation of + exceptions thrown in the Mongo Java driver into Spring's portable Data + Access Exception hierarchy. Refer to the section on exception translation for more + information. + + While there are many convenience methods on MongoTemplate to help + you easily perform common tasks if you should need to access the Mongo + driver API directly to access functionality not explicitly exposed by the + MongoTemplate you can use one of several Execute callback methods. These + will give you a reference to a Mongo Collection or DB object. Please see + the section Execution + Callbacks for more information. + + Now let's look at a examples of how to work with the MongoTemplate in the context of the Spring container. - Exception Translation - - Mongo Converters - - Execute callbacks -
Instantiating MongoTemplate - In Java based configuration using the driver's com.mongodb.Mongo - object + You can use Java to create and register an instance of + MongoTemplate as shown below. Registering a com.mongodb.Mongo object and enabling Spring's @@ -290,109 +309,63 @@ public class AppConfig { <programlisting language="java">@Configuration public class AppConfig { - public @Bean Mongo mongo() throws UnknownHostException, MongoException { + public @Bean Mongo mongo() throws Exception { return new Mongo("localhost"); } - public @Bean MongoTemplate mongoTemplate() throws UnknownHostException, MongoException { - return new MongoTemplate(mongo(), "test", "HelloMongo"); + public @Bean MongoTemplate mongoTemplate() throws Exception { + return new MongoTemplate(mongo(), "mydatabase", "mycollection"); } } </programlisting> </example> - <para>Alternatively using <classname>MongoFactoryBean</classname>, which - avoid dealing with the checked UnknownHostException</para> - - <example> - <title>Registering a com.mongodb.Mongo object and enabling Spring's - exception translation support - - @Configuration - public class AppConfig { - - /* - * The method argument is the container managed Mongo instance created by the mongo() method - */ - public @Bean MongoTemplate mongoTemplate(Mongo mongo) { - MongoTemplate mongoTemplate = new MongoTemplate(mongo, "test", "HelloMongo"); - return mongoTemplate; - } - - /* - * Factory bean that creates the Mongo instance - */ - public @Bean MongoFactoryBean mongo() { - MongoFactoryBean mongo = new MongoFactoryBean(); - mongo.setHost("localhost"); - return mongo; - } - - /* - * Use this post processor to translate any MongoExceptions thrown in @Repository - * annotated classes - */ - public @Bean PersistenceExceptionTranslationPostProcessor - persistenceExceptionTranslationPostProcessor() { - return new PersistenceExceptionTranslationPostProcessor(); - } - - } - - - There are several overloaded constructors of MongoTemplate. - These are - - - - MongoTemplate - (Mongo mongo, String databaseName) - takes the - default database name to operate against - - - - MongoTemplate - (Mongo mongo, String databaseName, String - defaultCollectionName) - adds the default collection - name to operate against. - - - - MongoTemplate - (Mongo mongo, String databaseName, String - defaultCollectionName, MongoConverter mongoConverter) - - override with a provided MongoConverter. Default is - SimpleMongoConverter - - - - MongoTemplate - (Mongo mongo, String databaseName, String - defaultCollectionName, MongoConverter mongoConverter, WriteConcern - writeConcern, WriteResultChecking writeResultChecking) - - Specify a default WriteConcern and also WriteResultChecking - policy - - - - MongoTemplate - (Mongo mongo, String databaseName, String - defaultCollectionName, WriteConcern writeConcern, - WriteResultChecking writeResultChecking)- Specify a - default WriteConcern and also WriteResultChecking policy - - - - MongoTemplate - (Mongo mongo, String databaseName, WriteConcern - writeConcern, WriteResultChecking writeResultChecking)- - Specify a default WriteConcern and also WriteResultChecking - policy - - - - - + There are several overloaded constructors of MongoTemplate. These + are + + + + MongoTemplate + (Mongo mongo, String databaseName) - takes the + default database name to operate against + + + + MongoTemplate + (Mongo mongo, String databaseName, String + defaultCollectionName) - adds the default collection name + to operate against. + + + + MongoTemplate + (Mongo mongo, String databaseName, String + defaultCollectionName, MongoConverter mongoConverter) - + override with a provided MongoConverter. Default is + SimpleMongoConverter + + + + You can also configure a MongoTemplate using Spring's XML + <beans/> schema. + + <mongo:mongo host="localhost" port="27017"/> + + <bean id="mongoTemplate" class="org.springframework.data.document.mongodb.MongoTemplate"> + <constructor-arg ref="mongo"/> + <constructor-arg name="databaseName" value="geospatial"/> + <constructor-arg name="defaultCollectionName" value="newyork"/> + </bean> + + Other properties that you might like to set when creating a + MongTemplate are WriteResultCheckingPolicy and the default + WriteConcern. + + + The preferred way to reference the operations on + MongoTemplate instance is via its interface + MongoOperations. +
WriteResultChecking Policy @@ -407,15 +380,55 @@ public class AppConfig { The default is to use a WriteResultChecking of NONE.
+ +
+ WriteConcern + + You can set the WriteConcern property that the MongoTemplate + will use for write operations if it has not yet been specifid with the + driver. If not set, it will default to the one set in the MongoDB + driver's DB or Collection setting. + + + Setting the WriteConcern to different values when saving an + object will be provided in a future release. This will most likely + be handled using mapping metadata provided either in the form of + annotations on the domain object or by an external fluent + DSL. + +
Saving, Updating, and Deleting Documents - Insert, savfe, remove, findAndRemove + 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 - + public class Person { + + private String id; + private String firstName; + private int age; + + // getters and setter omitted + +} + + You can save, update and delete the object as shown below + + public class PersonExample { + + @Inject + +Person p = new Person(); +p.setFirstName("Sven"); +p.setAge(22); + + +mongo
Methods for saving documents @@ -1252,4 +1265,99 @@ public class AppConfig { The lifecycle events are....
+ +
+ Exception Translation + + The Spring framework provides exception translation for a wide + variety of database and mapping technologies. This has traditionally been + for JDBC and JPA. The Spring support for Mongo extends this feature to the + MongoDB Database by providing an implementation of the + org.springframework.dao.support.PersistenceExceptionTranslator + interface. + + The motivation behind mapping to Spring's consistent + data access exception hierarchy is that you are then able to write + portable and descriptive exception handling code without resorting to + coding against MongoDB error + codes. All of Spring's data access exceptions are inherited from + the root DataAccessException class so you can be + sure that you will be able to catch all database related exception within + a single try-catch block. Note, that not all exceptions thrown by the + MongoDB driver inherit from the MongoException class. The inner exception + and message are preserved so no information is lost. + + Some of the mappings performed by the MongoExceptionTranslator are: + com.mongodb.Network to DataAccessResourceFailureException and + MongoException error codes 1003, 12001, 12010, 12011, 12012 to + InvalidDataAccessApiUsageException. Look into the implementation for more + details on the mapping. +
+ +
+ Execution Callback + + One common design feature of all Spring template classes is that all + functionality is routed into one of the templates execute callback + methods. This helps ensure that exceptions and any resource management + that maybe required are performed consistency. While this was of much + greater need in the case of JDBC and JMS than with MongoDB, it still + offers a single spot for exception translation and logging to occur. As + such, using thexe execute callback is the preferred way to access the + Mongo driver's DB and Collection objects to perform uncommon operations + that were not exposed as methods on + MongoTemplate. + + Here is a list of execute callback methods. + + + + <T> T execute + (CollectionCallback<T> action) + Executes the given CollectionCallback on the default + collection. + + + + <T> T execute + (String collectionName, + CollectionCallback<T> action) Executes the given + CollectionCallback on the collection of the given name.update using + the $addToSet update modifier + + + + <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. + + + + Here is an example that uses the CollectionCallback to return + information about an index. + + boolean hasIndex = template.execute("geolocation", new CollectionCallback<Boolean>() { + public Boolean doInCollection(DBCollection collection) throws MongoException, DataAccessException { + List<DBObject> indexes = collection.getIndexInfo(); + for (DBObject dbo : indexes) { + if ("location_2d".equals(dbo.get("name"))) { + return true; + } + } + return false; + } + }); +