diff --git a/src/docbkx/introduction/getting-started.xml b/src/docbkx/introduction/getting-started.xml index c15172dd3..d292e7c98 100644 --- a/src/docbkx/introduction/getting-started.xml +++ b/src/docbkx/introduction/getting-started.xml @@ -12,9 +12,9 @@
First Steps - As explained in , Spring Data Document (SDDOC) provides integration + As explained in , 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 SDDOC documentation, + 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.
@@ -34,14 +34,14 @@ Knowing NoSQL and Document stores 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 SDDOC. + 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.
Trying Out The Samples - Unfortunately the SDDOC project is very young and there are no samples available yet. However we are working on them and plan to make them available + Unfortunately the DATADOC project is very young and there are no samples available yet. However we are working on them and plan to make them available as soon as possible. In the meantime however, one can use our test suite as a code example (assuming the documentation is not enough) - we provide extensive integration tests for our code base. diff --git a/src/docbkx/introduction/why-sd-doc.xml b/src/docbkx/introduction/why-sd-doc.xml index dde545bd0..fccb6380c 100644 --- a/src/docbkx/introduction/why-sd-doc.xml +++ b/src/docbkx/introduction/why-sd-doc.xml @@ -14,7 +14,7 @@ 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 SDDOC) framework makes it easy to + 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. diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml index 77e573fdc..686248de2 100644 --- a/src/docbkx/reference/mongodb.xml +++ b/src/docbkx/reference/mongodb.xml @@ -1,88 +1,187 @@ +"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> MongoDB support - One of the document stores supported by SDDOC 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. - - + 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. +
MongoDB Requirements - SDDOC requires MongoDB 1.4 while 1.6 is recommended. - + + DATADOC requires MongoDB 1.4 while 1.6 is recommended.
- +
MongoDB Support High Level View - + The MongoDB support provides several components: + - Configuration Factory - for configuring and handling communication with MongoDB via its Java driver - Template implemenattion - providing a generified, user friendly template classes for interacting with MongoDB. - explains the abstraction builds on top of the low-level MongoDB Java API to handle the - storage and retrieval of documents plus mapping between documents and domain classes. - Support Classes - that offer reusable components such as mapping support and exception translation. + + Configuration Factory + + - for configuring and handling communication with MongoDB via its Java driver + + + + Template implemenattion + + - providing a generified, user friendly template classes for interacting with MongoDB. + + + + explains the abstraction builds on top of the low-level MongoDB Java API to handle the storage and retrieval of documents plus mapping between documents and domain classes. + + + + Support Classes + + - that offer reusable components such as mapping support and exception translation. + + + 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. +
+ +
+ Connecting to MongoDB + + One of the first tasks when using MongoDB and Spring is to connect + to the store through the IoC container. To do that + + The easiest way to work with a + MongoFactoryBean is to configure a + MongoFactory bean. This has the added advantage of + also acting as an ExceptionTranslator that can be used to translate any + Mongo exceptions to exceptions in the + SpringDataAccessException hierarchy as long as your + data access classes are annotatded with @Repository and you are using an + PersistenceExceptionTranslationPostProcessor (see + Spring API docs). + + You have two basic choices - use Java based configuration or XML + based configuration. An example fo a basic Java configuratopn style + is: + + + Java based Spring configuration for MongoDB + + @Configuration +public class AppConfig { + + /* + * Factory bean that creates the Mongo instance + */ + public @Bean MongoFactoryBean mongo() { + MongoFactoryBean mongo = new MongoFactoryBean(); + mongo.setHost("localhost"); + return mongo; + } - 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. -
- -
- Connecting to MongoDB - - One of the first tasks when using MongoDB and Spring is to connect to the store through the IoC container. To do that - - The easiest way to work with a MongoFactoryBean is to configure ... - -
- -
- Working with Objects through <classname>MongoTemplate</classname> - - 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 a high-level abstraction for MongoDB interaction. - - - - Operational views - - - - - - - - Interface - Description - - - - - Collection Operations - MongoDB string (or value) operations - - - Document Operations - MongoDB list operations - - - -
- - Once configured, the template is thread-safe and can be reused across multiple instances. - - Out of the box, MongoTemplate uses a Java-based default converter for most of its operations... - + /* + * A basic MongoTemplate instance + */ + public @Bean MongoTemplate mongoTemplate(Mongo mongo) { + MongoTemplate mongoTemplate = new MongoTemplate(mongo, "test", "HelloMongo"); + return mongoTemplate; + } + + /* + * Use this post processor to translate any MongoExceptions thrown in @Repository annotated classes + */ + public @Bean PersistenceExceptionTranslationPostProcessor persistenceExceptionTranslationPostProcessor() { + return new PersistenceExceptionTranslationPostProcessor(); + } + +} + + + + The following shows the same configuration using XML: + + + XML based Spring configuration for MongoDB + + <!-- Factory bean that creates the Mongo instance --> +<bean id="mongo" class="org.springframework.data.document.mongodb.MongoFactoryBean"> + <property name="host" value="localhost"/> +</bean> + +<!-- A basic MongoTemplate instance --> +<bean id="mongoTemplate" class="org.springframework.data.document.mongodb.MongoTemplate"> + <constructor-arg name="mongo" ref="mongo"/> + <constructor-arg name="databaseName" value="test"/> + <constructor-arg name="defaultCollectionName" value="HelloMongo"/> +</bean> + +<!-- Use this post processor to translate any MongoExceptions thrown in @Repository annotated classes --> +<bean class="org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor"/> + + +
+ +
+ Working with Objects through + <classname>MongoTemplate</classname> + + 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. + + + Operational views + + + + + + + + + + + Interface + + Description + + + + + + Collection + Operations + + MongoDB document operations + + + + Document Operations + + MongoDB collection operations + + + +
+ + Once configured, the template is thread-safe and can be reused + across multiple instances. + + Out of the box, MongoTemplate uses a + Java-based default converter for most of its operations...
@@ -118,8 +217,24 @@ General mongo repository Spring configuration - <mongo:repositories base-package="com.acme.*.repositories" - mongo-template-ref="myMongoTemplate" /> + <?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 @@ -309,11 +424,15 @@ class PersonRepositoryTests {
- -
- Roadmap ahead - - Spring Data MongoDB project 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! -
- \ No newline at end of file + +
+ Roadmap ahead + + Spring Data MongoDB project 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! +
+