There are a few support options available:

For information on the Spring Data Mongo source code repository, nightly builds and snapshot artifacts please see the Spring Data Mongo homepage.

You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Spring Community forums. To follow developer activity look for the mailing list information on the Spring Data Mongo homepage.

If you encounter a bug or want to suggest an improvement, please create a ticket on the Spring Data issue tracker.

To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the Spring Community Portal.

Lastly, you can follow the SpringSource Data blog or the project team on Twitter (SpringData)

Implementing a data access layer of an application has been cumbersome for quite a while. Too much boilerplate code had to be written. Domain classes were anemic and haven't been designed in a real object oriented or domain driven manner.

Using both of these technologies makes developers life a lot easier regarding rich domain model's persistence. Nevertheless the amount of boilerplate code to implement repositories especially is still quite high. So the goal of the repository abstraction of Spring Data is to reduce the effort to implement data access layers for various persistence stores significantly

The following chapters will introduce the core concepts and interfaces of Spring Data repositories.

The central interface in Spring Data repository abstraction is Repository (probably not that much of a surprise). It is typeable to the domain class to manage as well as the id type of the domain class and provides some sophisticated functionality around CRUD for the entity managed.

Example 4.1. Repository interface

public interface Repository<T, ID extends Serializable> {

    T save(T entity);                                                                    

    T findById(ID primaryKey);                                                           

    List<T> findAll();                                                                   

    Page<T> findAll(Pageable pageable);                                                  

    Long count();                                                                        

    void delete(T entity);                                                               

    boolean exists(ID primaryKey);                                                       

    // … more functionality omitted.
}

	Saves the given entity.
	Returns the entity identified by the given id.
	Returns all entities.
	Returns a page of entities.
	Returns the number of entities.
	Deletes the given entity.
	Returns whether an entity with the given id exists.

Usually we will have persistence technology specific sub-interfaces to include additional technology specific methods. We will now ship implementations for a variety of Spring Data modules that implement that interface.

On top of the Repository there is a PagingAndSortingRepository abstraction that adds additional methods to ease paginated access to entities:

public interface PagingAndSortingRepository<T, ID extends Serializable> extends Repository<T, ID> {

    List<T> findAll(Sort sort);

    Page<T> findAll(Pageable pageable);
}

Accessing the second page of User by a page size of 20 you could simply do something like this:

