DATADOC-30 updated documenation
This commit is contained in:
Thomas Risberg
@@ -1,112 +1,123 @@
|
|||||||
<?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="get-started">
|
<chapter id="get-started">
|
||||||
<title>Getting Started</title>
|
<title>Getting Started</title>
|
||||||
|
|
||||||
<para>Learning a new framework is not always straight forward. In this section, we (the Spring Data team)
|
<para>Learning a new framework is not always straight forward. In this
|
||||||
tried to provide, what we think is, an easy to follow guide for starting with Spring Data Document module.
|
section, we (the Spring Data team) tried to provide, what we think is, an
|
||||||
Of course, feel free to create your own learning 'path' as you see fit and, if possible, please report back
|
easy to follow guide for starting with Spring Data Document module. Of
|
||||||
any improvements to the documentation that can help others.</para>
|
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.</para>
|
||||||
|
|
||||||
<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 (DATADOC) provides integration
|
<para>As explained in <xref linkend="why-Spring Data-Document" />, Spring
|
||||||
between Spring framework and document oriented data stores. Thus, it is important to become acquainted with both of these
|
Data Document (DATADOC) provides integration between Spring framework and
|
||||||
frameworks (storages or environments depending on how you want to name them). Throughout the DATADOC documentation,
|
document oriented data stores. Thus, it is important to become acquainted
|
||||||
each section provides links to resources relevant however, it is best to become familiar with these topics beforehand.</para>
|
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.</para>
|
||||||
|
|
||||||
<section id="get-started:first-steps:spring">
|
<section id="get-started:first-steps:spring">
|
||||||
<title>Knowing Spring</title>
|
<title>Knowing Spring</title>
|
||||||
<para>Spring Data uses heavily Spring framework's <ulink url="http://static.springframework.org/spring/docs/3.0.x/reference/spring-core.html">core</ulink> functionality,
|
|
||||||
such as the <ulink url="http://static.springframework.org/spring/docs/3.0.x/reference/beans.html">IoC</ulink> container,
|
|
||||||
<ulink url="http://static.springframework.org/spring/docs/3.0.x/reference/resources.html">resource</ulink> abstract or
|
|
||||||
<ulink url="http://static.springframework.org/spring/docs/3.0.x/reference/aop.html">AOP</ulink> 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
|
|
||||||
<ulink url="http://www.springsource.org/documentation">home page</ulink> for more information. In general, this should be the starting point for
|
|
||||||
developers wanting to try Spring Data Document.</para>
|
|
||||||
</section>
|
|
||||||
<section id="get-started:first-steps:nosql">
|
|
||||||
<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
|
|
||||||
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 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.
|
|
||||||
</para>
|
|
||||||
</section>
|
|
||||||
<section id="get-started:first-steps:samples">
|
|
||||||
<title>Trying Out The Samples</title>
|
|
||||||
<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
|
|
||||||
integration tests for our code base.
|
|
||||||
</para>
|
|
||||||
<!--
|
|
||||||
<para>The current distribution contains:</para>
|
|
||||||
<itemizedlist>
|
|
||||||
<listitem>
|
|
||||||
<para>Simple Service Sample</para>
|
|
||||||
<para>A simple example that illustrates OSGi service publication and consumption through Spring DM. This is a good starting point
|
|
||||||
for users learning the basics.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>Weather Sample</para>
|
|
||||||
<para>A demo that shows more advanced features of Spring DM and OSGi. The application creates a very simple weather information services
|
|
||||||
presenting some best practices in designing an application to take advantage of the modularity offered by OSGi.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>Simple Web App Sample</para>
|
|
||||||
<para>As the name implies, this is a simple web application, containing Servlets, JSPs and JSP tags, that runs inside OSGi through Spring DM.</para>
|
|
||||||
</listitem>
|
|
||||||
<listitem>
|
|
||||||
<para>Web Console Sample</para>
|
|
||||||
<para>A more complicated sample that demos a Spring MVC annotation based, web application that runs inside OSGi through Spring DM, featuring
|
|
||||||
class path scanning and various Spring taglib. Additionally, the web application interacts with the OSGi environment through the web UI.</para>
|
|
||||||
</listitem>
|
|
||||||
</itemizedlist>
|
|
||||||
<para>Each project contains instructions regarding its content and startup procedure. Users are encouraged to experiment with the samples to get a better
|
|
||||||
understanding of the technologies used.</para>
|
|
||||||
-->
|
|
||||||
</section>
|
|
||||||
</section>
|
|
||||||
|
|
||||||
<section id="get-started:help">
|
<para>Spring Data uses heavily Spring framework's <ulink
|
||||||
<title>Need Help?</title>
|
url="http://static.springframework.org/spring/docs/3.0.x/reference/spring-core.html">core</ulink>
|
||||||
|
functionality, such as the <ulink
|
||||||
<para>If you encounter issues or you are just looking for an advice, feel free to use one of the links below:</para>
|
url="http://static.springframework.org/spring/docs/3.0.x/reference/beans.html">IoC</ulink>
|
||||||
|
container, <ulink
|
||||||
<section id="get-started:help:community">
|
url="http://static.springframework.org/spring/docs/3.0.x/reference/resources.html">resource</ulink>
|
||||||
<title>Community Forum</title>
|
abstract or <ulink
|
||||||
<para>The Spring Data <ulink url="http://forum.springframework.org/forumdisplay.php?f=80">forum</ulink> is a message board for all Spring Data (not just Document) users to
|
url="http://static.springframework.org/spring/docs/3.0.x/reference/aop.html">AOP</ulink>
|
||||||
share information and help each other. Note that registration is needed <emphasis>only</emphasis> for posting.
|
infrastructure. While it is not important to know the Spring APIs,
|
||||||
</para>
|
understanding the concepts behind them is. At a minimum, the idea behind
|
||||||
</section>
|
IoC should be familiar. These being said, the more knowledge one has
|
||||||
<section id="get-started:help:professional">
|
about the Spring, the faster she will pick up Spring Data Document.
|
||||||
<title>Professional Support</title>
|
Besides the very comprehensive (and sometimes disarming) documentation
|
||||||
<para>Professional, from-the-source support, with guaranteed response time, is available from <ulink url="http://www.springsource.com">SpringSource</ulink>,
|
that explains in detail the Spring Framework, there are a lot of
|
||||||
the company behind Spring Data and Spring.
|
articles, blog entries and books on the matter - take a look at the
|
||||||
</para>
|
Spring framework <ulink
|
||||||
</section>
|
url="http://www.springsource.org/documentation">home page</ulink> for
|
||||||
|
more information. In general, this should be the starting point for
|
||||||
|
developers wanting to try Spring Data Document.</para>
|
||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section id="get-started:up-to-date">
|
<section id="get-started:first-steps:nosql">
|
||||||
<title>Following Development</title>
|
<title>Knowing NoSQL and Document stores</title>
|
||||||
|
|
||||||
<para>For information on the Spring Data source code repository, nightly builds and snapshot artifacts please see the Spring Data home
|
<para>NoSQL stores have taken the storage world by storm. It is a vast
|
||||||
<ulink url="http://www.springsource.org/spring-data">page</ulink>.
|
domain with a plethora of solutions, terms and patterns (to make things
|
||||||
</para>
|
worth even the term itself has multiple <ulink
|
||||||
<para>You can help make Spring Data best serve the needs of the Spring community by interacting with developers through the Spring Community
|
url="http://www.google.com/search?q=nosoql+acronym">meanings</ulink>).
|
||||||
<ulink url="http://forum.springsource.org">forums</ulink>.</para>
|
While some of the principles are common, it is crucial that the user is
|
||||||
<para>If you encounter a bug or want to suggest an improvement,
|
familiar to some degree with the stores supported by DATADOC. The best
|
||||||
please create a ticket on the Spring Data issue <ulink url="https://jira.springframework.org/browse/DATAKV">tracker</ulink>.</para>
|
way to get acquainted to this solutions is to read their documentation
|
||||||
<para>To stay up to date with the latest news and announcements in the Spring eco system, subscribe to the
|
and follow their examples - it usually doesn't take more then 5-10
|
||||||
Spring Community <ulink url="http://www.springframework.org/">Portal</ulink>.</para>
|
minutes to go through them and if you are coming from an RDMBS-only
|
||||||
<para>Lastly, you can follow the SpringSource Data <ulink url="http://blog.springsource.com/category/data-access/">blog</ulink> or the project team on Twitter
|
background many times these exercises can be an eye opener.</para>
|
||||||
(<ulink url="http://twitter.com/SpringData">SpringData</ulink>)</para>
|
</section>
|
||||||
</section>
|
|
||||||
|
|
||||||
|
<section id="get-started:first-steps:samples">
|
||||||
|
<title>Trying Out The Samples</title>
|
||||||
|
|
||||||
|
<para>The DATADOC project is very young but there are some samples
|
||||||
|
available in the GitHub repository: <ulink
|
||||||
|
url="https://github.com/SpringSource/spring-data-document-examples">https://github.com/SpringSource/spring-data-document-examples</ulink>.</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="get-started:help">
|
||||||
|
<title>Need Help?</title>
|
||||||
|
|
||||||
|
<para>If you encounter issues or you are just looking for an advice, feel
|
||||||
|
free to use one of the links below:</para>
|
||||||
|
|
||||||
|
<section id="get-started:help:community">
|
||||||
|
<title>Community Forum</title>
|
||||||
|
|
||||||
|
<para>The Spring Data <ulink
|
||||||
|
url="http://forum.springframework.org/forumdisplay.php?f=80">forum</ulink>
|
||||||
|
is a message board for all Spring Data (not just Document) users to
|
||||||
|
share information and help each other. Note that registration is needed
|
||||||
|
<emphasis>only</emphasis> for posting.</para>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="get-started:help:professional">
|
||||||
|
<title>Professional Support</title>
|
||||||
|
|
||||||
|
<para>Professional, from-the-source support, with guaranteed response
|
||||||
|
time, is available from <ulink
|
||||||
|
url="http://www.springsource.com">SpringSource</ulink>, the company
|
||||||
|
behind Spring Data and Spring.</para>
|
||||||
|
</section>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section id="get-started:up-to-date">
|
||||||
|
<title>Following Development</title>
|
||||||
|
|
||||||
|
<para>For information on the Spring Data source code repository, nightly
|
||||||
|
builds and snapshot artifacts please see the Spring Data home <ulink
|
||||||
|
url="http://www.springsource.org/spring-data">page</ulink>.</para>
|
||||||
|
|
||||||
|
<para>You can help make Spring Data best serve the needs of the Spring
|
||||||
|
community by interacting with developers through the Spring Community
|
||||||
|
<ulink url="http://forum.springsource.org">forums</ulink>.</para>
|
||||||
|
|
||||||
|
<para>If you encounter a bug or want to suggest an improvement, please
|
||||||
|
create a ticket on the Spring Data issue <ulink
|
||||||
|
url="https://jira.springframework.org/browse/DATAKV">tracker</ulink>.</para>
|
||||||
|
|
||||||
|
<para>To stay up to date with the latest news and announcements in the
|
||||||
|
Spring eco system, subscribe to the Spring Community <ulink
|
||||||
|
url="http://www.springframework.org/">Portal</ulink>.</para>
|
||||||
|
|
||||||
|
<para>Lastly, you can follow the SpringSource Data <ulink
|
||||||
|
url="http://blog.springsource.com/category/data-access/">blog</ulink> or
|
||||||
|
the project team on Twitter (<ulink
|
||||||
|
url="http://twitter.com/SpringData">SpringData</ulink>)</para>
|
||||||
|
</section>
|
||||||
</chapter>
|
</chapter>
|
||||||
@@ -6,6 +6,6 @@
|
|||||||
3.0.x and above.</para>
|
3.0.x and above.</para>
|
||||||
<para>
|
<para>
|
||||||
In terms of document stores, <ulink url="http://www.mongodb.org/">MongoDB</ulink> preferably version 1.6.5
|
In terms of document stores, <ulink url="http://www.mongodb.org/">MongoDB</ulink> preferably version 1.6.5
|
||||||
and <ulink url="http://couchdb.apache.org/">CouchDB</ulink> 1.0.1 or later are required.
|
or later or <ulink url="http://couchdb.apache.org/">CouchDB</ulink> 1.0.1 or later are required.
|
||||||
</para>
|
</para>
|
||||||
</chapter>
|
</chapter>
|
||||||
@@ -4,8 +4,9 @@
|
|||||||
<preface id="preface">
|
<preface id="preface">
|
||||||
<title>Preface</title>
|
<title>Preface</title>
|
||||||
|
|
||||||
<para>The Spring Datastore Document project applies core Spring concepts to the development of solutions using a document style data store.
|
<para>The Spring Datastore Document project applies core Spring concepts to
|
||||||
We provide a "template" as a high-level abstraction for sending and receiving messages.
|
the development of solutions using a document style data store. We provide a
|
||||||
You will notice similarities to the JDBC support in the Spring Framework.
|
"template" as a high-level abstraction for storing and querying documents.
|
||||||
</para>
|
You will notice similarities to the JDBC support in the Spring
|
||||||
|
Framework.</para>
|
||||||
</preface>
|
</preface>
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
<?xml version="1.0" encoding="UTF-8"?>
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
<!DOCTYPE chapter 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="mongo.core" xmlns:xi="http://www.w3.org/2001/XInclude">
|
<chapter id="mongo.core">
|
||||||
<title>Core support</title>
|
<title>Core support</title>
|
||||||
|
|
||||||
<para>One of the document stores supported by DATADOC is <ulink
|
<para>One of the document stores supported by DATADOC is <ulink
|
||||||
@@ -24,18 +24,27 @@
|
|||||||
<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
|
<listitem>
|
||||||
and handling communication with MongoDB via its Java driver</listitem>
|
<emphasis>Configuration Factory</emphasis>
|
||||||
|
|
||||||
<listitem><emphasis>Template implemenattion</emphasis> - providing a
|
- for configuring and handling communication with MongoDB via its Java driver
|
||||||
generified, user friendly template classes for interacting with MongoDB.
|
</listitem>
|
||||||
<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
|
<listitem>
|
||||||
components such as mapping support and exception translation.</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
|
<para>For most tasks, the higher-level abstractions and support services
|
||||||
@@ -122,7 +131,7 @@ public class AppConfig {
|
|||||||
</section>
|
</section>
|
||||||
|
|
||||||
<section id="mongodb:template">
|
<section id="mongodb:template">
|
||||||
<title>Working with Objects through
|
<title>Working with objects through
|
||||||
<classname>MongoTemplate</classname></title>
|
<classname>MongoTemplate</classname></title>
|
||||||
|
|
||||||
<para>Most users are likely to use <classname>MongoTemplate</classname>
|
<para>Most users are likely to use <classname>MongoTemplate</classname>
|
||||||
@@ -130,61 +139,23 @@ public class AppConfig {
|
|||||||
<literal>org.springframework.data.document.mongodb</literal> - the
|
<literal>org.springframework.data.document.mongodb</literal> - the
|
||||||
template is in fact the central class of the MongoDB module due to its
|
template is in fact the central class of the MongoDB module due to its
|
||||||
rich feature set. The template offers convenience methods and automatic
|
rich feature set. The template offers convenience methods and automatic
|
||||||
mapping between MongoDB JSON documents and your domain classes.</para>
|
mapping between MongoDB JSON documents and your domain classes. Out of the
|
||||||
|
box, <classname>MongoTemplate</classname> 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, the template is
|
||||||
|
thread-safe and can be reused across multiple instances. </para>
|
||||||
|
|
||||||
<table id="MongoDB-template-operations-view" pgwide="1">
|
<para>Let's look at a couple of examples for how to interect with the
|
||||||
<title>Operational views</title>
|
<classname>MongoTemplate</classname>.</para>
|
||||||
|
|
||||||
<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: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
|
<para>The Spring Data Document projects MongoDB support is in its early
|
||||||
interested in feedback, knowing what your use cases are, what are the
|
stages. We are interested in feedback, knowing what your use cases are,
|
||||||
common patters you encounter so that the MongoDB module better serves your
|
what are the common patters you encounter so that the MongoDB module
|
||||||
needs. Do contact us using the channels <link
|
better serves your needs. Do contact us using the channels <link
|
||||||
linkend="get-started:help:community">mentioned</link> above, we are
|
linkend="get-started:help:community">mentioned</link> above, we are
|
||||||
interested in hearing from you!</para>
|
interested in hearing from you!</para>
|
||||||
</section>
|
</section>
|
||||||
|
|||||||
Reference in New Issue
Block a user