diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index b739007dc..7f1f7877b 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/src/docbkx/reference/mongodb.xml @@ -4,60 +4,87 @@ MongoDB support - One of the document stores supported by DATADOC isMongoDB. To quote the project home - page: MongoDB (from "humongous") is a scalable, high-performance, - open source, document-oriented database. Spring Data Document - provides easy configuration and access to MongoDB from a Spring application. - Offers both low-level and high-level abstraction for interacting with the - store, freeing the user from infrastructural concerns. + The MongoDB support contains a wide range of features which are + summarized below. + + + + Spring configuration support using Java based @Configuration + classes or an XML namespace for a Mongo driver instance and replica + sets + + + + MongoTemplate helper class that increases productivity performing + common Mongo operations. Includes integrated object mapping between + documents and POJOs. + + + + Exception translation into Spring's portable Data Access Exception + hierarchy + + + + Feature Rich Object Mapping integrated with Spring's Conversion + Service + + + + Annotation based mapping metadata but extensible to support other + metadata formats + + + + Persistence and mapping lifecycle events + + + + Low-level mapping using MongoReader/MongoWriter + abstractions + + + + Java based Query, Criteria, and Update DSLs + + + + Automatic implementatin of Repository interfaces including support + for custom finder methods. + + + + QueryDSL integration to support type-safe queries. + + + + Cross-store persistance - support for JPA Entities with fields + transparently persisted/retrieved using MongoDB + + + + Log4j log appender + + + + GeoSpatial integration + + + + For most tasks you will find yourself using MongoTemplate or the + Repository support that both leverage the rich mapping functionality. + MongoTemplate is the place to look for accessing functionality such as + incrementing counters or ad-hoc CRUD operations. MongoTemplate also provides + callback methods so that it is easy for you to get a hold of the low level + API artifacts such as org.mongo.DB to communicate + directly with MongoDB.
- MongoDB Requirements + Getting Started - DATADOC requires MongoDB 1.4 while the latest production release - (1.6.5 as of this writing) is recommended. -
- -
- MongoDB Support High Level View - - The MongoDB support provides several components: - - - - - - Configuration Factory - - - for configuring and handling communication with MongoDB via its Java driver - - - - - - Template implementation - - - 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. - - - - - - Support Classes - - - that offer reusable components such as mapping support and exception translation. - - - - For most tasks, the higher-level abstractions and support services - are the best choice. Note that at any point, one can move between layers - - for example, it's very easy to get a hold of the low level connection - (org.mongo.DB) to communicate directly with MongoDB. + Spring MongoDB support requires MongoDB 1.4 or higher and Java SE 5 + or higher. The latest production release (1.8.x as of this writing) is + recommended.
@@ -87,48 +114,35 @@ metadata @Configuration - public class AppConfig { +public class AppConfig { - /* - * Factory bean that creates the com.mongodb.Mongo instance - */ - public @Bean Mongo mongo() throws UnknownHostException, MongoException { - return new Mongo("localhost"); - } + /* + * Factory bean that creates the com.mongodb.Mongo instance + */ + public @Bean Mongo mongo() throws UnknownHostException, MongoException { + return new Mongo("localhost"); + } - } +} - This approach allows you to use the standard com.mongodb.Mongo API - that you may already be used to using but also pollutes the code with - the UnknownHostException checked exception. + This approach allows you to use the standard + com.mongodb.Mongo API that you may already be + used to using but also pollutes the code with the UnknownHostException + checked exception. - However, you may also register an instance of + You may also register an instance of com.mongodb.Mongo instance with the container - using Spring'sMongoFactoryBean. As + using Spring's MongoFactoryBean. As compared to instantiating a com.mongodb.Mongo instance directly, the FactoryBean approach has the added advantage of - also acting as an ExceptionTranslator that can be used to translate any - Mongo exceptions to exceptions in the - SpringDataAccessException. This is part ofDataAccessException hierarchy. This hierarchy is + described in Spring's - DAO support features. The exception translation feature works - hand in hand with Spring's @Repository - annotation. To enable exception translation on data access components - annotated with @Repository register a - PersistenceExceptionTranslationPostProcessor - ( - JavaDoc) with the container. - While enabling exception translation can be done using Java - based bean metadata it is often done declaratively in XML using - Spring's context namespace - <context::annotation-config/>.to enable - - annotation configuration features. - + DAO support features. An example is shown below An example of a Java based bean metadata that supports exception translation on @Repository annotated classes is @@ -140,48 +154,18 @@ support @Configuration - public class AppConfig { +public class AppConfig { - /* - * Factory bean that creates the com.mongodb.Mongo instance - */ - public @Bean MongoFactoryBean mongo() { + /* + * Factory bean that creates the com.mongodb.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(); - } - - } - - - - 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. - - - Registering a com.mongodb.Mongo object and enabling Spring's - exception translation support - - @Configuration - public class AppConfig extends MongoExceptionTranslationConfig { - - public @Bean Mongo mongo() throws UnknownHostException, MongoException { - return new Mongo("localhost"); - } - } - + } +} +
@@ -205,7 +189,7 @@ XML schema to configure MongoDB <?xml version="1.0" encoding="UTF-8"?> - <beans xmlns="http://www.springframework.org/schema/beans" +<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context" xmlns:mongo="http://www.springframework.org/schema/data/mongo" @@ -217,15 +201,13 @@ http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-3.0.xsd"> - <beans> + <!-- Default bean name is 'mongo' --> + <mongo:mongo host="localhost" port="27017"/> - <!-- Default bean name is 'mongo' --> - <mongo:mongo host="localhost" port="27017"/> + <!-- To translate any MongoExceptions thrown in @Repository annotated classes --> + <context:annotation-config/> - <!-- To translate any MongoExceptions thrown in @Repository annotated classes --> - <context:annotation-config/> - - </beans> +</beans> @@ -237,16 +219,16 @@ <beans> - <mongo:mongo host="localhost" port="27017"> - <mongo:options connectionsPerHost="10" - threadsAllowedToBlockForConnectionMultiplier="5" - maxWaitTime="12000" - connectTimeout="0" - socketTimeout="0" - autoConnectRetry="0"/> - </mongo:mongo/> + <mongo:mongo host="localhost" port="27017"> + <mongo:options connectionsPerHost="10" + threadsAllowedToBlockForConnectionMultiplier="5" + maxWaitTime="12000" + connectTimeout="0" + socketTimeout="0" + autoConnectRetry="0"/> + </mongo:mongo/> - </beans> +</beans> @@ -255,11 +237,11 @@ <beans> - <mongo:mongo> - <! replica set TBD -- should be available for release 1.0.0.M2 --> - <mongo:mongo> + <mongo:mongo> + <! replica set TBD -- should be available for release 1.0.0.M2 --> + <mongo:mongo> - </beans> +</beans> @@ -299,21 +281,21 @@ exception translation support @Configuration - public class AppConfig extends MongoExceptionTranslationConfig { +public class AppConfig { - public @Bean Mongo mongo() throws UnknownHostException, MongoException { - return new Mongo("localhost"); - } + public @Bean Mongo mongo() throws UnknownHostException, MongoException { + return new Mongo("localhost"); + } - public @Bean MongoTemplate mongoTemplate() throws UnknownHostException, MongoException { - return new MongoTemplate(mongo(), "test", "HelloMongo"); - } - } + public @Bean MongoTemplate mongoTemplate() throws UnknownHostException, MongoException { + return new MongoTemplate(mongo(), "test", "HelloMongo"); + } +} - Alternatively using MongoFactoryBean, which avoid dealing with the - checked UnknownHostException + Alternatively using MongoFactoryBean, which + avoid dealing with the checked UnknownHostException Registering a com.mongodb.Mongo object and enabling Spring's