PagingAndSortingRepository<User, Long> repository = // … get access to a bean
Page<User> users = repository.findAll(new PageRequest(1, 20);

Next to standard CRUD functionality repositories are usually query the underlying datastore. With Spring Data declaring those queries becomes a four-step process (we use the JPA based module as example but that works the same way for other stores):

At this stage we barely scratched the surface of what's possible with the repositories but the general approach should be clear. Let's go through each of these steps and and figure out details and various options that you have at each stage.

4.3.2. Defining query methods

4.3.2.1. Query lookup strategies

The next thing we have to discuss is the definition of query methods. There's roughly two main ways how the repository proxy is generally able to come up with the store specific query from the method name. The first option is to derive the quer from the method name directly, the second is using some kind of additionally created query. What detailed options are available pretty much depends on the actual store. However there's got to be some algorithm the decision which actual query to is made.

There's three strategies for the repository infrastructure to resolve the query. The strategy to be used can be configured at the namespace through the query-lookup-strategy attribute. However might be the case that some of the strategies are not supported for the specific datastore. Here are your options:

CREATE

This strategy will try to construct a store specific query from the query method's name. The general approach is to remove a given set of well-known prefixes from the method name and parse the rest of the method. Read more about query construction in ???.

USE_DECLARED_QUERY

This strategy tries to find a declared query which will be used for execution first. The query could be defined by an annotation somwhere or declared by other means. Please consult the documentation of the specific store to find out what options are available for that store. If the repository infrastructure does not find a declared query for the method at bootstrap time it will fail.

CREATE_IF_NOT_FOUND (default)

This strategy is actually a combination of the both mentioned above. It will try to lookup a declared query first but create a custom method name based query if no declared query was found. This is default lookup strategy and thus will be used if you don't configure anything explicitly. It allows quick query definition by method names but also custom tuning of these queries by introducing declared queries for those who need explicit tuning.

4.3.2.2. Query creation

The query builder mechanism built into Spring Data repository infrastructue is useful to build constraining queries over entities of the repository. We will strip the prefixes findBy, find, readBy, read, getBy as well as get from the method and start parsing the rest of it. At a very basic level you can define conditions on entity properties and concatenate them with AND and OR.

Example 4.3. Query creation from method names

public interface PersonRepository extends JpaRepository<User, Long> {

  List<Person> findByEmailAddressAndLastname(EmailAddress emailAddress, String lastname);
}

The actual result of parsing that method will of course depend on the persistence store we create the query for. However there are some general things to notice. The expression are usually property traversals combined with operators that can be concatenated. As you can see in the example you can combine property expressions with And and Or. Beyond that you will get support for various operators like Between, LessThan, GreaterThan, Like for the property expressions. As the operators supported can vary from datastore to datastore please consult the according part of the reference documentation.

4.3.2.2.1. Property expressions

Property expressions can just refer to a direct property of the managed entity (as you just saw in the example above. On query creation time we already make sure that the parsed property is at a property of the managed domain class. However you can also traverse nested properties to define constraints on. Assume Persons have Addresses with ZipCodes. In that case a method name of

List<Person> findByAddressZipCode(ZipCode zipCode);

will create the property traversal x.address.zipCode. The resolution algorithm starts with interpreting the entire part (AddressZipCode) as property and checks the domain class for a property with that name (uncapitalized). If it succeeds it just uses that. If not it starts splitting up the source at the camel case parts from the right side into a head and a tail and tries to find the according property, e.g. AddressZip and Code. If we find a property with that head we take the tail and continue building the tree down from there. As in our case the first split does not match we move the split point to the left (Address, ZipCode).

Now although this should work for most cases, there might be cases where the algorithm could select the wrong property. Suppose our Person class has a addressZip property as well. Then our algorithm would match in the first split round already and essentially choose the wrong property and finally fail (as the type of addressZip probably has no code property). To resolve this ambiguity you can use _ inside your method name to manually define traversal points. So our method name would end up like so:

List<Person> findByAddress_ZipCode(ZipCode zipCode);

4.3.2.3. Special parameter handling

To hand parameters to your query you simply define method parameters as already seen in in examples above. Besides that we will recognizes certain specific types to apply pagination and sorting to your queries dynamically.

Example 4.4. Using Pageable and Sort in query methods

Page<User> findByLastname(String lastname, Pageable pageable);

List<User> findByLastname(String lastname, Sort sort);

List<User> findByLastname(String lastname, Pageable pageable);

The first method allows you to pass a Pageable instance to the query method to dynamically add paging to your statically defined query. Sorting options are handed via the Pageable instance, too. If you only need sorting, simply add a Sort parameter to your method. As you also can see, simply returning a List is possible as well. We will then not retrieve the additional metadata required to build the actual Page instance but rather simply restrict the query to lookup only the given range of entities.

	Note
	To find out how many pages you get for a query entirely we have to trigger an additional count query. This will be derived from the query you actually trigger by default.

<?xml version="1.0" encoding="UTF-8"?>
<beans:beans xmlns:beans="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://www.springframework.org/schema/data/jpa
  xsi:schemaLocation="http://www.springframework.org/schema/beans 
    http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/data/jpa
    http://www.springframework.org/schema/data/jpa/spring-jpa.xsd">

  <repositories base-package="com.acme.repositories" />

</beans:beans>

<repositories base-package="com.acme.repositories">
  <context:exclude-filter type="regex" expression=".*SomeRepository" />
</repositories>

<repositories base-package="com.acme.repositories">
  <repository id="userRepository" />
</repositories>

RepositoryFactorySupport factory = … // Instantiate factory here
UserRepository repository = factory.getRepository(UserRepository.class);

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. An easy way to bootstrap setting up a working environment is to create a Spring based project in STS.

First you need to set up a running Mongodb server. Refer to the Mongodb Quick Start guide for an explanation on how to startup a Mongo instance. Once installed starting Mongo is typically a matter of executing the following command: MONGO_HOME/bin/mongod

To create a Spring project in STS go to File -> New -> Spring Template Project -> Simple Spring Utility Project --> press Yes when prompted. Then enter a project and a package name such as org.spring.mongodb.example.

Then add the following to pom.xml dependencies section.

<dependencies>

  <!-- other dependency elements omitted -->

  <dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-mongodb</artifactId>
    <version>1.0.0.M2</version>
  </dependency>

  <dependency>
    <groupId>cglib</groupId>
    <artifactId>cglib</artifactId>
    <version>2.2</version>
  </dependency>

</dependencies>

The cglib dependency is there as we will use Spring's Java configuration style. Also change the version of Spring in the pom.xml to be

<spring.framework.version>3.0.5.RELEASE</spring.framework.version>

You will also need to add the location of the Spring Milestone repository for maven to your pom.xml which is at the same level of your <dependencies/> element

<repositories>
  <repository>
    <id>spring-milestone</id>
    <name>Spring Maven MILESTONE Repository</name>
    <url>http://maven.springframework.org/milestone</url>
  </repository>
</repositories>

The repository is also browseable here.

You may also want to set the logging level to DEBUG to see some additional information, edit the log4j.properties file and add

log4j.category.org.springframework.data.document.mongodb=DEBUG

Next, in the org.spring.mongodb package in the src/test/java directory create a class as shown below.

package org.spring.mongodb;

import org.springframework.context.annotation.Configuration;
import org.springframework.data.document.mongodb.MongoTemplate;
import org.springframework.data.document.mongodb.config.AbstractMongoConfiguration;

import com.mongodb.Mongo;

@Configuration
public class MongoConfig extends AbstractMongoConfiguration {

  @Override
  public Mongo mongo() throws Exception {
    return new Mongo("localhost");
  }

  @Override
  public MongoTemplate mongoTemplate() throws Exception {
    return new MongoTemplate(mongo() , "database", "mongoexample");
  }

}

Then create a simple Person class to persist

package org.spring.mongodb;

public class Person {

  private String id;
  
  private String name;

  public Person(String id, String name) {
    this.id = id;
    this.name = name;
  }
  
  public String getId() {
    return id;
  }

  public String getName() {
    return name;
  }

  @Override
  public String toString() {
    return "Person [id=" + id + ", name=" + name + "]";
  }
  
}

And a main application to run

package org.spring.mongodb;

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.springframework.context.ApplicationContext;
import org.springframework.context.annotation.AnnotationConfigApplicationContext;
import org.springframework.data.document.mongodb.MongoOperations;
import org.springframework.data.document.mongodb.query.Criteria;
import org.springframework.data.document.mongodb.query.Query;

public class MongoApp {

  private static final Log log = LogFactory.getLog(MongoApp.class);

  public static void main(String[] args) {
    ApplicationContext ctx = new AnnotationConfigApplicationContext(MongoConfig.class);
    MongoOperations mongoOps = ctx.getBean(MongoOperations.class);
    
    mongoOps.insert(new Person("1234", "Joe"));

    log.info(mongoOps.findOne(new Query(Criteria.where("name").is("Joe")), Person.class));
  }

}

This will produce the following output

MongoPersistentEntityIndexCreator] - <Analyzing class class org.spring.mongodb.Person for index information.>
LoggingEventListener] - <onBeforeConvert: Person [id=1234, name=Joe]>
LoggingEventListener] - <onBeforeSave: Person [id=1234, name=Joe], { "_id" : "1234" , "name" : "Joe"}>
MongoTemplate] - <insert DBObject: { "_id" : "1234" , "name" : "Joe"}>
LoggingEventListener] - <onAfterSave: Person [id=1234, name=Joe], { "_id" : "1234" , "name" : "Joe"}>
MongoTemplate] - <findOne using query: { "name" : "Joe"} in db.collection: database.person>
LoggingEventListener] - <onAfterLoad: { "_id" : "1234" , "name" : "Joe"}>
LoggingEventListener] - <onAfterConvert: { "_id" : "1234" , "name" : "Joe"}, Person [id=1234, name=Joe]>
MongoApp] - <Person [id=1234, name=Joe]>

