From b1f6ff9d89bc4a3a7935b473b955cbf3d44318a7 Mon Sep 17 00:00:00 2001 From: Mark Pollack Date: Sun, 13 Feb 2011 03:53:57 -0200 Subject: [PATCH] Update documentation. Add support to configure MongoOptions in .xsd --- .../document/mongodb/config/MongoParser.java | 32 +- .../mongodb/config/spring-mongo-1.0.xsd | 65 ++- .../config/MongoNamespaceTests-context.xml | 13 +- .../src/test/resources/server-jmx.xml | 4 +- src/docbkx/reference/mongodb.xml | 380 +++++++++++++++--- 5 files changed, 423 insertions(+), 71 deletions(-) diff --git a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/config/MongoParser.java b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/config/MongoParser.java index db3600f85..9e6de9692 100644 --- a/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/config/MongoParser.java +++ b/spring-data-mongodb/src/main/java/org/springframework/data/document/mongodb/config/MongoParser.java @@ -22,7 +22,9 @@ import org.springframework.beans.factory.support.BeanDefinitionBuilder; import org.springframework.beans.factory.xml.AbstractSingleBeanDefinitionParser; import org.springframework.beans.factory.xml.ParserContext; import org.springframework.data.document.mongodb.MongoFactoryBean; +import org.springframework.data.document.mongodb.MongoOptionsFactoryBean; import org.springframework.util.StringUtils; +import org.springframework.util.xml.DomUtils; import org.w3c.dom.Element; /** @@ -37,12 +39,40 @@ public class MongoParser extends AbstractSingleBeanDefinitionParser { } @Override - protected void doParse(Element element, BeanDefinitionBuilder builder) { + protected void doParse(Element element, ParserContext parserContext, BeanDefinitionBuilder builder) { super.doParse(element, builder); setPropertyValue(element, builder, "port", "port"); setPropertyValue(element, builder, "host", "host"); + parseOptions(parserContext, element, builder); + + } + + /** + * Parses the options sub-element. Populates the given attribute factory with the proper attributes. + * + * @param element + * @param attrBuilder + * @return true if parsing actually occured, false otherwise + */ + private boolean parseOptions(ParserContext parserContext, Element element, + BeanDefinitionBuilder mongoBuilder) { + Element optionsElement = DomUtils.getChildElementByTagName(element, "options"); + if (optionsElement == null) + return false; + + BeanDefinitionBuilder optionsDefBuilder = BeanDefinitionBuilder.genericBeanDefinition(MongoOptionsFactoryBean.class); + + setPropertyValue(optionsElement, optionsDefBuilder, "connectionsPerHost", "connectionsPerHost"); + setPropertyValue(optionsElement, optionsDefBuilder, "threadsAllowedToBlockForConnectionMultiplier", "threadsAllowedToBlockForConnectionMultiplier"); + setPropertyValue(optionsElement, optionsDefBuilder, "maxWaitTime", "maxWaitTime"); + setPropertyValue(optionsElement, optionsDefBuilder, "connectTimeout", "connectTimeout"); + setPropertyValue(optionsElement, optionsDefBuilder, "socketTimeout", "socketTimeout"); + setPropertyValue(optionsElement, optionsDefBuilder, "autoConnectRetry", "autoConnectRetry"); + + mongoBuilder.addPropertyValue("mongoOptions", optionsDefBuilder.getBeanDefinition()); + return true; } @Override diff --git a/spring-data-mongodb/src/main/resources/org/springframework/data/document/mongodb/config/spring-mongo-1.0.xsd b/spring-data-mongodb/src/main/resources/org/springframework/data/document/mongodb/config/spring-mongo-1.0.xsd index c133aaad4..6cdf4ec87 100644 --- a/spring-data-mongodb/src/main/resources/org/springframework/data/document/mongodb/config/spring-mongo-1.0.xsd +++ b/spring-data-mongodb/src/main/resources/org/springframework/data/document/mongodb/config/spring-mongo-1.0.xsd @@ -25,6 +25,22 @@ Defines a Mongo instance used for accessing MongoDB'. + + + + + + + + + + + + + + - + @@ -114,6 +130,53 @@ The name of the Mongo object that determines what server to monitor. (by default + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/spring-data-mongodb/src/test/resources/org/springframework/data/document/mongodb/config/MongoNamespaceTests-context.xml b/spring-data-mongodb/src/test/resources/org/springframework/data/document/mongodb/config/MongoNamespaceTests-context.xml index ab52de0f2..18ab46a9d 100644 --- a/spring-data-mongodb/src/test/resources/org/springframework/data/document/mongodb/config/MongoNamespaceTests-context.xml +++ b/spring-data-mongodb/src/test/resources/org/springframework/data/document/mongodb/config/MongoNamespaceTests-context.xml @@ -1,13 +1,14 @@ - - - + + + diff --git a/spring-data-mongodb/src/test/resources/server-jmx.xml b/spring-data-mongodb/src/test/resources/server-jmx.xml index 0a61119cd..2441dab55 100644 --- a/spring-data-mongodb/src/test/resources/server-jmx.xml +++ b/spring-data-mongodb/src/test/resources/server-jmx.xml @@ -9,9 +9,9 @@ http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-3.0.xsd"> - + - + MongoDB Requirements - DATADOC requires MongoDB 1.4 while 1.6 is recommended. + DATADOC requires MongoDB 1.4 while the latest production release + (1.6.5 as of this writing) is recommended.
@@ -37,16 +38,14 @@ Template implemenattion - - providing a generified, user friendly template classes for interacting with MongoDB. + - 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 - explains the abstraction builds on top of the low-level MongoDB Java API to handle the storage and retrieval of documents plus mapping between documents and domain classes. + provides additional details. - - Support Classes - that offer reusable components such as mapping support and exception translation. @@ -62,45 +61,92 @@
Connecting to MongoDB - One of the first tasks when using MongoDB and Spring is to connect - to the store through the IoC container. To do that - - The easiest way to work with a - MongoFactoryBean is to configure a - MongoFactory bean. This has the added advantage of - also acting as an ExceptionTranslator that can be used to translate any - Mongo exceptions to exceptions in the - SpringDataAccessException hierarchy as long as your - data access classes are annotatded with @Repository and you are using an - PersistenceExceptionTranslationPostProcessor (see - Spring API docs). - - You have two basic choices - use Java based configuration or XML - based configuration. An example fo a basic Java configuratopn style - is: + One of the first tasks when using MongoDB and Spring is to create a + com.mongodb.Mongo object using the IoC container. + There are two main ways to do this, either using Java based bean metadata + or XML based bean metadata. These are discussed in the following + sections. + For those not familiar with how to configure the Spring + container using Java based bean metadata instead of XML based metadata + see the high level introduction in the reference docs here as well as the detailed documentation here. + + +
+ Using Java based based metadata + + An example of using Java based bean metadata to register an + instance of a com.mongodb.Mongo is shown + below + Registering a com.mongodb.Mongo object using Java based bean + metadata + + @Configuration +public class AppConfig { - - Java based Spring configuration for MongoDB + /* + * Factory bean that creates the com.mongodb.Mongo instance + */ + public @Bean Mongo mongo() throws UnknownHostException, MongoException { + return new Mongo("localhost"); + } - @Configuration +} + + + + 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 + com.mongodb.Mongo instance with the container + 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 of 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. + + + An example of a Java based bean metadata that supports exception + translation on @Repository annotated classes is + shown below: + + + Registering a com.mongodb.Mongo object using Spring's + MongoFactoryBean and enabling Spring's exception translation + support + + @Configuration public class AppConfig { /* - * Factory bean that creates the Mongo instance + * Factory bean that creates the com.mongodb.Mongo instance */ public @Bean MongoFactoryBean mongo() { MongoFactoryBean mongo = new MongoFactoryBean(); mongo.setHost("localhost"); return mongo; - } - - /* - * A basic MongoTemplate instance - */ - public @Bean MongoTemplate mongoTemplate(Mongo mongo) { - MongoTemplate mongoTemplate = new MongoTemplate(mongo, "test", "HelloMongo"); - return mongoTemplate; - } + } /* * Use this post processor to translate any MongoExceptions thrown in @Repository annotated classes @@ -111,29 +157,104 @@ public class AppConfig { } - + - The following shows the same configuration using XML: + 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. + - - XML based Spring configuration for MongoDB + + Registering a com.mongodb.Mongo object and enabling Spring's + exception translation support - <!-- Factory bean that creates the Mongo instance --> -<bean id="mongo" class="org.springframework.data.document.mongodb.MongoFactoryBean"> - <property name="host" value="localhost"/> -</bean> - -<!-- A basic MongoTemplate instance --> -<bean id="mongoTemplate" class="org.springframework.data.document.mongodb.MongoTemplate"> - <constructor-arg name="mongo" ref="mongo"/> - <constructor-arg name="databaseName" value="test"/> - <constructor-arg name="defaultCollectionName" value="HelloMongo"/> -</bean> + @Configuration +public class AppConfig extends MongoExceptionTranslationConfig { + + public @Bean Mongo mongo() throws UnknownHostException, MongoException { + return new Mongo("localhost"); + } +} + + +
-<!-- Use this post processor to translate any MongoExceptions thrown in @Repository annotated classes --> -<bean class="org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor"/> +
+ Using XML based metadata + + While you can use Spring's traditional <beans/> XML + namespace to register an instance of + com.mongodb.Mongo with the container, the XML can + be quite verbose, does not easily support the configuration of public + instance variables used with the driver's MongoOptions class, and + 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. + + To use the Mongo namespace elements you will need to reference the + Mongo schema: + + + XML schmea to configure MongoDB + + <?xml version="1.0" encoding="UTF-8"?> +<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" + 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"> + +<beans> + + <!-- Default bean name is 'mongo' --> + <mongo:mongo host="localhost" port="27017"/> + + <!-- To translate any MongoExceptions thrown in @Repository annotated classes --> + <context:annotation-config/> + +</beans> + + + + A more advanced configuration with MongoOptions is shown + below + + + XML schmea to configure MongoOptinos in MongoDB + + <beans> + + <mongo:mongo host="localhost" port="27017"> + <mongo:options connectionsPerHost="10" + threadsAllowedToBlockForConnectionMultiplier="5" + maxWaitTime="12000" + connectTimeout="0" + socketTimeout="0" + autoConnectRetry="0"/> + </mongo:mongo/> + +</beans> + + + + A configuration using replica sets is shown below: + XML schmea to configure replica sets in MongoDB + + <beans> + + <mongo:mongo> + <! replica set TBD --> + <mongo:mongo> + +</beans> - + +
@@ -148,45 +269,182 @@ public class AppConfig { 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. Once configured, the template is - thread-safe and can be reused across multiple instances. + reading and storing domain objects. + + + 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 - MongoTemplate. + MongoTemplate in the context of the Spring + container. + +
+ Instantiating MongoTemplate + + In Java based configuration using the driver's com.mongodb.Mongo + object + + + 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"); + } + + public @Bean MongoTemplate mongoTemplate() throws UnknownHostException, MongoException { + return new MongoTemplate(mongo(), "test", "HelloMongo"); + } +} + + + + Alternatively using MongoFactoryBean, which avoid dealing with the + checked UnknownHostException + + + 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) + + + + MongoTemplate(Mongo mongo, String databaseName, WriteConcern + writeConcern, WriteResultChecking writeResultChecking) + + + + The + + +
+ WriteResultChecking Policy + + When in development it is very handy to either log or throw an + exception if the WriteResult returned from any MongoDB operation + contains an error. It is quite common to forget to do this during + 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. + + + + TBD + + +
+
+ +
+ Overivew of MongoTemplate Methods + + +
-
+
Working with collections ...
-
+
Creating an index ...
-
+
Saving and retreiving objects as documents in a collection ...
-
+
Querying documents in a collection ...
-
+
Updating documents in a collection ...
-
+
Roadmap ahead The Spring Data Document projects MongoDB support is in its early