mindol1004/spring-data-mongodb
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge remote branch 'origin/master'

Browse Source
This commit is contained in:
Mark Pollack
2010-12-23 14:47:46 -05:00
parent e4d44e4a17 80b245001a
commit 47438367f6
3 changed files with 205 additions and 86 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
src/docbkx/introduction/getting-started.xml
View File

@@ -12,9 +12,9 @@
<section id="get-started:first-steps"> <section id="get-started:first-steps">
<title>First Steps</title> <title>First Steps</title>
<para>As explained in <xref linkend="why-Spring Data-Document"/>, Spring Data Document (SDDOC) provides integration <para>As explained in <xref linkend="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 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.</para> each section provides links to resources relevant however, it is best to become familiar with these topics beforehand.</para>
<section id="get-started:first-steps:spring"> <section id="get-started:first-steps:spring">
@@ -34,14 +34,14 @@
<title>Knowing NoSQL and Document stores</title> <title>Knowing NoSQL and Document stores</title>
<para>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 <para>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 <ulink url="http://www.google.com/search?q=nosoql+acronym">meanings</ulink>). term itself has multiple <ulink url="http://www.google.com/search?q=nosoql+acronym">meanings</ulink>).
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 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. to go through them and if you are coming from an RDMBS-only background many times these exercises can be an eye opener.
</para> </para>
</section> </section>
<section id="get-started:first-steps:samples"> <section id="get-started:first-steps:samples">
<title>Trying Out The Samples</title> <title>Trying Out The Samples</title>
<para>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 <para>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 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. integration tests for our code base.
</para> </para>

2
src/docbkx/introduction/why-sd-doc.xml
View File

@@ -14,7 +14,7 @@
and speed. In terms of implementation, Document stores represent one of the and speed. In terms of implementation, Document stores represent one of the
most popular types of stores in the NoSQL space.</para> most popular types of stores in the NoSQL space.</para>
<para>The Spring Data Document (or SDDOC) framework makes it easy to <para>The Spring Data Document (or DATADOC) framework makes it easy to
write Spring applications that use a Document store by eliminating the redundant write Spring applications that use a Document store by eliminating the redundant
tasks and boiler place code required for interacting with the store through tasks and boiler place code required for interacting with the store through
Spring's excellent infrastructure support.</para> Spring's excellent infrastructure support.</para>

247
src/docbkx/reference/mongodb.xml
View File