There is an github repository with several examples that you can download and play around with to get a feel for how the library works.

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.

	Note
	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.

@Configuration
public class AppConfig {

  /*
   * Use the standard Mongo driver API to create a com.mongodb.Mongo instance.
   */
   public @Bean Mongo mongo() throws Exception {
       return new Mongo("localhost");
   }
}      

@Configuration
public class AppConfig {

    /*
     * Factory bean that creates the com.mongodb.Mongo instance
     */
     public @Bean MongoFactoryBean mongo() {
          MongoFactoryBean mongo = new MongoFactoryBean();
          mongo.setHost("localhost");
          return mongo;
     }
}

<?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">

    <!-- Default bean name is 'mongo' -->
    <mongo:mongo host="localhost" port="27017"/>

    <!-- To translate any MongoExceptions thrown in @Repository annotated classes -->
    <context:annotation-config/>

</beans>
        

<beans>

  <mongo:mongo host="localhost" port="27017">
    <mongo:options connectionsPerHost="10"
                   threadsAllowedToBlockForConnectionMultiplier="5"
                   maxWaitTime="12000"
                   connectTimeout="0"
                   socketTimeout="0"
                   autoConnectRetry="0"/>
  </mongo:mongo/>

</beans>
        

@Configuration
public class AppConfig {

  /*
   * Use the standard Mongo driver API to create a com.mongodb.Mongo instance that supports replica sets
   */
  @Bean
  public Mongo mongo() throws Exception {
    
    List<ServerAddress> serverAddresses = new ArrayList<ServerAddress>();    
    serverAddresses.add( new ServerAddress( "127.0.0.1", 27017 ) ); 
    serverAddresses.add( new ServerAddress( "127.0.0.1", 27018 ) );
    
    MongoOptions options = new MongoOptions();
    options.autoConnectRetry = true; 
    
    Mongo mongo  = new Mongo( serverAddresses, options );
    mongo.slaveOk();
    
    return mongo;
  }
}      

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.

	Note
	Once configured, MongoTemplate is thread-safe and can be reused across multiple instances.

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 MongoTemplate class implements the interface MongoOperations. In as much as possible, the methods on MongoOperations are named after methods available on the MongoDB driver Collection object. For example, you will find methods such as "find", "findAndModify", "findOne", "insert", "remove", "save", "update" and "updateMulti". The design goal was to make it as easy as possible to transition between the use of the base MongoDB driver and MongoOperations. The difference in betwee the two is that MongOperations can be passed domain objects instead of DBObject and there are fluent APIs for Query, Criteria, and Update operations instead of DBObject..

	Note
	The preferred way to reference the operations on MongoTemplate instance is via its interface MongoOperations.

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.

5.4.1. Instantiating MongoTemplate

You can use Java to create and register an instance of MongoTemplate as shown below.

Example 5.6. Registering a com.mongodb.Mongo object and enabling Spring's exception translation support

@Configuration
public class AppConfig {

    public @Bean Mongo mongo() throws Exception {
        return new Mongo("localhost");
    }

    public @Bean MongoTemplate mongoTemplate() throws Exception {
        return new MongoTemplate(mongo(), "mydatabase", "mycollection");
    }
}
        

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.

	Note
	The preferred way to reference the operations on MongoTemplate instance is via its interface MongoOperations.

5.4.1.1. 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.

The default is to use a WriteResultChecking of NONE.

5.4.1.2. 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.

	Note
	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.

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.

	Note
	MongoOperations is the interface that MongoTemplate implements.

public class PersonExample { 

  private static final Log log = LogFactory.getLog(PersonExample.class);
  
  @Autowired
  private MongoOperations mongoOps;
  
  public void doWork() {
   
    Person p = new Person();
    p.setFirstName("Sven");
    p.setAge(22);
    
    // Save   
    mongoOps.save(p);
    log.debug("Saved: " + p);
    
    // Find
    p = mongoOps.findOne(query(whereId().is(p.getId())), Person.class);    
    log.debug("Found: " + p);
    
    // Update age to 24 for Sven
    mongoOps.updateFirst(query(where("firstName").is("Sven")), update("age", 24));    
    p = mongoOps.findOne(query(whereId().is(p.getId())), Person.class);    
    log.debug("Updated: " + p);
    
    // Delete    
    mongoOps.remove(p);

    // Check that deletion worked
    List<Person> people =  mongoOps.getCollection(Person.class);
    log.debug("Number of people = : " + people.size());

}

This would produce the following log output (including some debug message from MongoTemplate itself)

Saved: PersonWithIdPropertyOfTypeString [id=4d9e82ac94fa72c65a9e7d5f, firstName=Sven, age=22]
findOne using query: { "_id" : { "$oid" : "4d9e82ac94fa72c65a9e7d5f"}} in db.collection: database.personexample
Found: PersonWithIdPropertyOfTypeString [id=4d9e82ac94fa72c65a9e7d5f, firstName=Sven, age=22]
findOne using query: { "_id" : { "$oid" : "4d9e82ac94fa72c65a9e7d5f"}} in db.collection: database.personexample
Updated: PersonWithIdPropertyOfTypeString [id=4d9e82ac94fa72c65a9e7d5f, firstName=Sven, age=24]
remove using query: { "_id" : { "$oid" : "4d9e82ac94fa72c65a9e7d5f"}}
Number of people = : 0

There was implicit conversion using the MongoConverter between a String and ObjectId as stored in the database and recognizing a convention of the property "Id" name.

