1.0.0.M1
MongoTemplateThe Spring Datastore Document project applies core Spring concepts to the development of solutions using a document style data store. We provide a "template" as a high-level abstraction for storing and querying documents. You will notice similarities to the JDBC support in the Spring Framework.
This document is the reference guide for Spring Data - Document Support. It explains Document module concepts and semantics and the syntax for various stores namespaces.
For an introduction to document stores or Spring, or Spring Data examples, please refer to Chapter 3, Getting Started - this documentation refers only to Spring Data Document Support and assumes the user is familiar with the document stores and Spring concepts.
The Spring Framework is the leading full-stack Java/JEE application framework. It provides a lightweight container and a non-invasive programming model enabled by the use of dependency injection, AOP, and portable service abstractions.
NoSQL storages provide an alternative to classical RDBMS for horizontal scalability and speed. In terms of implementation, Document stores represent one of the most popular types of stores in the NoSQL space.
The Spring Data Document (or DATADOC) framework makes it easy to write Spring applications that use a Document store by eliminating the redundant tasks and boiler place code required for interacting with the store through Spring's excellent infrastructure support.
Spring Data Document 1.x binaries requires JDK level 6.0 and above, and Spring Framework 3.0.x and above.
In terms of document stores, MongoDB preferably version 1.6.5 or later or CouchDB 1.0.1 or later are required.
Learning a new framework is not always straight forward. In this section, we (the Spring Data team) tried to provide, what we think is, an easy to follow guide for starting with Spring Data Document module. Of course, feel free to create your own learning 'path' as you see fit and, if possible, please report back any improvements to the documentation that can help others.
As explained in Chapter 1, Why Spring Data - Document?, Spring Data Document (DATADOC) provides integration between Spring framework and document oriented data stores. Thus, it is important to become acquainted with both of these frameworks (storages or environments depending on how you want to name them). Throughout the DATADOC documentation, each section provides links to resources relevant however, it is best to become familiar with these topics beforehand.
Spring Data uses heavily Spring framework's core functionality, such as the IoC container, resource abstract or AOP infrastructure. While it is not important to know the Spring APIs, understanding the concepts behind them is. At a minimum, the idea behind IoC should be familiar. These being said, the more knowledge one has about the Spring, the faster she will pick up Spring Data Document. Besides the very comprehensive (and sometimes disarming) documentation that explains in detail the Spring Framework, there are a lot of articles, blog entries and books on the matter - take a look at the Spring framework home page for more information. In general, this should be the starting point for developers wanting to try Spring Data Document.
NoSQL stores have taken the storage world by storm. It is a vast domain with a plethora of solutions, terms and patterns (to make things worth even the term itself has multiple meanings). While some of the principles are common, it is crucial that the user is familiar to some degree with the stores supported by DATADOC. The best way to get acquainted to this solutions is to read their documentation and follow their examples - it usually doesn't take more then 5-10 minutes to go through them and if you are coming from an RDMBS-only background many times these exercises can be an eye opener.
The DATADOC project is very young but there are some samples available in the GitHub repository: https://github.com/SpringSource/spring-data-document-examples.
If you encounter issues or you are just looking for an advice, feel free to use one of the links below:
The Spring Data forum is a message board for all Spring Data (not just Document) users to share information and help each other. Note that registration is needed only for posting.
Professional, from-the-source support, with guaranteed response time, is available from SpringSource, the company behind Spring Data and Spring.
For information on the Spring Data source code repository, nightly builds and snapshot artifacts please see the Spring Data home page.
You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Spring Community forums.
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); (1)
T findById(ID primaryKey); (2)
List<T> findAll(); (3)
Page<T> findAll(Pageable pageable); (4)
Long count(); (5)
void delete(T entity); (6)
boolean exists(ID primaryKey); (7)
// … more functionality omitted.
}| (1) | Saves the given entity. |
| (2) | Returns the entity identified by the given id. |
| (3) | Returns all entities. |
| (4) | Returns a page of entities. |
| (5) | Returns the number of entities. |
| (6) | Deletes the given entity. |
| (7) | 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:
Example 4.2. PagingAndSortingRepository
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):
Declare an interface extending the technology specific Repository sub-interface and type it to the domain class it shall handle.
public interface PersonRepository extends JpaRepository<User, Long> { … }Declare query methods on the interface.
List<Person> findByLastname(String lastname);
Setup Spring to create proxy instances for those interfaces.
<?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>
Get the repository instance injected and use it.
public class SomeClient {
@Autowired
private PersonRepoyitory repository;
public void doSomething() {
List<Person> persons = repository.findByLastname("Matthews");
}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.
As a very first step you define a domain class specific repository
interface to start with. It's got to be typed to the domain class and an
ID type so that you get CRUD methods of the
Repository interface tailored to
it.
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:
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 ???.
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.
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.
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.
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);
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.
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.
So now the question is how to create instances and bean definitions for the repository interfaces defined.
The easiest way to do so is by using the Spring namespace that is shipped with each Spring Data module that supports the repository mechanism. Each of those includes a repositories element that allows you to simply define a base packge Spring shall scan for you.
<?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>
In this case we instruct Spring to scan
com.acme.repositories and all it's sub packages for
interfaces extending the appropriate
Repository sub-interface (in this case
JpaRepository). For each interface
found it will register the presistence technology specific
FactoryBean to create the according
proxies that handle invocations of the query methods. Each of these
beans will be registered under a bean name that is derived from the
interface name, so an interface of
UserRepository would be registered
under userRepository. The base-package
attribute allows to use wildcards, so that you can have a pattern of
packages parsed.
By default we will pick up every interface extending the
persistence technology specific
Repository sub-interface located
underneath the configured base package and create a bean instance
for it. However, you might want to gain finer grained control over
which interfaces bean instances get created for. To do this we
support the use of <include-filter /> and
<exclude-filter /> elements inside
<repositories />. The semantics are exactly
equivalent to the elements in Spring's context namespace. For
details see Spring reference documentation on these
elements.
E.g. to exclude certain interfaces from instantiation as repository, you could use the following configuration:
Example 4.5. Using exclude-filter element
<repositories base-package="com.acme.repositories"> <context:exclude-filter type="regex" expression=".*SomeRepository" /> </repositories>
This would exclude all interface ending on
SomeRepository from being
instantiated.
You can also use the repository infrastructure outside of a Spring container usage. You will still need to have some of the Spring libraries on your classpath but you can generally setup repositories programatically as well. The Spring Data modules providing repository support ship a persistence technology specific RepositoryFactory that can be used as follows:
Example 4.6. Standalone usage of repository factory
RepositoryFactorySupport factory = … // Instantiate factory here UserRepository repository = factory.getRepository(UserRepository.class);
Often it is necessary to provide a custom implementation for a few repository methods. Spring Data repositories easily allow provide custom repository code and integrate it with generic CRUD abstraction and query method functionality. To enrich a repository with custom functionality you have to define an interface and an implementation for that functionality first and let the repository interface you provided so far extend that custom interface.
Example 4.7. Interface for custom repository functionality
interface UserRepositoryCustom {
public void someCustomMethod(User user);
}Example 4.8. Implementation of custom repository functionality
class UserRepositoryImpl implements UserRepositoryCustom {
public void someCustomMethod(User user) {
// Your custom implementation
}
}Note that the implementation itself does not depend on Spring Data and can be a regular Spring bean. So you can either use standard dependency injection behaviour to inject references to other beans, take part in aspects and so on.
Example 4.9. Changes to the your basic repository interface
public interface UserRepository extends JpaRepository<User, Long>, UserRepositoryCustom {
// Declare query methods here
}Let your standard repository interface extend the custom one. This makes CRUD and custom functionality available to clients.
If you use namespace configuration the repository infrastructure
tries to autodetect custom implementations by looking up classes in
the package we found a repository using the naming conventions
appending the namespace element's attribute
repository-impl-postfix to the classname. This suffix
defaults to Impl.
Example 4.10. Configuration example
<repositories base-package="com.acme.repository"> <repository id="userRepository" /> </repositories> <repositories base-package="com.acme.repository" repository-impl-postfix="FooBar"> <repository id="userRepository" /> </repositories>
The first configuration example will try to lookup a class
com.acme.repository.UserRepositoryImpl to act
as custom repository implementation, where the second example will try
to lookup
com.acme.repository.UserRepositoryFooBar.
The approach above works perfectly well if your custom implementation uses annotation based configuration and autowring entirely as will be trated as any other Spring bean. If your customly implemented bean needs some special wiring you simply declare the bean and name it after the conventions just descibed. We will then pick up the custom bean by name rather than creating an own instance.
Example 4.11. Manual wiring of custom implementations (I)
<repositories base-package="com.acme.repository"> <repository id="userRepository" /> </repositories> <beans:bean id="userRepositoryImpl" class="…"> <!-- further configuration --> </beans:bean>
This also works if you use automatic repository lookup without
defining single <repository /> elements.
In case you are not in control of the implementation bean name
(e.g. if you wrap a generic repository facade around an existing
repository implementation) you can explicitly tell the
<repository /> element which bean to use as custom
implementation by using the repository-impl-ref
attribute.
Example 4.12. Manual wiring of custom implementations (II)
<repositories base-package="com.acme.repository"> <repository id="userRepository" repository-impl-ref="customRepositoryImplementation" /> </repositories> <bean id="customRepositoryImplementation" class="…"> <!-- further configuration --> </bean>
In other cases you might want to add a single method to all of your repository interfaces. So the approach just shown is not feasible. The first step to achieve this is adding and intermediate interface to declare the shared behaviour
Example 4.13. An interface declaring custom shared behaviour
public interface MyRepository<T, ID extends Serializable>
extends JpaRepository<T, ID> {
void sharedCustomMethod(ID id);
}Now your individual repository interfaces will extend this intermediate interface to include the functionality declared. The second step is to create an implementation of this interface that extends the persistence technology specific repository base class which will act as custom base class for the repository proxies then.
If you're using automatic repository interface detection using
the Spring namespace using the interface just as is will cause Spring
trying to create an instance of
MyRepository. This is of course not
desired as it just acts as indermediate between
Repository and the actual repository
interfaces you want to define for each entity. To exclude an interface
extending Repository from being
instantiated as repository instance annotate it with
@NoRepositoryBean.
Example 4.14. Custom repository base class
public class MyRepositoryImpl<T, ID extends Serializable>
extends SimpleJpaRepository<T, ID> implements MyRepository<T, ID> {
public void sharedCustomMethod(ID id) {
// implementation goes here
}
}The last step to get this implementation used as base class for
Spring Data repositores is replacing the standard
RepositoryFactoryBean with a custom one using a
custom RepositoryFactory that in turn creates
instances of your MyRepositoryImpl class.
Example 4.15. Custom repository factory bean
public class MyRepositoryFactoryBean<T extends JpaRepository<?, ?>
extends JpaRepositoryFactoryBean<T> {
protected RepositoryFactorySupport getRepositoryFactory(…) {
return new MyRepositoryFactory(…);
}
private static class MyRepositoryFactory extends JpaRepositoryFactory{
public MyRepositoryImpl getTargetRepository(…) {
return new MyRepositoryImpl(…);
}
public Class<? extends RepositorySupport> getRepositoryClass() {
return MyRepositoryImpl.class;
}
}
}Finally you can either declare beans of the custom factory
directly or use the factory-class attribute of the Spring
namespace to tell the repository infrastructure to use your custom
factory implementation.
Example 4.16. Using the custom factory with the namespace
<repositories base-package="com.acme.repository" factory-class="com.acme.MyRepositoryFactoryBean" />
This part of the reference documentation explains the core functionality offered by Spring Data Document.
Chapter 5, MongoDB support introduces the MongoDB module feature set.
Chapter 6, Mongo repositories introduces the repository support for MongoDB.
One of the document stores supported by DATADOC is MongoDB. To quote the project home page: “ MongoDB (from "humongous") is a scalable, high-performance, open source, document-oriented database. ”
Spring Data Document provides easy configuration and access to MongoDB from a Spring application. Offers both low-level and high-level abstraction for interacting with the store, freeing the user from infrastructural concerns.
DATADOC requires MongoDB 1.4 while the latest production release (1.6.5 as of this writing) is recommended.
The MongoDB support provides several components:
For most tasks, the higher-level abstractions and support services are the best choice. Note that at any point, one can move between layers - for example, it's very easy to get a hold of the low level connection (org.mongo.DB) to communicate directly with MongoDB.
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.
An example of using Java based bean metadata to register an
instance of a com.mongodb.Mongo is shown
below
Example 5.1. Registering a com.mongodb.Mongo object using Java based bean metadata
@Configuration
public class AppConfig {
/*
* Factory bean that creates the com.mongodb.Mongo instance
*/
public @Bean Mongo mongo() throws UnknownHostException, MongoException {
return new Mongo("localhost");
}
}
This approach allows you to use the standard com.mongodb.Mongo API that you may already be used to using but also pollutes the code with the UnknownHostException checked exception.
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:
Example 5.2. 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 com.mongodb.Mongo instance
*/
public @Bean MongoFactoryBean mongo() {
MongoFactoryBean mongo = new MongoFactoryBean();
mongo.setHost("localhost");
return mongo;
}
/*
* Use this post processor to translate any MongoExceptions thrown in @Repository
* annotated classes
*/
public @Bean PersistenceExceptionTranslationPostProcessor
persistenceExceptionTranslationPostProcessor() {
return new PersistenceExceptionTranslationPostProcessor();
}
}
if you prefer to use the standard MongoDB API to create a
com.mongodb.Mongo instance and have exception translation enabled on
your @Repository instances, simply inherit from
MongoExceptionTranslationConfig as shown
below.
Example 5.3. 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");
}
}
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 configuration of replica 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:
Example 5.4. XML schema 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
Example 5.5. XML schema 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:
Example 5.6. XML schema to configure replica sets in MongoDB
<beans>
<mongo:mongo>
<! replica set TBD -- should be available for release 1.0.0.M2 -->
<mongo:mongo>
</beans>
Most users are likely to use MongoTemplate
and its corresponding package
org.springframework.data.document.mongodb - the
template is in fact the central class of the MongoDB module due to its
rich feature set. The template offers convenience methods and automatic
mapping between MongoDB JSON documents and your domain classes. Out of the
box, MongoTemplate uses a Java-based default
converter but you can also write your own converter classes to be used for
reading and storing domain objects.
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 in the context of the Spring
container.
In Java based configuration using the driver's com.mongodb.Mongo object
Example 5.7. 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
Example 5.8. Registering a com.mongodb.Mongo object and enabling Spring's exception translation support
@Configuration
public class AppConfig {
/*
* The method argument is the container managed Mongo instance created by the mongo() method
*/
public @Bean MongoTemplate mongoTemplate(Mongo mongo) {
MongoTemplate mongoTemplate = new MongoTemplate(mongo, "test", "HelloMongo");
return mongoTemplate;
}
/*
* Factory bean that creates the Mongo instance
*/
public @Bean MongoFactoryBean mongo() {
MongoFactoryBean mongo = new MongoFactoryBean();
mongo.setHost("localhost");
return mongo;
}
/*
* Use this post processor to translate any MongoExceptions thrown in @Repository
* annotated classes
*/
public @Bean PersistenceExceptionTranslationPostProcessor
persistenceExceptionTranslationPostProcessor() {
return new PersistenceExceptionTranslationPostProcessor();
}
}
There are several overloaded constructors of MongoTemplate. These are
MongoTemplate(Mongo mongo, String
databaseName) - takes the default database name to
operate against
MongoTemplate(Mongo mongo, String
databaseName, String defaultCollectionName) - adds the
default collection name to operate against.
MongoTemplate(Mongo mongo, String
databaseName, String defaultCollectionName, MongoConverter
mongoConverter) - override with a provided
MongoConverter. Default is SimpleMongoConverter
MongoTemplate(Mongo mongo, String
databaseName, String defaultCollectionName, MongoConverter
mongoConverter, WriteConcern writeConcern, WriteResultChecking
writeResultChecking) - Specify a default WriteConcern
and also WriteResultChecking policy
MongoTemplate(Mongo mongo, String
databaseName, String defaultCollectionName, WriteConcern
writeConcern, WriteResultChecking writeResultChecking)-
Specify a default WriteConcern and also WriteResultChecking
policy
MongoTemplate(Mongo mongo, String
databaseName, WriteConcern writeConcern, WriteResultChecking
writeResultChecking)- Specify a default WriteConcern and
also WriteResultChecking policy
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.
The public methods for MongoTemplate are
defined by the interface MongoOperations.
They can be grouped into the following categories:
Set<String> getCollectionNames() A
set of collection names.
boolean collectionExists(String
collectionName) Check to see if a collection with a
given name exists.
DBCollection createCollection(String
collectionName) Create an uncapped collection with the
provided name.
DBCollection createCollection(String
collectionName, CollectionOptions collectionOptions)
Create a collect with the provided name and options.
void dropCollection(String
collectionName) Drop the collection with the given
name.
DBCollection getCollection(String
collectionName) Get a collection by name, creating it
if it doesn't exist.
DBCollection getDefaultCollection()
The default collection used by this template.
String getDefaultCollectionName()
The default collection name used by this template.
CommandResult executeCommand(DBObject
command) Execute a MongoDB command.
CommandResult executeCommand(String
jsonCommand) Execute the a MongoDB command expressed
as a JSON string.
<T> T execute(CollectionCallback<T>
action) Executes the given CollectionCallback on the
default collection.
<T> T execute(String collectionName,
CollectionCallback<T> action) Executes the given
CollectionCallback on the collection of the given name.update
using the $addToSet update modifier
<T> T execute(DbCallback<T>
action) Executes a DbCallback translating any
exceptions as necessary.
<T> T executeInSession(DbCallback<T>
action) Executes the given DbCallback within the same
connection to the database so as to ensure consistency in a
write heavy environment where you may read the data that you
wrote.
void ensureIndex(IndexDefinition
indexDefintion) Ensure that an index for the provided
IndexDefinition exists for the default collection.
void ensureIndex(String
collectionName, IndexDefinition indexSpecification)
Ensure that an index for the provided IndexDefinition
exists.
void insert(Object
objectToSave) Insert the object into the default
collection.
void insert(String collectionName,
Object objectToSave) Insert the object into the
specified collection.
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 insert(T objectToSave,
MongoWriter<T> writer) Insert the object into
the default collection.
<T> void insert(String collectionName, T
objectToSave, MongoWriter<T> writer) Insert the
object into the specified collection.
<T> void insertList(List<? extends
T> listToSave, MongoWriter<T> writer) Insert
a list of objects into the default collection using the provided
MongoWriter instance
<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
<T> List<T> getCollection(Class<T>
targetClass) Query for a list of objects of type T
from the default collection.
<T> List<T> getCollection(String
collectionName, Class<T> targetClass) Query for
a list of objects of type T from the specified
collection.
<T> List<T> getCollection(String
collectionName, Class<T> targetClass, MongoReader<T>
reader) Query for a list of objects of type T from the
specified collection, mapping the DBObject using the provided
MongoReader.
<T> T findOne(Query query,
Class<T> targetClass) Map the results of an
ad-hoc query on the default MongoDB collection to a single
instance of an object of the specified type.
<T> T findOne(Query query,
Class<T> targetClass, MongoReader<T>
reader) Map the results of an ad-hoc query on the
default MongoDB collection to a single instance of an object of
the specified type.
<T> T findOne(String collectionName,
Query query, Class<T> targetClass) Map the
results of an ad-hoc query on the specified collection to a
single instance of an object of the specified type.
<T> T findOne(String collectionName,
Query query, Class<T> targetClass, MongoReader<T>
reader) Map the results of an ad-hoc query on the
specified collection to a single instance of an object of the
specified type.
<T> List<T> find(Query query, Class<T>
targetClass) Map the results of an ad-hoc query on the
default MongoDB collection to a List of the specified
type.
<T> List<T> find(Query query, Class<T>
targetClass, MongoReader<T> reader) Map the
results of an ad-hoc query on the default MongoDB collection to
a List of the specified type.
<T> List<T> find(String collectionName,
Query query, Class<T> targetClass) Map the
results of an ad-hoc query on the specified collection to a List
of the specified type.
<T> List<T> find(String collectionName,
Query query, Class<T> targetClass, CursorPreparer
preparer) Map the results of an ad-hoc query on the
specified collection to a List of the specified type.
<T> List<T> find(String collectionName,
Query query, Class<T> targetClass, MongoReader<T>
reader) Map the results of an ad-hoc query on the
specified collection to a List of the specified type.
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.
void remove(Query query)
Remove all documents from the default collection that match the
provided query document criteria.
void remove(String collectionName,
Query query) Remove all documents from the specified
collection that match the provided query document
criteria.
WriteResult updateFirst(Query query, Update
update) Updates the first object that is found in the
default collection that matches the query document with the
provided updated document.
WriteResult updateFirst(String
collectionName, Query query, Update update) Updates
the first object that is found in the specified collection that
matches the query document criteria with the provided updated
document.
WriteResult updateMulti(Query query, Update
update) Updates all objects that are found in the
default collection that matches the query document criteria with
the provided updated document.
WriteResult updateMulti(String
collectionName, Query query, Update update) Updates
all objects that are found in the specified collection that
matches the query document criteria with the provided updated
document.
It's time to look at some code examples showing how to use the
MongoTemplate. First we look at creating our
first collection.
Example 5.9. Working with collections using the MongoTemplate
DBCollection collection = null;
if (!mongoTemplate.getCollectionNames().contains("MyNewCollection")) {
collection = mongoTemplate.createCollection("MyNewCollection");
}
mongoTemplate.dropCollection("MyNewCollection");
We can create an index on a collection to improve query performance.
Example 5.10. Creating an index using the MongoTemplate
mongoTemplate.ensureIndex("MyCollection", new Index().on("name", Order.ASCENDING));
Once we have created the collection and maybe an index we can
start using the collection to store our domain objects as documents.
Note that we are using a static import for
org.springframework.data.document.mongodb.query.Criteria.where
to make the query more readable.
Example 5.11. Inserting and retrieving documents using the MongoTemplate
import static org.springframework.data.document.mongodb.query.Criteria.where;
...
Person p = new Person("Bob", 33);
mongoTemplate.insert("MyCollection", p);
Person qp = mongoTemplate.findOne("MyCollection",
new Query(where("id").is(p.getId())), Person.class);
We saw how to retrieve a single document. We can also query for a collection of documents to be returned as domain objects in a list. Assuming that we have a number of Person objects with name and age stored as documents in a collection and that each person has an embedded account document with a balance. We can now run a query using the following code.
Example 5.12. Querying for documents using the MongoTemplate
import static org.springframework.data.document.mongodb.query.Criteria.where;
...
List<Person> result = mongoTemplate.find(
new Query(where("age").lt(50)).and(where("accounts.balance").gt(1000.00d)),
Person.class);
All find methods take a Query object as a
parameter. This object defines the criteria and options used to perform
the query. The criteria is specified using a
Criteria object that has a static factory method
named where used to instantiate a new
Criteria object. We recommend using a static
import for
org.springframework.data.document.mongodb.query.Criteria.where
to make the query more readable.
This query should return a list of Person objects that meet the specified criteria. The Criteria class has the following methods that correspond to the operators provided in MongoDB.
As you can see most methods return the
Criteria object to provide a fluent style for the
API.
Criteria all(Object o) Creates
a criterion using the $all operator
Criteria exists(boolean b)
Creates a criterion using the
$exists operator
Criteria gt(Object o) Creates a
criterion using the $gt operator
Criteria gte(Object o) Creates
a criterion using the $gte operator
Criteria in(Object... o)
Creates a criterion using the $in
operator
Criteria is(Object o) Creates a
criterion using the $is operator
Criteria lt(Object o) Creates a
criterion using the $lt operator
Criteria lte(Object o) Creates
a criterion using the $lte operator
Criteriamod(Number value, Number
remainder) Creates a criterion using the
$mod operator
Criteria nin(Object... o)
Creates a criterion using the $nin
operator
Criteria not() Creates a
criterion using the $not meta operator which
affects the clause directly following
Criteria regex(String re)
Creates a criterion using a
$regex
Criteria size(int s) Creates a
criterion using the $size operator
Criteria type(int t) Creates a
criterion using the $type operator
void or(List<Query> queries)
Creates an or query using the $or
operator for all of the provided queries
The Query class has some additional methods
used to provide options for the query.
Query and(Criteria criteria)
used to add additional criteria to the query
Field fields() used to
define fields to be included in the query results
Query limit(int limit) used
to limit the size of the returned results to the provided limit
(used for paging)
Query skip(int skip) used to
skip the provided number of documents in the results (used for
paging)
Sort sort() used to provide
sort definition for the results
For updates we can elect to update the first document found using
updateFirst or we can update all documents that were
found to match the query using updateMulti. Here is
an example of an update of all SAVINGS accounts where we are adding a
one time $50.00 bonus to the balance using the $inc
operator.
Example 5.13. Updating documents using the MongoTemplate
import static org.springframework.data.document.mongodb.query.Criteria.where;
...
WriteResult wr = mongoTemplate.updateMulti(
new Query(where("accounts.accountType").is(Account.Type.SAVINGS)),
new Update().inc("accounts.$.balance", 50.00));
In addition to the Query discussed above we
provide the update definition using an Update
object. The Update class has methods that match
the update modifiers available for MongoDB.
As you can see most methods return the
Update object to provide a fluent style for the
API.
Update addToSet(String key, Object
value) Update using the $addToSet
update modifier
Update inc(String key, Number
inc) Update using the $inc update
modifier
Update pop(String key, Update.Position
pos) Update using the $pop update
modifier
Update pull(String key, Object
value) Update using the $pull
update modifier
Update pullAll(String key, Object[]
values) Update using the $pullAll
update modifier
Update push(String key, Object
value) Update using the $push
update modifier
Update pushAll(String key, Object[]
values) Update using the $pushAll
update modifier
Update rename(String oldName, String
newName) Update using the $rename
update modifier
Update set(String key, Object
value) Update using the $set update
modifier
Update unset(String key)
Update using the $unset update
modifier
The Spring Data Document projects MongoDB support is in its early stages. We are interested in feedback, knowing what your use cases are, what are the common patters you encounter so that the MongoDB module better serves your needs. Do contact us using the channels mentioned above, we are interested in hearing from you!
Abstract
This chapter will point out the specialties for repository support for MongoDB. This builds on the core repository support explained in Chapter 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:
Example 6.1. Sample Person entity
public class Person {
private ObjectId id;
private String firstname;
private String lastname;
// … getters and setters omitted
}We have a quite simple domain object here. Note that it has a property
named id of type ObjectId. The default
serialization mechanism used in MongoTemplate (which
is backing the repository support) regards properties named id as document
id. Currently we support String,
ObjectId and BigInteger as
id-types.
Example 6.2. Basic repository interface to persist Person entities
public interface PersonRepository extends MongoRepository<Person, Long> {
}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
Example 6.3. General mongo repository Spring configuration
<?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: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 in Example 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:
Example 6.4. Paging access to Person entities
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration
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
Example 6.5. PersonRepository with query methods
public interface PersonRepository extends MongoRepository<Person, Long> {
List<Person> findByLastname(String lastname);
Page<Person> findByFirstname(String firstname, Pageable pageable);
}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.
Table 6.1. Supported keywords for query methods
| Keyword | Sample | Logical result |
|---|---|---|
GreaterThan | findByAgeGreaterThan(int
age) | {"age" : {"$gt" : age}} |
LessThan | findByAgeLessThan(int
age) | {"age" : {"$lt" : age}} |
Between | findByAgeBetween(int from, int
to) | {"age" : {"$gt" : from, "$lt" : to}} |
IsNotNull,
NotNull | findByFirstnameNotNull() | {"age" : {"$ne" : null}} |
IsNull,
Null | findByFirstnameNull() | {"age" : null} |
Like | findByFirstnameLike(String
name) | {"age" : age} (age as
regex) |
| (No keyword) | findByFirstname(String
name) | {"age" : name} |
Not | findByFirstnameNot(String
name) | {"age" : {"$ne" : name}} |