DATADOC-30 copied base docs from key-value -- thanks Costin

src/docbkx/index.xml

@@ -5,26 +5,28 @@
   <bookinfo>
     <title>Spring Datastore Document - Reference Documentation</title>
 
-    <releaseinfo>version;</releaseinfo>
+    <releaseinfo>&version;</releaseinfo>
 
     <authorgroup>
       <author>
         <firstname>Mark</firstname>
-
         <surname>Pollack</surname>
       </author>
 
       <author>
         <firstname>Thomas</firstname>
-
         <surname>Risberg</surname>
       </author>
 
       <author>
         <firstname>Oliver</firstname>
-
         <surname>Gierke</surname>
       </author>
+      <author>
+          <firstname>Costin</firstname>
+          <surname>Leau</surname>
+          <affiliation>SpringSource</affiliation>
+      </author>
     </authorgroup>
 
     <legalnotice>
@@ -38,15 +40,21 @@
   <toc />
 
   <xi:include href="preface.xml" />
-  <xi:include href="mongo.xml" />
 
-  <part>
-    <title>Reference</title>
+  <part id="introduction">
+    <title>Introduction</title>
      
-    <partintro>
-      <para>This part of the reference documentation details the ...</para>
-    </partintro>
-
-    <!-- <xi:include href="amqp.xml"/> -->
+    <xi:include href="introduction/introduction.xml"/>
+    <xi:include href="introduction/why-sd-doc.xml"/>
+    <xi:include href="introduction/requirements.xml"/>
+    <xi:include href="introduction/getting-started.xml"/>
   </part>
+
+  <part id="reference">
+    <title>Reference Documentation</title>
+     
+    <xi:include href="reference/introduction.xml"/>
+    <xi:include href="reference/mongodb.xml"/>
+  </part>
+
 </book>

src/docbkx/introduction/getting-started.xml

@@ -0,0 +1,112 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="get-started">
+    <title>Getting Started</title>
+
+    <para>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.</para>
+
+    <section id="get-started:first-steps">
+		<title>First Steps</title>
+		
+		<para>As explained in <xref linkend="why-Spring Data-Document"/>, Spring Data Document (SDDOC) 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, 
+		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">
+			<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 SDDOC.
+			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 SDDOC 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">
+		<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>

src/docbkx/introduction/introduction.xml

@@ -0,0 +1,17 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+
+<partintro>
+          <para>
+            <para>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.</para>
+			
+			<para>For an introduction to document stores or Spring, or Spring Data examples, please refer to
+			<xref linkend="get-started"/> - this documentation refers only to Spring Data Document Support and 
+			assumes the user is familiar with the document stores and Spring concepts.</para>
+
+			</para>
+          
+</partintro>

src/docbkx/introduction/requirements.xml

@@ -0,0 +1,11 @@
+  <chapter id="requirements">
+      <title>Requirements</title>
+
+      <para>Spring Data Document 1.x binaries requires JDK level 6.0 and above, 
+      and <ulink url="http://www.springsource.org/documentation">Spring Framework</ulink>
+      3.0.x and above.</para>
+      <para>
+      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.
+      </para>
+  </chapter>

src/docbkx/introduction/why-sd-doc.xml

@@ -0,0 +1,21 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="why-Spring Data-Document">
+    <title>Why Spring Data - Document?</title>
+
+    <para>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.</para>
+    
+    <para><ulink url="http://en.wikipedia.org/wiki/NoSQL">NoSQL</ulink>
+    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.</para>
+
+    <para>The Spring Data Document (or SDDOC) 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.</para>
+</chapter>

src/docbkx/reference/introduction.xml

@@ -0,0 +1,9 @@
+      <partintro>
+      <title>Document structure</title>
+
+	  <para>This part of the reference documentation explains the core functionality
+	  offered by Spring Data Document.</para>
+
+      <para><xref linkend="mongodb"/> introduces the Document module feature set.</para>
+
+      </partintro>

src/docbkx/reference/mongodb.xml

@@ -0,0 +1,94 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
+                 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+<chapter id="mongodb">
+  <title>MongoDB support</title>
+
+  <para>One of the document stores supported by SDDOC is <ulink url="http://www.mongodb.org/">MongoDB</ulink>.
+  To quote the project home page:
+  <quote>
+	MongoDB (from "humongous") is a scalable, high-performance, open source, document-oriented database.
+  </quote>
+  
+  <para>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.</para>
+  </para>
+  
+  <section id="mongodb:requirements">
+    <title>MongoDB Requirements</title>
+    <para>SDDOC requires MongoDB 1.4 while 1.6 is recommended.
+    </para>
+  </section>
+  
+  <section id="mongodb:architecture">
+    <title>MongoDB Support High Level View</title>
+    
+    <para>The MongoDB support provides several components:</para>
+    <itemizedlist>
+      <listitem><emphasis>Configuration Factory</emphasis> - for configuring and handling communication with MongoDB via its Java driver</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>
+    
+    <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
+    easy to get a hold of the low level connection (org.mongo.DB) to communicate directly with MongoDB.</para>
+    </section>
+  
+    <section id="mongodb:connectors">
+      <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>The easiest way to work with a <interfacename>MongoFactoryBean</interfacename> is to configure ...</para>
+      
+    </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 a high-level abstraction for MongoDB interaction.
+      </para>
+      
+      <table  id="MongoDB-template-operations-view" pgwide="1">
+        <title>Operational views</title>
+        
+        <tgroup cols="2">
+          <colspec colname="c1" colwidth="1*" align="center"/>
+          <colspec colname="c2" colwidth="1*" align="center"/>
+          <spanspec spanname="both" namest="c1" nameend="c2" colsep="0" align="center" />
+          <thead>
+            <row>
+              <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>
+      
+      <para>Out of the box, <classname>MongoTemplate</classname> uses a Java-based default converter for most of its operations...</para>
+      
+  </section>
+    
+    <section id="mongodb:future">
+    	<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
+    	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>