	Note
	This example is meant to show the use of save, update and remove operations on MongoTemplate and not to show complex mapping functionality

The query stynax used in the example is explained in more detail in the section Querying Documents.

5.5.1. Methods for saving and inserting documents

There are several convenient methods on MongoTemplate for saving and inserting your objects. In addition to using a MongoCoverter to converter your domain object to the database, you can also use an implementation of the MongoWriter interface to have very fine grained control over the conversion process.

	Note
	The difference between insert and save operations is that a save operation will perform an insert if the object is not already present.

The simple case of using the save operation is to pass in as an argument only the object to save. In this case the default collection assigned to the template will be used unless the converter overrides this default through the use of more specific mapping metadata. You may also call the save operation with a specific collection name.

When inserting or saving, if the Id property is not set, the assumption is that its value will be autogenerated by the database. As such, for autogeneration of an ObjectId to succeed the type of the Id property/field in your class must be either a String, ObjectId, or BigInteger.

Here is a basic example of using the save operation and retrieving its contents.

Example 5.7. Inserting and retrieving documents using the MongoTemplate

import static org.springframework.data.document.mongodb.query.Criteria.where;
import static org.springframework.data.document.mongodb.query.Criteria.query;

    ...

    Person p = new Person("Bob", 33);
    mongoTemplate.insert("MyCollection", p);

    Person qp = mongoTemplate.findOne("MyCollection", query(where("age").is(33)), Person.class);
        

The four save operations available to you are listed below.

• 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.

A similar set of insert operations is listed below

• void insert (Object objectToSave) Insert the object to the default collection.

• void insert (String collectionName, Object objectToSave) Insert the object to the specified collection.

• <T> void insert (T objectToSave, MongoWriter<T> writer) Insert the object into the default collection using the provided writer.

• <T> void insert (String collectionName, T objectToSave, MongoWriter<T> writer) Insert the object into the specified collection using the provided writer.

Unless and explicit MongoWriter is passed into the save or insert method, the the template's MongoConverter will be used.

5.5.1.1. Saving using MongoWriter

The MongoWriter interface allows you to have lower level control over the mapping of an object into a DBObject. The MongoWriter interface is

/**
 * A MongoWriter is responsible for converting an object of type T to the native MongoDB
 * representation DBObject.
 *
 * @param <T> the type of the object to convert to a DBObject
 */
public interface MongoWriter<T> {

  /**
   * Write the given object of type T to the native MongoDB object representation DBObject.
   *
   * @param t   The object to convert to a DBObject
   * @param dbo The DBObject to use for writing.
   */
  void write(T t, DBObject dbo);

}

5.5.1.2. Inserting Lists of objects in batch

The MongoDB driver supports inserting a collection of documents in one operation. The methods in the MongoOperations interface that support this functionality are listed below

• void insertList (List<? extends Object> listToSave) Insert a list of objects into the default collection in a single batch write to the database.

• void insertList (String collectionName, List<? extends Object> listToSave) Insert a list of objects into the specified collection in a single batch write to the database.

• <T> void insertList (List<? extends T> listToSave, MongoWriter<T> writer) Insert the object into the default collection using the provided writer.

• <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

import static org.springframework.data.document.mongodb.query.Criteria.where;
import static org.springframework.data.document.mongodb.query.Query.query;
import static org.springframework.data.document.mongodb.query.Update

          ...

  WriteResult wr = mongoTemplate.updateMulti(query(where("accounts.accountType").is(Account.Type.SAVINGS)),
                                             update.inc("accounts.$.balance", 50.00));
        

You can express you queries using the Query and Criteria classes which have method names that mirror the native MongoDB operator names such as lt, lte, is, and others. The Query and Criteria classes follow a fluent API style so that you can easily chain together multiple method criteria and queries while having easy to understand code. Static imports in Java are used to help remove the need to see the 'new' keyword for creating Query and Criteria instances so as to improve readability.

GeoSpatial queries are also supported and are described more in the section GeoSpatial Queries.

import static org.springframework.data.document.mongodb.query.Criteria.where;
import static org.springframework.data.document.mongodb.query.Query.query;

    ...

     List<Person> result = mongoTemplate.find(query(where("age").lt(50).and("accounts.balance").gt(1000.00d)),Person.class);
        

/**
 * A MongoWriter is responsible for converting a native MongoDB DBObject to an object of type T.
 *
 * @param <T> the type of the object to convert from a DBObject
 */
public interface MongoReader<T> {

  /**
   * Ready from the native MongoDB DBObject representation to an instance of the class T. 
   * The given type has to be the starting point for marshalling the {@link DBObject} 
   * into it. So in case there's no real valid data inside {@link DBObject} for the 
   * given type, just return an empty instance of the given type.
   *
   * @param clazz the type of the return value
   * @param dbo   theDBObject
   * @return the converted object
   */
  <S extends T> S read(Class<S> clazz, DBObject dbo);
}

5.6.3. GeoSpatial Queries

MongoDB supports GeoSpatial queries through the use of operators such as $near, $within, and $nearSphere. Methods specific to geospatial queries are available on the Criteria class. There are also a few shape classes, Box, Circle, and Point that are used in conjunction with geospatial related Criteria methods.

To understand how to perform GeoSpatial queries we will use the following Venue class taken from the integration tests.which relies on using the rich MappingMongoConverter.

@Document(collection="newyork")
public class Venue {
    
  @Id
  private String id;
  private String name;
  private double[] location;
  
