Introduction
In this tutorial we will refactor an existing Spring MVC 3 - MongoDB application (see
here) to use the newly released
Spring Data Document 1.0.0.M1 for MongoDB. Our purpose here is to realize how Spring Data simplifies integration development with MongoDB. To appreciate Spring Data, it is advisable to know how to perform basic CRUD functions with native MongoDB support. And that's the reason why we'll be refactoring an existing
Spring MVC 3 - MongoDB application.
Note: An updated version of this tutorial is now accessible at Spring MVC 3.1 - Implement CRUD with Spring Data MongoDB (Part 1)
What is MongoDB?
MongoDB (from "humongous") is a scalable, high-performance, open source, document-oriented database. Written in C++, MongoDB features:
- Document-oriented storage
- Full Index Support
- Replication & High Availability
- Scale horizontally without compromising functionality.
- Rich, document-based queries.
- Atomic modifiers for contention-free performance.
- Flexible aggregation and data processing.
- Store files of any size without complicating your stack.
- Enterprise class support, training, and consulting available.
Source: http://www.mongodb.org/
What is Spring Data - Document?
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.
Source: Spring Datastore Document - Reference Documentation
In a nutshell MongoDB uses JSON instead of SQL There's no static schema to create. All schemas are dynamic, meaning you create them on-the-fly. You can try a real-time online shell for MongoDB at http://try.mongodb.org/. Visit the official MongoDB site for a thorough discussion.
Prerequisites
In order to complete this tutorial, you will be required to install a copy of MongoDB. If you don't have one yet, grab a copy now by visiting http://www.mongodb.org/display/DOCS/Quickstart. Installation is really easy.
Development
Our application is a simple CRUD system for managing a list of Persons. Data is stored in MongoDB database. We'll start by declaring our domain objects. Then we'll discuss the service layer. And lastly we'll add the controllers.
The Domain Layer
Our application contains a single domain object named
Person. It consists the following properties:
pid
firstName
lastName
money
Here's the class declaration:
Person.java
package org.krams.tutorial.domain;
import java.io.Serializable;
/**
* A simple POJO representing a Person
*
* @author Krams at {@link http://krams915@blogspot.com}
*/
public class Person implements Serializable {
private static final long serialVersionUID = -5527566248002296042L;
private String pid;
private String firstName;
private String lastName;
private Double money;
public String getPid() {
return pid;
}
public void setPid(String pid) {
this.pid = pid;
}
public String getFirstName() {
return firstName;
}
public void setFirstName(String firstName) {
this.firstName = firstName;
}
public String getLastName() {
return lastName;
}
public void setLastName(String lastName) {
this.lastName = lastName;
}
public Double getMoney() {
return money;
}
public void setMoney(Double money) {
this.money = money;
}
}Warning!
In the original tutorial we used
id to signify the primary identity of the Person. But in this tutorial we used
pid instead. This is because when we use
id with Spring Data, it messes up the
id property by merging it with the built-in
_id property of MongoDB.
For now, if you plan to use Spring Data, don't use
id as your id field. Choose a different name instead. I have filed already an inquiry about this behavior in the Spring forums. See it
here.
The Service Layer
Our service class contains the main changes in the original application. Instead of calling native MongoDB methods for performing CRUD operations, we use Spring Data's
MongoTemplate instead.
What is MongoTemplate?
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.
Source: Spring Datastore Document - Reference Documentation
Here's the class declaration:
PersonService.java
package org.krams.tutorial.service;
import java.util.List;
import java.util.UUID;
import javax.annotation.Resource;
import org.apache.log4j.Logger;
import org.krams.tutorial.domain.Person;
import org.springframework.data.document.mongodb.MongoTemplate;
import org.springframework.data.document.mongodb.query.Query;
import org.springframework.data.document.mongodb.query.Update;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import static org.springframework.data.document.mongodb.query.Criteria.where;
/**
* Service for processing {@link Person} objects.
* Uses Spring's {@link MongoTemplate} to perform CRUD operations.
* <p>
* For a complete reference to MongoDB
* see http://www.mongodb.org/
* <p>
* For a complete reference to Spring Data MongoDB
* see http://www.springsource.org/spring-data
*
* @author Krams at {@link http://krams915@blogspot.com}
*/
@Service("personService")
@Transactional
public class PersonService {
protected static Logger logger = Logger.getLogger("service");
@Resource(name="mongoTemplate")
private MongoTemplate mongoTemplate;
/**
* Retrieves all persons
*/
public List<Person> getAll() {
logger.debug("Retrieving all persons");
// Find an entry where pid property exists
Query query = new Query(where("pid").exists(true));
// Execute the query and find all matching entries
List<Person> persons = mongoTemplate.find(query, Person.class);
return persons;
}
/**
* Retrieves a single person
*/
public Person get( String id ) {
logger.debug("Retrieving an existing person");
// Find an entry where pid matches the id
Query query = new Query(where("pid").is(id));
// Execute the query and find one matching entry
Person person = mongoTemplate.findOne("mycollection", query, Person.class);
return person;
}
/**
* Adds a new person
*/
public Boolean add(Person person) {
logger.debug("Adding a new user");
try {
// Set a new value to the pid property first since it's blank
person.setPid(UUID.randomUUID().toString());
// Insert to db
mongoTemplate.insert("mycollection", person);
return true;
} catch (Exception e) {
logger.error("An error has occurred while trying to add new user", e);
return false;
}
}
/**
* Deletes an existing person
*/
public Boolean delete(String id) {
logger.debug("Deleting existing person");
try {
// Find an entry where pid matches the id
Query query = new Query(where("pid").is(id));
// Run the query and delete the entry
mongoTemplate.remove(query);
return true;
} catch (Exception e) {
logger.error("An error has occurred while trying to delete new user", e);
return false;
}
}
/**
* Edits an existing person
*/
public Boolean edit(Person person) {
logger.debug("Editing existing person");
try {
// Find an entry where pid matches the id
Query query = new Query(where("pid").is(person.getPid()));
// Declare an Update object.
// This matches the update modifiers available in MongoDB
Update update = new Update();
update.set("firstName", person.getFirstName());
mongoTemplate.updateMulti(query, update);
update.set("lastName", person.getLastName());
mongoTemplate.updateMulti(query, update);
update.set("money", person.getMoney());
mongoTemplate.updateMulti(query, update);
return true;
} catch (Exception e) {
logger.error("An error has occurred while trying to edit existing user", e);
return false;
}
}
}The code should should be self-explanatory. Notice how Spring Data has reduced the amount of code. To appreciate this difference, let's do a comparison between using the traditional MongoDB and using Spring Data.
Retrieving all entries
old implementation
public List<person> getAll() {
logger.debug("Retrieving all persons");
// Retrieve collection
DBCollection coll = MongoDBFactory.getCollection("mydb","mycollection");
// Retrieve cursor for iterating records
DBCursor cur = coll.find();
// Create new list
List<person> items = new ArrayList<person>();
// Iterate cursor
while(cur.hasNext()) {
// Map DBOject to Person
DBObject dbObject = cur.next();
Person person = new Person();
person.setId(dbObject.get("id").toString());
person.setFirstName(dbObject.get("firstName").toString());
person.setLastName(dbObject.get("lastName").toString());
person.setMoney(Double.valueOf(dbObject.get("money").toString()));
// Add to new list
items.add(person);
}
// Return list
return items;
}
new implementation
public List<Person> getAll() {
logger.debug("Retrieving all persons");
Query query = new Query(where("pid").exists(true));
List<Person> persons = mongoTemplate.find(query, Person.class);
return persons;
}
Retrieving a single entry
old implementation
public Person get( String id ) {
logger.debug("Retrieving an existing person");
// Retrieve collection
DBCollection coll = MongoDBFactory.getCollection("mydb","mycollection");
// Create a new object
DBObject doc = new BasicDBObject();
// Put id to search
doc.put("id", id);
// Find and return the person with the given id
DBObject dbObject = coll.findOne(doc);
// Map DBOject to Person
Person person = new Person();
person.setId(dbObject.get("id").toString());
person.setFirstName(dbObject.get("firstName").toString());
person.setLastName(dbObject.get("lastName").toString());
person.setMoney(Double.valueOf(dbObject.get("money").toString()));
// Return person
return person;
}
new implementation
public Person get( String id ) {
logger.debug("Retrieving an existing person");
// Find an entry where pid matches the id
Query query = new Query(where("pid").is(id));
// Execute the query and find one matching entry
Person person = mongoTemplate.findOne("mycollection", query, Person.class);
return person;
}
Adding a new entry
old implementation
public Boolean add(Person person) {
logger.debug("Adding a new user");
try {
// Retrieve collection
DBCollection coll = MongoDBFactory.getCollection("mydb","mycollection");
// Create a new object
BasicDBObject doc = new BasicDBObject();
// Generate random id using UUID type 4
// See http://en.wikipedia.org/wiki/Universally_unique_identifier
doc.put("id", UUID.randomUUID().toString() );
doc.put("firstName", person.getFirstName());
doc.put("lastName", person.getLastName());
doc.put("money", person.getMoney());
// Save new person
coll.insert(doc);
return true;
} catch (Exception e) {
logger.error("An error has occurred while trying to add new user", e);
return false;
}
}
new implementation
public Boolean add(Person person) {
logger.debug("Adding a new user");
try {
// Set a new value to the pid property first since it's blank
person.setPid(UUID.randomUUID().toString());
// Insert to db
mongoTemplate.insert("mycollection", person);
return true;
} catch (Exception e) {
logger.error("An error has occurred while trying to add new user", e);
return false;
}
}
Deleting an entry
old implementation
public Boolean delete(String id) {
logger.debug("Deleting existing person");
try {
// Retrieve person to delete
BasicDBObject item = (BasicDBObject) getDBObject( id );
// Retrieve collection
DBCollection coll = MongoDBFactory.getCollection("mydb","mycollection");
// Delete retrieved person
coll.remove(item);
return true;
} catch (Exception e) {
logger.error("An error has occurred while trying to delete new user", e);
return false;
}
}
new implementation
public Boolean delete(String id) {
logger.debug("Deleting existing person");
try {
// Find an entry where pid matches the id
Query query = new Query(where("pid").is(id));
// Run the query and delete the entry
mongoTemplate.remove(query);
return true;
} catch (Exception e) {
logger.error("An error has occurred while trying to delete new user", e);
return false;
}
}
Updating an entry
old implementation
public Boolean edit(Person person) {
logger.debug("Editing existing person");
try {
// Retrieve person to edit
BasicDBObject existing = (BasicDBObject) getDBObject( person.getId() );
DBCollection coll = MongoDBFactory.getCollection("mydb","mycollection");
// Create new object
BasicDBObject edited = new BasicDBObject();
// Assign existing details
edited.put("id", person.getId());
edited.put("firstName", person.getFirstName());
edited.put("lastName", person.getLastName());
edited.put("money", person.getMoney());
// Update existing person
coll.update(existing, edited);
return true;
} catch (Exception e) {
logger.error("An error has occurred while trying to edit existing user", e);
return false;
}
}
new implementation
public Boolean edit(Person person) {
logger.debug("Editing existing person");
try {
// Find an entry where pid matches the id
Query query = new Query(where("pid").is(person.getPid()));
// Declare an Update object.
// This matches the update modifiers available in MongoDB
Update update = new Update();
update.set("firstName", person.getFirstName());
mongoTemplate.updateMulti(query, update);
update.set("lastName", person.getLastName());
mongoTemplate.updateMulti(query, update);
update.set("money", person.getMoney());
mongoTemplate.updateMulti(query, update);
return true;
} catch (Exception e) {
logger.error("An error has occurred while trying to edit existing user", e);
return false;
}
}
Configuration
To use Spring's
MongoTemplate it needs to be declared via configuration. It also needs a reference to a MongoDB database. Let's declare an XML configuration that satifies these requirements:
mongo-config.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:p="http://www.springframework.org/schema/p"
xmlns:mongo="http://www.springframework.org/schema/data/mongo"
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">
<!-- Default bean name is 'mongo' -->
<mongo:mongo host="localhost" port="27017"/>
<!-- Offers convenience methods and automatic mapping between MongoDB JSON documents and your domain classes. -->
<bean id="mongoTemplate" class="org.springframework.data.document.mongodb.MongoTemplate">
<constructor-arg ref="mongo"/>
<constructor-arg value="mydb"/>
<constructor-arg value="mycollection"/>
</bean>
<bean id="initService" class="org.krams.tutorial.service.InitService" init-method="init"></bean>
</beans>Notice we're using the mongo namespace:
xmlns:mongo="http://www.springframework.org/schema/data/mongo"
We've declared a reference to a MongoDB database by declaring:
<mongo:mongo host="localhost" port="27017"/>
Then we declared a
MongoTemplate that references a MongoDB database (mongo), a database (mydb), and a collection (mycollection):
<bean id="mongoTemplate" class="org.springframework.data.document.mongodb.MongoTemplate">
<constructor-arg ref="mongo"/>
<constructor-arg value="mydb"/>
<constructor-arg value="mycollection"/>
</bean>
Lastly, we declared an
initService
<bean id="initService" class="org.krams.tutorial.service.InitService" init-method="init"></bean>
The purpose of the
initService is to prepopulate our MongoDB with sample data.
Here's the class declaration:
InitService.java
package org.krams.tutorial.service;
import java.util.UUID;
import javax.annotation.Resource;
import org.apache.log4j.Logger;
import org.krams.tutorial.domain.Person;
import org.springframework.data.document.mongodb.MongoTemplate;
import org.springframework.transaction.annotation.Transactional;
/**
* Service for initializing MongoDB with sample data
* <p>
* For a complete reference to MongoDB
* see http://www.mongodb.org/
* <p>
* For transactions, see http://static.springsource.org/spring/docs/3.0.x/spring-framework-reference/html/transaction.html
*
* @author Krams at {@link http://krams915@blogspot.com}
*/
@Transactional
public class InitService {
protected static Logger logger = Logger.getLogger("service");
@Resource(name="mongoTemplate")
private MongoTemplate mongoTemplate;
private void init() {
// Populate our MongoDB database
logger.debug("Init MongoDB users");
// Drop existing collection
mongoTemplate.dropCollection("mycollection");
// Create new object
Person p = new Person ();
p.setPid(UUID.randomUUID().toString());
p.setFirstName("John");
p.setLastName("Smith");
p.setMoney(1000.0);
// Insert to db
mongoTemplate.insert("mycollection", p);
// Create new object
p = new Person ();
p.setPid(UUID.randomUUID().toString());
p.setFirstName("Jane");
p.setLastName("Adams");
p.setMoney(2000.0);
// Insert to db
mongoTemplate.insert("mycollection", p);
// Create new object
p = new Person ();
p.setPid(UUID.randomUUID().toString());
p.setFirstName("Jeff");
p.setLastName("Mayer");
p.setMoney(3000.0);
// Insert to db
mongoTemplate.insert("mycollection", p);
}
}
The Controller Layer
After creating the domain and service classes, we need to declare a controller that will handle the web requests.
MainController.java
package org.krams.tutorial.controller;
import java.util.List;
import javax.annotation.Resource;
import org.apache.log4j.Logger;
import org.krams.tutorial.domain.Person;
import org.krams.tutorial.service.PersonService;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.ModelAttribute;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
/**
* Handles and retrieves person request
*
* @author Krams at {@link http://krams915@blogspot.com}
*/
@Controller
@RequestMapping("/main")
public class MainController {
protected static Logger logger = Logger.getLogger("controller");
@Resource(name="personService")
private PersonService personService;
/**
* Handles and retrieves all persons and show it in a JSP page
*
* @return the name of the JSP page
*/
@RequestMapping(value = "/persons", method = RequestMethod.GET)
public String getPersons(Model model) {
logger.debug("Received request to show all persons");
// Retrieve all persons by delegating the call to PersonService
List persons = personService.getAll();
// Attach persons to the Model
model.addAttribute("persons", persons);
// This will resolve to /WEB-INF/jsp/personspage.jsp
return "personspage";
}
/**
* Retrieves the add page
*
* @return the name of the JSP page
*/
@RequestMapping(value = "/persons/add", method = RequestMethod.GET)
public String getAdd(Model model) {
logger.debug("Received request to show add page");
// Create new Person and add to model
// This is the formBackingOBject
model.addAttribute("personAttribute", new Person());
// This will resolve to /WEB-INF/jsp/addpage.jsp
return "addpage";
}
/**
* Adds a new person by delegating the processing to PersonService.
* Displays a confirmation JSP page
*
* @return the name of the JSP page
*/
@RequestMapping(value = "/persons/add", method = RequestMethod.POST)
public String add(@ModelAttribute("personAttribute") Person person) {
logger.debug("Received request to add new person");
// The "personAttribute" model has been passed to the controller from the JSP
// We use the name "personAttribute" because the JSP uses that name
// Call PersonService to do the actual adding
personService.add(person);
// This will resolve to /WEB-INF/jsp/addedpage.jsp
return "addedpage";
}
/**
* Deletes an existing person by delegating the processing to PersonService.
* Displays a confirmation JSP page
*
* @return the name of the JSP page
*/
@RequestMapping(value = "/persons/delete", method = RequestMethod.GET)
public String delete(@RequestParam(value="pid", required=true) String id,
Model model) {
logger.debug("Received request to delete existing person");
// Call PersonService to do the actual deleting
personService.delete(id);
// Add id reference to Model
model.addAttribute("pid", id);
// This will resolve to /WEB-INF/jsp/deletedpage.jsp
return "deletedpage";
}
/**
* Retrieves the edit page
*
* @return the name of the JSP page
*/
@RequestMapping(value = "/persons/edit", method = RequestMethod.GET)
public String getEdit(@RequestParam(value="pid", required=true) String id,
Model model) {
logger.debug("Received request to show edit page");
// Retrieve existing Person and add to model
// This is the formBackingOBject
model.addAttribute("personAttribute", personService.get(id));
// This will resolve to /WEB-INF/jsp/editpage.jsp
return "editpage";
}
/**
* Edits an existing person by delegating the processing to PersonService.
* Displays a confirmation JSP page
*
* @return the name of the JSP page
*/
@RequestMapping(value = "/persons/edit", method = RequestMethod.POST)
public String saveEdit(@ModelAttribute("personAttribute") Person person,
@RequestParam(value="pid", required=true) String id,
Model model) {
logger.debug("Received request to update person");
// The "personAttribute" model has been passed to the controller from the JSP
// We use the name "personAttribute" because the JSP uses that name
// We manually assign the id because we disabled it in the JSP page
// When a field is disabled it will not be included in the ModelAttribute
person.setPid(id);
// Delegate to PersonService for editing
personService.edit(person);
// Add id reference to Model
model.addAttribute("pid", id);
// This will resolve to /WEB-INF/jsp/editedpage.jsp
return "editedpage";
}
}Our controller is a simple class that delegates actual processing to
PersonService. When the service is done processing, the controller forwards the result to a JSP view.
Other Configurations and Files
To make the tutorial manageable, I've decided not to post the following configuration files in this tutorial:
web.xml
spring-servlet.xml
applicationContext.xml
These files are standard Spring MVC related configuration files. You can find them in the downloadable application at the end of this tutorial.
I have also left out the JSP declarations. You can find a description of them in the following tutorial:
Spring MVC 3: Using a Document-Oriented Database - MongoDB
Run the Application
To run the application, open your browser and enter the following URL:
http://localhost:8080/spring-data-mongodb/krams/main/persons
You should see the following CRUD view:
Conclusion
That's it. We have successfully refactored our existing Spring MVC 3 - MongoDB application to use the newly released Spring Data Document 1.0 for MongoDB. We've compared side-by-side between the native MongoDB development and with the new Spring Data framework. We have seen how Spring Data has simplified our development further.
Download the project
You can access the project site at Google's Project Hosting at
http://code.google.com/p/spring-mvc-mongodb/
You can download the project as a Maven build. Look for the
spring-data-mongodb.zip in the Download sections.
You can run the project directly using an embedded server via Maven.
For Tomcat:
mvn tomcat:run
For Jetty:
mvn jetty:run
If you want to learn more about Spring MVC and integration with other technologies, feel free to read my other tutorials in the
Tutorials section.
Subscribe by reader
Subscribe by email
Share