@@ -1,88 +1,187 @@
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" <!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<chapter id="mongodb"> <chapter id="mongodb">
<title>MongoDB support</title> <title>MongoDB support</title>
<para>One of the document stores supported by SDDOC is <ulink url="http://www.mongodb.org/">MongoDB</ulink>. <para>One of the document stores supported by DATADOC is <ulink
To quote the project home page: url="http://www.mongodb.org/">MongoDB</ulink>. To quote the project home
<quote> page: <quote> MongoDB (from "humongous") is a scalable, high-performance,
MongoDB (from "humongous") is a scalable, high-performance, open source, document-oriented database. open source, document-oriented database. </quote> <para>Spring Data Document
</quote> provides easy configuration and access to MongoDB from a Spring application.
Offers both low-level and high-level abstraction for interacting with the
<para>Spring Data Document provides easy configuration and access to MongoDB from a Spring application. Offers both low-level and store, freeing the user from infrastructural concerns.</para></para>
high-level abstraction for interacting with the store, freeing the user from infrastructural concerns.</para>
</para>
<section id="mongodb:requirements"> <section id="mongodb:requirements">
<title>MongoDB Requirements</title> <title>MongoDB Requirements</title>
<para>SDDOC requires MongoDB 1.4 while 1.6 is recommended.
</para> <para>DATADOC requires MongoDB 1.4 while 1.6 is recommended.</para>
</section> </section>
<section id="mongodb:architecture"> <section id="mongodb:architecture">
<title>MongoDB Support High Level View</title> <title>MongoDB Support High Level View</title>
<para>The MongoDB support provides several components:</para> <para>The MongoDB support provides several components:</para>
<itemizedlist> <itemizedlist>
<listitem><emphasis>Configuration Factory</emphasis> - for configuring and handling communication with MongoDB via its Java driver</listitem> <listitem>
<listitem><emphasis>Template implemenattion</emphasis> - providing a generified, user friendly template classes for interacting with MongoDB. <emphasis>Configuration Factory</emphasis>
<xref linkend="mongodb:template"/> explains the abstraction builds on top of the low-level MongoDB Java API to handle the
storage and retrieval of documents plus mapping between documents and domain classes.</listitem> - for configuring and handling communication with MongoDB via its Java driver
<listitem><emphasis>Support Classes</emphasis> - that offer reusable components such as mapping support and exception translation.</listitem> </listitem>
<listitem>
<emphasis>Template implemenattion</emphasis>
- providing a generified, user friendly template classes for interacting with MongoDB.
<xref linkend="mongodb:template" />
explains the abstraction builds on top of the low-level MongoDB Java API to handle the storage and retrieval of documents plus mapping between documents and domain classes.
</listitem>
<listitem>
<emphasis>Support Classes</emphasis>
- that offer reusable components such as mapping support and exception translation.
</listitem>
</itemizedlist> </itemizedlist>
<para>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 <para>For most tasks, the higher-level abstractions and support services
easy to get a hold of the low level connection (org.mongo.DB) to communicate directly with MongoDB.</para> are the best choice. Note that at any point, one can move between layers -
</section> for example, it's very easy to get a hold of the low level connection
(org.mongo.DB) to communicate directly with MongoDB.</para>
</section>
<section id="mongodb:connectors"> <section id="mongodb:connectors">
<title>Connecting to MongoDB</title> <title>Connecting to MongoDB</title>
<para>One of the first tasks when using MongoDB and Spring is to connect to the store through the IoC container. To do that</para> <para>One of the first tasks when using MongoDB and Spring is to connect
to the store through the IoC container. To do that</para>
<para>The easiest way to work with a <interfacename>MongoFactoryBean</interfacename> is to configure ...</para> <para>The easiest way to work with a
<interfacename>MongoFactoryBean</interfacename> is to configure a
<classname>MongoFactory</classname> 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
<classname>SpringDataAccessException</classname> hierarchy as long as your
data access classes are annotatded with @Repository and you are using an
<classname>PersistenceExceptionTranslationPostProcessor</classname> (see
<link linkend="???">Spring API docs</link>).</para>
</section> <para>You have two basic choices - use Java based configuration or XML
based configuration. An example fo a basic Java configuratopn style
is:</para>
<section id="mongodb:template"> <example>
<title>Working with Objects through <classname>MongoTemplate</classname></title> <title>Java based Spring configuration for MongoDB</title>
<para>Most users are likely to use <classname>MongoTemplate</classname> and its corresponding package <literal>org.springframework.data.document.mongodb</literal> - the <programlisting language="java">@Configuration
template is in fact the central class of the MongoDB module due to its rich feature set. public class AppConfig {
The template offers a high-level abstraction for MongoDB interaction.
</para>
<table id="MongoDB-template-operations-view" pgwide="1"> /*
<title>Operational views</title> * Factory bean that creates the Mongo instance
*/
public @Bean MongoFactoryBean mongo() {
MongoFactoryBean mongo = new MongoFactoryBean();
mongo.setHost("localhost");
return mongo;
}
<tgroup cols="2"> /*
<colspec colname="c1" colwidth="1*" align="center"/> * A basic MongoTemplate instance
<colspec colname="c2" colwidth="1*" align="center"/> */
<spanspec spanname="both" namest="c1" nameend="c2" colsep="0" align="center" /> public @Bean MongoTemplate mongoTemplate(Mongo mongo) {
<thead> MongoTemplate mongoTemplate = new MongoTemplate(mongo, "test", "HelloMongo");
<row> return mongoTemplate;
<entry>Interface</entry> }
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><interfacename>Collection Operations</interfacename></entry>
<entry>MongoDB string (or value) operations</entry>
</row>
<row>
<entry><interfacename>Document Operations</interfacename></entry>
<entry>MongoDB list operations</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Once configured, the template is thread-safe and can be reused across multiple instances.</para> /*
* Use this post processor to translate any MongoExceptions thrown in @Repository annotated classes
*/
public @Bean PersistenceExceptionTranslationPostProcessor persistenceExceptionTranslationPostProcessor() {
return new PersistenceExceptionTranslationPostProcessor();
}
<para>Out of the box, <classname>MongoTemplate</classname> uses a Java-based default converter for most of its operations...</para> }
</programlisting>
</example>
<para>The following shows the same configuration using XML:</para>
<example>
<title>XML based Spring configuration for MongoDB</title>
<programlisting language="xml">&lt;!-- Factory bean that creates the Mongo instance --&gt;
&lt;bean id="mongo" class="org.springframework.data.document.mongodb.MongoFactoryBean"&gt;
&lt;property name="host" value="localhost"/&gt;
&lt;/bean&gt;
&lt;!-- A basic MongoTemplate instance --&gt;
&lt;bean id="mongoTemplate" class="org.springframework.data.document.mongodb.MongoTemplate"&gt;
&lt;constructor-arg name="mongo" ref="mongo"/&gt;
&lt;constructor-arg name="databaseName" value="test"/&gt;
&lt;constructor-arg name="defaultCollectionName" value="HelloMongo"/&gt;
&lt;/bean&gt;
&lt;!-- Use this post processor to translate any MongoExceptions thrown in @Repository annotated classes --&gt;
&lt;bean class="org.springframework.dao.annotation.PersistenceExceptionTranslationPostProcessor"/&gt;
</programlisting>
</example>
</section>
<section id="mongodb:template">
<title>Working with Objects through
<classname>MongoTemplate</classname></title>
<para>Most users are likely to use <classname>MongoTemplate</classname>
and its corresponding package
<literal>org.springframework.data.document.mongodb</literal> - 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.</para>
<table id="MongoDB-template-operations-view" pgwide="1">
<title>Operational views</title>
<tgroup cols="2">
<colspec align="center" colname="c1" colwidth="1*" />
<colspec align="center" colname="c2" colwidth="1*" />
<spanspec align="center" colsep="0" nameend="c2" namest="c1"
spanname="both" />
<thead>
<row>
<entry>Interface</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><interfacename>Collection
Operations</interfacename></entry>
<entry>MongoDB document operations</entry>
</row>
<row>
<entry><interfacename>Document Operations</interfacename></entry>
<entry>MongoDB collection operations</entry>
</row>
</tbody>
</tgroup>
</table>
<para>Once configured, the template is thread-safe and can be reused
across multiple instances.</para>
<para>Out of the box, <classname>MongoTemplate</classname> uses a
Java-based default converter for most of its operations...</para>
</section> </section>
<section id="mongodb.repositories"> <section id="mongodb.repositories">
@@ -118,8 +217,24 @@
<example> <example>
<title>General mongo repository Spring configuration</title> <title>General mongo repository Spring configuration</title>
<programlisting language="xml">&lt;mongo:repositories base-package="com.acme.*.repositories" <programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
mongo-template-ref="myMongoTemplate" /&gt;</programlisting> &lt;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"&gt;
&lt;mongo:repositories base-package="com.acme.*.repositories"
mongo-template-ref="myMongoTemplate" /&gt;
...
&lt;/beans&gt;</programlisting>
</example> </example>
<para>This namespace element will cause the base packages to be scanned <para>This namespace element will cause the base packages to be scanned
@@ -310,10 +425,14 @@ class PersonRepositoryTests {
</section> </section>
</section> </section>
<section id="mongodb:future"> <section id="mongodb:future">
<title>Roadmap ahead</title> <title>Roadmap ahead</title>
<para>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 <para>Spring Data MongoDB project is in its early stages. We are
better serves your needs. Do contact us using the channels <link linkend="get-started:help:community">mentioned</link> above, we are interested in hearing from you!</para> interested in feedback, knowing what your use cases are, what are the
</section> common patters you encounter so that the MongoDB module better serves your
needs. Do contact us using the channels <link
linkend="get-started:help:community">mentioned</link> above, we are
interested in hearing from you!</para>
</section>
</chapter> </chapter>