  @PersistenceConstructor
  Venue(String name, double[] location) {
    super();
    this.name = name;
    this.location = location;    
  }
  
  public Venue(String name, double x, double y) {
    super();
    this.name = name;
    this.location = new double[] { x, y };    
  }

  public String getName() {
    return name;
  }

  public double[] getLocation() {
    return location;
  }

  @Override
  public String toString() {
    return "Venue [id=" + id + ", name=" + name + ", location="
        + Arrays.toString(location) + "]";
  } 
}

To find locations within a circle, the following query can be used.

Circle circle = new Circle(-73.99171, 40.738868, 0.01);
List<Venue> venues = 
    template.find(new Query(Criteria.where("location").withinCenter(circle)), Venue.class);

To find venues within a circle using Spherical coordinates the following query can be used

Circle circle = new Circle(-73.99171, 40.738868, 0.003712240453784);
List<Venue> venues = 
    template.find(new Query(Criteria.where("location").withinCenterSphere(circle)), Venue.class);

To find venues within a Box the following query can be used

//lower-left then upper-right
Box box = new Box(new Point(-73.99756, 40.73083), new Point(-73.988135, 40.741404));  
List<Venue> venues = 
    template.find(new Query(Criteria.where("location").withinBox(box)), Venue.class);

To find venues near a Point, the following query can be used

Point point = new Point(-73.99171, 40.738868);
List<Venue> venues = 
    template.find(new Query(Criteria.where("location").near(point).maxDistance(0.01)), Venue.class);

To find venues near a Point using Spherical coordines the following query can be used

Point point = new Point(-73.99171, 40.738868);
List<Venue> venues = 
    template.find(new Query(
        Criteria.where("location").nearSphere(point).maxDistance(0.003712240453784)), 
        Venue.class);

	Note
	Support for the GeoNear command will be provided in the RC release.

MongoTemplate provides a few methods for managing indexes and collections.

mongoTemplate.ensureIndex("MyCollection", new Index().on("name",Order.ASCENDING));        

mongoTemplate.ensureIndex(new GeospatialIndex("location"));

DBCollection collection = null;
if (!mongoTemplate.getCollectionNames().contains("MyNewCollection")) {
    collection = mongoTemplate.createCollection("MyNewCollection");
}

mongoTemplate.dropCollection("MyNewCollection");        

You can also get at the Mongo driver's collection.command( ) method using the executeCommand methods on MongoTemplate. These will also perform exception translation into Spring's Data Access Exception hierarchy.

Built into the MongoDB mapping framework are several org.springframework.context.ApplicationEvent events that your application can respond to by registering special beans in the ApplicationContext. By being based off Spring's ApplicationContext event infastructure this enables other products, such as Spring Integration, to easily receive these events as they are a well known eventing mechanism in Spring based applications.

To intercept an object before it goes through the conversion process (which turns your domain object into a com.mongodb.DBObject), you'd register a subclass of org.springframework.data.document.mongodb.mapping.event.AbstractMappingEventListener that overrides the onBeforeConvert method. When the event is dispatched, your listener will be called and passed the domain object before it goes into the converter.

public class BeforeConvertListener<BeforeConvertEvent, Person> extends AbstractMappingEventListener {
  @Override
  public void onBeforeConvert(Person p) {
    ... does some auditing manipulation, set timestamps, whatever ...
  }
}
        

To intercept an object before it goes into the database, you'd register a subclass of org.springframework.data.document.mongodb.mapping.event.AbstractMappingEventListener that overrides the onBeforeSave method. When the event is dispatched, your listener will be called and passed the domain object and the converted com.mongodb.DBObject.

public class BeforeSaveListener<BeforeSaveEvent, Person> extends AbstractMappingEventListener {
  @Override
  public void onBeforeSave(Person p, DBObject dbo) {
    ... change values, delete them, whatever ...
  }
}
        

Simply declaring these beans in your Spring ApplicationContext will cause them to be invoked whenever the event is dispatched.

The list of callback methods that are present in AbstractMappingEventListener are

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.

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.

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;
      }
    });

This chapter will point out the specialties for repository support for MongoDB. This builds on the core repository support explained inChapter 4, Repositories. So make sure you've got a sound understanding of the basic concepts explained there.

To access domain entities stored in a MongoDB you can leverage our sophisticated repository support that eases implementing those quite significantly. To do so, simply create an interface for your repository:

public class Person {

      private String id;
      private String firstname;
      private String lastname;
      private Address address;

      // … getters and setters omitted
}
    

We have a quite simple domain object here. Note that it has a property named id of typeObjectId. The default serialization mechanism used in MongoTemplate (which is backing the repository support) regards properties named id as document id. Currently we supportString, ObjectId and BigInteger as id-types.

public interface PersonRepository extends MongoRepository<Person, Long> {

   // additional custom finder methods go here
}
    

The central MongoDB CRUD repository interface is MongoRepository. Right now this interface simply serves typing purposes but we will add additional methods to it later. In your Spring configuration simply add

<?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:mongo="http://www.springframework.org/schema/data/mongo"
      xmlns:context="http://www.springframework.org/schema/context"
      xsi:schemaLocation="http://www.springframework.org/schema/beans
      http://www.springframework.org/schema/beans/spring-beans-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/context
      http://www.springframework.org/schema/context/spring-context-3.0.xsd">

  <mongo:mongo id="mongo" />
  
  <bean id="mongoTemplate" class="org.springframework.data.document.mongodb.MongoTemplate">
    <constructor-arg ref="mongo" />
    <constructor-arg value="database" />
    <constructor-arg value="collection" />
    <constructor-arg>
      <mongo:mapping-converter />
    </constructor-arg>
  </bean>

  <mongo:repositories base-package="com.acme.*.repositories" mongo-template-ref="myMongoTemplate" />
    …

</beans>

