@ -15,7 +15,8 @@
<section id= "mongodb:requirements" > <section id= "mongodb:requirements" >
<title > MongoDB Requirements</title> <title > MongoDB Requirements</title>
<para > DATADOC requires MongoDB 1.4 while 1.6 is recommended.</para> <para > DATADOC requires MongoDB 1.4 while the latest production release
(1.6.5 as of this writing) is recommended.</para>
</section> </section>
<section id= "mongodb:architecture" > <section id= "mongodb:architecture" >
@ -37,16 +38,14 @@
<emphasis > Template implemenattion</emphasis> <emphasis > Template implemenattion</emphasis>
- 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
<xref linkend= "mongodb:template" /> <xref linkend= "mongodb:template" />
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.
</listitem> </listitem>
<listitem > <listitem >
<emphasis > Support Classes</emphasis> <emphasis > Support Classes</emphasis>
- that offer reusable components such as mapping support and exception translation. - that offer reusable components such as mapping support and exception translation.
@ -62,45 +61,92 @@
<section id= "mongodb:connectors" > <section id= "mongodb:connectors" >
<title > Connecting to MongoDB</title> <title > Connecting to MongoDB</title>
<para > One of the first tasks when using MongoDB and Spring is to connect <para > One of the first tasks when using MongoDB and Spring is to create a
to the store through the IoC container. To do that</para> <classname > com.mongodb.Mongo</classname> object using the IoC container.
There are two main ways to do this, either using Java based bean metadata
<para > The easiest way to work with a or XML based bean metadata. These are discussed in the following
<interfacename > MongoFactoryBean</interfacename> is to configure a sections.<note >
<classname > MongoFactory</classname> bean. This has the added advantage of <para > For those not familiar with how to configure the Spring
also acting as an ExceptionTranslator that can be used to translate any container using Java based bean metadata instead of XML based metadata
Mongo exceptions to exceptions in the see the high level introduction in the reference docs <ulink
<classname > SpringDataAccessException</classname> hierarchy as long as your url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/new-in-3.html#new-java-configuration"
data access classes are annotatded with @Repository and you are using an userlevel="">here</ulink> as well as the detailed documentation <ulink
<classname > PersistenceExceptionTranslationPostProcessor</classname> (see url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-java-instantiating-container">here</ulink> .</para>
<link linkend= "???" > Spring API docs</link> ).</para> </note> </para>
<para > You have two basic choices - use Java based configuration or XML <section >
based configuration. An example fo a basic Java configuratopn style <title > Using Java based based metadata</title>
is:</para>
<para > An example of using Java based bean metadata to register an
instance of a <classname > com.mongodb.Mongo</classname> is shown
below<example >
<title > Registering a com.mongodb.Mongo object using Java based bean
metadata</title>
<programlisting language= "java" > @Configuration
public class AppConfig {
<example > /*
<title > Java based Spring configuration for MongoDB</title> * Factory bean that creates the com.mongodb.Mongo instance
*/
public @Bean Mongo mongo() throws UnknownHostException, MongoException {
return new Mongo("localhost");
}
<programlisting language= "java" > @Configuration }
</programlisting>
</example> </para>
<para > 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.</para>
<para > However, you may also register an instance of
<classname > com.mongodb.Mongo</classname> instance with the container
using Spring's <interfacename > MongoFactoryBean</interfacename> . As
compared to instantiating a <classname > com.mongodb.Mongo</classname>
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
<classname > SpringDataAccessException</classname> . This is part of <ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/dao.html">Spring's
DAO support features</ulink> . The exception translation feature works
hand in hand with Spring's <classname > @Repository</classname>
annotation. To enable exception translation on data access components
annotated with <classname > @Repository</classname> register a
<classname > PersistenceExceptionTranslationPostProcessor</classname>
(<ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-annotation-config">JavaDoc</ulink> )
with the container. <note >
<para > While enabling exception translation can be done using Java
based bean metadata it is often done declaratively in XML using
Spring's context namespace
<literal > < context::annotation-config/> </literal> .to enable
<ulink
url="http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/beans.html#beans-annotation-config">annotation
configuration features</ulink> .</para>
</note> </para>
<para > An example of a Java based bean metadata that supports exception
translation on <classname > @Repository</classname> annotated classes is
shown below:</para>
<example >
<title > Registering a com.mongodb.Mongo object using Spring's
MongoFactoryBean and enabling Spring's exception translation
support</title>
<programlisting language= "java" > @Configuration
public class AppConfig { public class AppConfig {
/* /*
* Factory bean that creates the Mongo instance * Factory bean that creates the com.mongodb. Mongo instance
*/ */
public @Bean MongoFactoryBean mongo() { public @Bean MongoFactoryBean mongo() {
MongoFactoryBean mongo = new MongoFactoryBean(); MongoFactoryBean mongo = new MongoFactoryBean();
mongo.setHost("localhost"); mongo.setHost("localhost");
return mongo; 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 * Use this post processor to translate any MongoExceptions thrown in @Repository annotated classes
@ -111,29 +157,104 @@ public class AppConfig {
} }
</programlisting> </programlisting>
</example> </example>
<para > The following shows the same configuration using XML:</para> <para > if you prefer to use the standard MongoDB API to create a
com.mongodb.Mongo instance and have exception translation enabled on
your <classname > @Repository</classname> instances, simply inherit from
<classname > MongoExceptionTranslationConfig</classname> as shown below.
</para>
<example > <example >
<title > XML based Spring configuration for MongoDB</title> <title > Registering a com.mongodb.Mongo object and enabling Spring's
exception translation support</title>
<programlisting language= "xml" > < !-- Factory bean that creates the Mongo instance --> <programlisting language= "java" > @Configuration
< bean id="mongo" class="org.springframework.data.document.mongodb.MongoFactoryBean"> public class AppConfig extends MongoExceptionTranslationConfig {
< property name="host" value="localhost"/>
< /bean> public @Bean Mongo mongo() throws UnknownHostException, MongoException {
return new Mongo("localhost");
< !-- A basic MongoTemplate instance --> }
< bean id="mongoTemplate" class="org.springframework.data.document.mongodb.MongoTemplate"> }
< constructor-arg name="mongo" ref="mongo"/> </programlisting>
< constructor-arg name="databaseName" value="test"/> </example>
< constructor-arg name="defaultCollectionName" value="HelloMongo"/> </section>
< /bean>
< !-- Use this post processor to translate any MongoExceptions thrown in @Repository annotated classes --> <section >
< bean class="org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor"/> <title > Using XML based metadata</title>
<para > While you can use Spring's traditional < beans/> XML
namespace to register an instance of
<classname > com.mongodb.Mongo</classname> 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. </para>
<para > To use the Mongo namespace elements you will need to reference the
Mongo schema:</para>
<example >
<title > XML schmea to configure MongoDB</title>
<programlisting language= "xml" > < ?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>
</programlisting>
</example>
<para > A more advanced configuration with MongoOptions is shown
below</para>
<example >
<title > XML schmea to configure MongoOptinos in MongoDB</title>
<programlisting language= "xml" > < beans>
< mongo:mongo host="localhost" port="27017">
< mongo:options connectionsPerHost="10"
threadsAllowedToBlockForConnectionMultiplier="5"
maxWaitTime="12000"
connectTimeout="0"
socketTimeout="0"
autoConnectRetry="0"/>
< /mongo:mongo/>
< /beans>
</programlisting>
</example>
<para > A configuration using replica sets is shown below:<example >
<title > XML schmea to configure replica sets in MongoDB</title>
<programlisting language= "xml" > < beans>
< mongo:mongo>
< ! replica set TBD -->
< mongo:mongo>
< /beans>
</programlisting> </programlisting>
</example> </example> </para>
</section>
</section> </section>
<section id= "mongodb:template" > <section id= "mongodb:template" >
@ -148,45 +269,182 @@ public class AppConfig {
mapping between MongoDB JSON documents and your domain classes. Out of the mapping between MongoDB JSON documents and your domain classes. Out of the
box, <classname > MongoTemplate</classname> uses a Java-based default box, <classname > MongoTemplate</classname> uses a Java-based default
converter but you can also write your own converter classes to be used for converter but you can also write your own converter classes to be used for
reading and storing domain objects. Once configured, the template is reading and storing domain objects. </para>
thread-safe and can be reused across multiple instances.</para>
<note >
<para > Once configured, <classname > MongoTemplate</classname> is
thread-safe and can be reused across multiple instances.</para>
</note>
<para > Let's look at a couple of examples for how to work with the <para > Let's look at a couple of examples for how to work with the
<classname > MongoTemplate</classname> .</para> <classname > MongoTemplate</classname> in the context of the Spring
container.</para>
<section >
<title > Instantiating MongoTemplate</title>
<para > In Java based configuration using the driver's com.mongodb.Mongo
object </para>
<example >
<title > Registering a com.mongodb.Mongo object and enabling Spring's
exception translation support</title>
<programlisting language= "java" > @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");
}
}
</programlisting>
</example>
<para > Alternatively using MongoFactoryBean, which avoid dealing with the
checked UnknownHostException</para>
<example >
<title > Registering a com.mongodb.Mongo object and enabling Spring's
exception translation support</title>
<programlisting language= "java" > @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();
}
}
</programlisting>
<para > There are several overloaded constructors of MongoTemplate.
These are</para>
<para > </para>
<itemizedlist >
<listitem >
<para > MongoTemplate(Mongo mongo, String databaseName) - takes the
default database name to operate against</para>
</listitem>
<listitem >
<para > MongoTemplate(Mongo mongo, String databaseName, String
defaultCollectionName) - adds the default collection name to
operate against.</para>
</listitem>
<listitem >
<para > MongoTemplate(Mongo mongo, String databaseName, String
defaultCollectionName, MongoConverter mongoConverter) - override
with a provided MongoConverter. Default is
SimpleMongoConverter</para>
</listitem>
<listitem >
<para > MongoTemplate(Mongo mongo, String databaseName, String
defaultCollectionName, MongoConverter mongoConverter, WriteConcern
writeConcern, WriteResultChecking writeResultChecking) - Specify a
default WriteConcern and also WriteResultChecking policy</para>
</listitem>
<listitem >
<para > MongoTemplate(Mongo mongo, String databaseName, String
defaultCollectionName, WriteConcern writeConcern,
WriteResultChecking writeResultChecking) </para>
</listitem>
<listitem >
<para > MongoTemplate(Mongo mongo, String databaseName, WriteConcern
writeConcern, WriteResultChecking writeResultChecking)</para>
</listitem>
</itemizedlist>
<para > The</para>
</example>
<section >
<title > WriteResultChecking Policy</title>
<para > 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. </para>
<para > </para>
<para > TBD</para>
<para > </para>
</section>
</section>
<section >
<title > Overivew of MongoTemplate Methods</title>
<para > </para>
</section>
<section id= "mongodb:template" > <section id= "mongodb-template-collections " >
<title > Working with collections</title> <title > Working with collections</title>
<para > ...</para> <para > ...</para>
</section> </section>
<section id= "mongodb:template" > <section id= "mongodb-template-index " >
<title > Creating an index</title> <title > Creating an index</title>
<para > ...</para> <para > ...</para>
</section> </section>
<section id= "mongodb:template" > <section id= "mongodb-template-sav e" >
<title > Saving and retreiving objects as documents in a <title > Saving and retreiving objects as documents in a
collection</title> collection</title>
<para > ...</para> <para > ...</para>
</section> </section>
<section id= "mongodb:template" > <section id= "mongodb-template-query" label= " " >
<title > Querying documents in a collection</title> <title > Querying documents in a collection</title>
<para > ...</para> <para > ...</para>
</section> </section>
<section id= "mongodb:template" > <section id= "mongodb-template-upd ate" >
<title > Updating documents in a collection</title> <title > Updating documents in a collection</title>
<para > ...</para> <para > ...</para>
</section> </section>
</section> </section>
<section id= "mongodb:future" > <section id= "mongodb-roadmap " >
<title > Roadmap ahead</title> <title > Roadmap ahead</title>
<para > The Spring Data Document projects MongoDB support is in its early <para > The Spring Data Document projects MongoDB support is in its early
Mark Pollack
15 years ago