This namespace element will cause the base packages to be scanned for interfaces extending MongoRepository and create Spring beans for each of them found. By default the repositories will get a MongoTemplate Spring bean wired that is called mongoTemplate, so you only need to configure mongo-template-ref explicitly if you deviate from this convention.

MongoRepository extends PagingAndSortingRepository which you can read about inExample 4.1, “Repository interface”. In general it provides you with CRUD operations as well as methods for paginated and sorted access to the entities. Working with the repository instance is just a matter of dependency injecting it into a client. So accessing the second page of Persons at a page size of 10 would simply look something like this:

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
public class PersonRepositoryTests {

    @Autowired PersonRepository repository;

    @Test
    public void readsFirstPageCorrectly() {

      Page<Person> persons = repository.findAll(new PageRequest(0, 10));
      assertThat(persons.isFirstPage(), is(true));
    }
}    

The sample creates an application context with Spring's unit test support which will perform annotation based dependency injection into test cases. Inside the test method we simply use the repository to query the datastore. We hand the repository a PageRequest instance that requests the first page of persons at a page size of 10.

Most of the data access operations you usually trigger on a repository result a query being executed against the Mongo databases. Defining such a query is just a matter of declaring a method on the repository interface

public interface PersonRepository extends MongoRepository<Person, String> {

    List<Person> findByLastname(String lastname);

    Page<Person> findByFirstname(String firstname, Pageable pageable);

    Person findByShippingAddresses(Address address);

}     

The first method shows a query for all people with the given lastname. The query will be derived parsing the method name for constraints which can be concatenated with And and Or. Thus the method name will result in a query expression of{"lastname" : lastname}. The second example shows how pagination is applied to a query. Just equip your method signature with a Pageable parameter and let the method return a Page instance and we will automatically page the query accordingly. The third examples shows that you can query based on properties which are not a primitive type.

public interface PersonRepository extends MongoRepository<Person, String>

  @Query("{ 'firstname' : ?0 }")
  List<Person> findByThePersonsFirstname(String firstname);

}

public interface PersonRepository extends MongoRepository<Person, String>

  @Query(value="{ 'firstname' : ?0 }", fields="firstname,lastname")
  List<Person> findByThePersonsFirstname(String firstname);

}

QPerson person = new QPerson("person");
List<Person> result = repository.findAll(person.address.zipCode.eq("C0123"));

Page<Person> page = repository.findAll(person.lastname.contains("a"), 
                                       new PageRequest(0, 2, Direction.ASC, "lastname"));

public interface QueryDslPredicateExecutor<T> {

  T findOne(Predicate predicate);

  List<T> findAll(Predicate predicate);

  List<T> findAll(Predicate predicate, OrderSpecifier<?>... orders);

  Page<T> findAll(Predicate predicate, Pageable pageable);

  Long count(Predicate predicate);
}

public interface PersonRepository extends MongoRepository<Person, String>, QueryDslPredicateExecutor<Person> {

   // additional finder methods go here

}

You can configure the MongoMappingConverter as well as Mongo and MongoTemplate eithe using Java or XML based metadata.

Here is an example using Spring's Java based configuration

@Configuration
public class GeoSpatialAppConfig extends AbstractMongoConfiguration {

  @Bean
  public Mongo mongo() throws Exception {
    return new Mongo("localhost");
  }
  
  @Bean
  public MongoTemplate mongoTemplate() throws Exception {
    return new MongoTemplate(mongo(), "geospatial", "newyork", mappingMongoConverter());
  }
 
  // specify which package to scan for @Document objects.
  public String getMappingBasePackage() {
    return "org.springframework.data.document.mongodb";
  }

  // optional
  @Bean
  public LoggingEventListener<MongoMappingEvent> mappingEventsListener() {
    return new LoggingEventListener<MongoMappingEvent>();
  }
}

AbstractMongoConfiguration requires you to implement methods that define a Mongo as well as a MongoTemplate object to the container. AbstractMongoConfiguration also has a method you can override named 'getMappingBasePackage' which tells the configuration where to scan for classes annotated with the @org.springframework.data.document.mongodb.mapping.Document annotation.

Spring's Mongo namespace enables you to easily enable mapping functionality in 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">

  <!-- Default bean name is 'mongo' -->
  <mongo:mongo host="localhost" port="27017"/>

  <!-- by default look for a Mongo object named 'mongo' - default name used for the converter is 'mappingConverter' -->
  <mongo:mapping-converter base-package="com.mycompany.domain"/>

  <!-- set the mapping converter to be used by the MongoTemplate -->
  <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="myCollection" />
    <constructor-arg name="mongoConverter" ref="mappingConverter"/>
  </bean>


</beans
      

This sets up the right objects in the ApplicationContext to perform the full gamut of mapping operations. The base-package property tells it where to scan for classes annotated with the @org.springframework.data.document.mongodb.mapping.Document annotation.

To take full advantage of the object mapping functionality inside the Spring Data/MongoDB support, you should annotate your mapped objects with the @org.springframework.data.document.mongodb.mapping.Document annotation. Although it is not necessary for the mapping framework to have this annotation (your POJOs will be mapped correctly, even without any annotations), it allows the classpath scanner to find and pre-process your domain objects to extract the necessary metadata. If you don't use this annotation, your application will take a slight performance hit the first time you store a domain object because the mapping framework needs to build up its internal metadata model so it knows about the properties of your domain object and how to persist them.

package com.mycompany.domain;

@Document
public class Person {

  @Id
  private ObjectId id;
  @Indexed
  private Integer ssn;
  private String firstName;
  @Indexed
  private String lastName;

}
      

	Important
	The @Id annotation tells the mapper which property you want to use for the MongoDB _id property and the @Indexed annotation tells the mapping framework to call ensureIndex on that property of your document, making searches faster.

@Document
@CompoundIndexes({
		@CompoundIndex(name = "age_idx", def = "{'lastName': 1, 'age': -1}")
})
public class Person<T extends Address> {

	@Id
	private String id;
	@Indexed(unique = true)
	private Integer ssn;
	private String firstName;
	@Indexed
	private String lastName;
	private Integer age;
	@Transient
	private Integer accountTotal;
	@DBRef
	private List<Account> accounts;
	private T address;

	
	public Person(Integer ssn) {
	  this.ssn = ssn;
	}
	
	@PersistenceConstructor
	public Person(Integer ssn, String firstName, String lastName, Integer age, T address) {
		this.ssn = ssn;
		this.firstName = firstName;
		this.lastName = lastName;
		this.age = age;
		this.address = address;
	}

	public String getId() {
		return id;
	}

 // no setter for Id.  (getter is only exposed for some unit testing)

	public Integer getSsn() {
		return ssn;
	}


// other getters/setters ommitted

}

package com.mycompany.domain;

@Document
@CompoundIndexes({
    @CompoundIndex(name = "age_idx", def = "{'lastName': 1, 'age': -1}")
})
public class Person {

  @Id
  private ObjectId id;
  private Integer age;
  private String firstName;
  private String lastName;

}
          

7.2.4. Using DBRefs

The mapping framework doesn't have to store child objects embedded within the document. You can also store them separately and use a DBRef to refer to that document. When the object is loaded from MongoDB, those references will be eagerly resolved and you will get back a mapped object that looks the same as if it had been stored embedded within your master document.

Here's an example of using a DBRef to refer to a specific document that exists independently of the object in which it is referenced (both classes are shown in-line for brevity's sake):

Example 7.5. 

@Document
public class Account {

  @Id
  private ObjectId id;
  private Float total;

}

@Document
public class Person {

  @Id
  private ObjectId id;
  @Indexed
  private Integer ssn;
  @DBRef
  private List<Account> accounts;

}
        

There's no need to use something like @OneToMany because the mapping framework sees that you're wanting a one-to-many relationship because there is a List of objects. When the object is stored in MongoDB, there will be a list of DBRefs rather than the Account objects themselves.

	Important
	The mapping framework does not handle cascading saves. If you change an Account object that is referenced by a Person object, you must save the Account object separately. Calling save on the Person object will not automatically save the Account objects in the property accounts.

7.2.6. Overriding Mapping with explicit Converters

When storing and querying your objects it is convenient to have a MongoConverter instance handle the mapping of all Java types to DBObjects. However, sometimes you may want the MongoConverter's do most of the work but allow you to selectivly handle the conversion for a particular type. To do this, register one or more one or more org.springframework.core.convert.converter.Converter instances with the MongoConverter.

	Note
	Spring 3.0 introduced a core.convert package that provides a general type conversion system. This is described in detail in the Spring reference documentation section entitled Spring 3 Type Conversion.

The setConverters method on SimpleMongoConverter and MappingMongoConverter should be used for this purpose. The method afterMappingMongoConverterCreation in AbstractMongoConfiguration can be overriden to configure a MappingMongoConverter.

Assuming that you have a working JPA application and would like to add some cross-store persistence for MongoDB. What do you have to add to your configuration?

First of all you need to add a dependency on the spring-data-mongodb-cross-store module. Using Maven this is done by adding a dependency to your pom:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

...

    <!-- Spring Data -->
    <dependency>
      <groupId>org.springframework.data</groupId>
      <artifactId>spring-data-mongodb-cross-store</artifactId>
      <version>${spring.data.mongo.version}</version>
    </dependency>


...

</project>

Once this is done we need to enable AspectJ for the project. The cross-store support is implemented using AspectJ aspects so by enabling compile time AspectJ support the cross-store features will become available to your project. In Maven you would add an additional plugin to the <build> section of the pom:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>

...

  <build>
    <plugins>
    
      ...      

      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>aspectj-maven-plugin</artifactId>
        <version>1.0</version>
        <dependencies>
          <!-- NB: You must use Maven 2.0.9 or above or these are ignored (see MNG-2972) -->
          <dependency>
            <groupId>org.aspectj</groupId>
            <artifactId>aspectjrt</artifactId>
            <version>${aspectj.version}</version>
          </dependency>
          <dependency>
            <groupId>org.aspectj</groupId>
            <artifactId>aspectjtools</artifactId>
            <version>${aspectj.version}</version>
          </dependency>
        </dependencies>
        <executions>
          <execution>
            <goals>
              <goal>compile</goal>
              <goal>test-compile</goal>
            </goals>
          </execution>
        </executions>
        <configuration>
          <outxml>true</outxml>
          <aspectLibraries>
            <aspectLibrary>
              <groupId>org.springframework</groupId>
              <artifactId>spring-aspects</artifactId>
            </aspectLibrary>
            <aspectLibrary>
              <groupId>org.springframework.data</groupId>
              <artifactId>spring-data-mongodb-cross-store</artifactId>
            </aspectLibrary>
          </aspectLibraries>
          <source>1.6</source>
          <target>1.6</target>
        </configuration>
      </plugin>

      ...      

    </plugins>
  </build>

...

</project>

Finally, you need to configure your project to use MongoDB and also configure the aspects that are used. The following XML snippet should be added to your application context:

<?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:jdbc="http://www.springframework.org/schema/jdbc"
  xmlns:jpa="http://www.springframework.org/schema/data/jpa"
  xmlns:mongo="http://www.springframework.org/schema/data/mongo"
  xsi:schemaLocation="http://www.springframework.org/schema/data/mongo 
    http://www.springframework.org/schema/data/mongo/spring-mongo.xsd
    http://www.springframework.org/schema/jdbc 
    http://www.springframework.org/schema/jdbc/spring-jdbc-3.0.xsd
    http://www.springframework.org/schema/beans 
    http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
    http://www.springframework.org/schema/data/jpa 
    http://www.springframework.org/schema/data/jpa/spring-jpa-1.0.xsd">

  ...
  
  <!--  Mongo config -->
  <mongo:mongo host="localhost" port="27017"/>

  <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="cross-store"/>
  </bean>

  <bean class="org.springframework.data.document.mongodb.MongoExceptionTranslator"/>

  <!--  Mongo cross-store aspect config -->
  <bean class="org.springframework.data.persistence.document.mongo.MongoDocumentBacking"
        factory-method="aspectOf">
    <property name="changeSetPersister" ref="mongoChangeSetPersister"/>
  </bean>
  <bean id="mongoChangeSetPersister" 
      class="org.springframework.data.persistence.document.mongo.MongoChangeSetPersister">
    <property name="mongoTemplate" ref="mongoTemplate"/>
    <property name="entityManagerFactory" ref="entityManagerFactory"/>
  </bean>

  ...

</beans>

We are assuming that you have a working JPA application so we will only cover the additional steps needed to persist part of your Entity in your Mongo database. First you need to identify the field you want persited. It should be a domain class and follow the general rules for the Mongo mapping support covered in previous chapters. The field you want persisted in MongoDB should be annotated using the @RelatedDocument annotation. That is really all you need to do!. The cross-store aspects take care of the rest. This includes marking the field with @Transient so it won't be persisted using JPA, keeping track of any changes made to the field value and writing them to the database on succesfull transaction completion, loading the document from MongoDB the first time the value is used in your application. Here is an example of a simple Entity that has a field annotated with @RelatedEntity.

@Entity
public class Customer {

  @Id
  @GeneratedValue(strategy = GenerationType.IDENTITY)
  private Long id;
  
  private String firstName;
  
  private String lastName;
  
  @RelatedDocument
  private SurveyInfo surveyInfo;

  // getters and setters omitted

}         

public class SurveyInfo {
  
  private Map<String, String> questionsAndAnswers;

  public SurveyInfo() {
    this.questionsAndAnswers = new HashMap<String, String>();
  }

  public SurveyInfo(Map<String, String> questionsAndAnswers) {
    this.questionsAndAnswers = questionsAndAnswers;
  }

  public Map<String, String> getQuestionsAndAnswers() {
    return questionsAndAnswers;
  }

  public void setQuestionsAndAnswers(Map<String, String> questionsAndAnswers) {
    this.questionsAndAnswers = questionsAndAnswers;
  }

  public SurveyInfo addQuestionAndAnswer(String question, String answer) {
    this.questionsAndAnswers.put(question, answer);
    return this;
  }
}    

Once the SurveyInfo has been set on the Customer object above the MongoTemplate that was configured above is used to save the SurveyInfo along with some metadata about the JPA Entity is stored in a MongoDB collection named after the fully qualified name of the JPA Entity class. The following code:

    Customer customer = new Customer();
    customer.setFirstName("Sven");
    customer.setLastName("Olafsen");
    SurveyInfo surveyInfo = new SurveyInfo()
      .addQuestionAndAnswer("age", "22")
      .addQuestionAndAnswer("married", "Yes")
      .addQuestionAndAnswer("citizenship", "Norwegian");
    customer.setSurveyInfo(surveyInfo);
    customerRepository.save(customer);

Executing the code above results in the following JSON document stored in MongoDB.

{ "_id" : ObjectId( "4d9e8b6e3c55287f87d4b79e" ),
  "_entity_id" : 1,
  "_entity_class" : "org.springframework.data.mongodb.examples.custsvc.domain.Customer",
  "_entity_field_name" : "surveyInfo",
  "questionsAndAnswers" : { "married" : "Yes",
    "age" : "22",
    "citizenship" : "Norwegian" },
  "_entity_field_class" : "org.springframework.data.mongodb.examples.custsvc.domain.SurveyInfo" }

Here is an example configuration

log4j.rootCategory=INFO, stdout

log4j.appender.stdout=org.springframework.data.document.mongodb.log4j.MongoLog4jAppender
log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
log4j.appender.stdout.layout.ConversionPattern=%d %p [%c] - <%m>%n
log4j.appender.stdout.host = localhost 
log4j.appender.stdout.port = 27017
log4j.appender.stdout.database = logs
log4j.appender.stdout.collectionPattern = %X{year}%X{month}
log4j.appender.stdout.applicationId = my.application
log4j.appender.stdout.warnOrHigherWriteConcern = FSYNC_SAFE

log4j.category.org.apache.activemq=ERROR
log4j.category.org.springframework.batch=DEBUG
log4j.category.org.springframework.data.document.mongodb=DEBUG
log4j.category.org.springframework.transaction=INFO

The important configuration to look at aside from host and port is the database and collectionPattern. The variables year, month, day and hour are available for you to use in forming a collection name. This is to support the common convention of grouping log information in a collection that corresponds to a specific time period, for example a collection per day.

There is also an applicationId which is put into the stored message. The document stored from logging as the following keys: level, name, applicationId, timestamp, properties, traceback, and message.

Spring's Mongo namespace enables you to easily enable JMX functionality

<?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"/>

    <!-- by default look for a Mongo object named 'mongo' -->
    <mongo:jmx/>

    <context:mbean-export/>

    <!-- To translate any MongoExceptions thrown in @Repository annotated classes -->
    <context:annotation-config/>

    <bean id="registry" class="org.springframework.remoting.rmi.RmiRegistryFactoryBean" p:port="1099" />

    <!-- Expose JMX over RMI -->
    <bean id="serverConnector" class="org.springframework.jmx.support.ConnectorServerFactoryBean"
        depends-on="registry"
        p:objectName="connector:name=rmi"
        p:serviceUrl="service:jmx:rmi://localhost/jndi/rmi://localhost:1099/myconnector" />

</beans>      

This will expose several MBeans

This is shown below in a screenshot from JConsole