DATADOC-147 - Update reference documentation to cover changes from M2 to M3 (partial work)

src/docbkx/introduction/getting-started.xml

@@ -5,10 +5,10 @@
   <title>Additional Help Resources</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
+  section, we try to provide what we think is an easy to follow guide for
-  easy to follow guide for starting with Spring Data Document module. However,
+  starting with Spring Data Document module. However, if you encounter issues
-  if you encounter issues or you are just looking for an advice, feel free to
+  or you are just looking for an advice, feel free to use one of the links
-  use one of the links below:</para>
+  below:</para>
 
   <section id="get-started:help">
     <title>Support</title>

src/docbkx/introduction/introduction.xml

@@ -11,22 +11,27 @@
   Spring concepts. </para><section id="get-started:first-steps:spring">
       <title>Knowing Spring</title>
 
-      <para>Spring Data uses heavily Spring framework's <ulink
+      <para>Spring Data uses 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
+      </ulink> container and Data Access abstractions such as the portable
-      url="http://static.springframework.org/spring/docs/3.0.x/reference/resources.html">resource
+      exception hierarchy. While it is not important to know the Spring APIs,
-      </ulink> abstract or <ulink
+      understanding the concepts behind them is. At a minimum, the idea behind
-      url="http://static.springframework.org/spring/docs/3.0.x/reference/aop.html">AOP
+      IoC should be familiar for whatever IoC container you choose to use.
-      </ulink> infrastructure. While it is not important to know the Spring
+      </para>
-      APIs, understanding the concepts behind them is. At a minimum, the idea
+
-      behind IoC should be familiar. These being said, the more knowledge one
+      <para>The core functionality of the MongoDB and CouchDB support can be
-      has about the Spring, the faster she will pick up Spring Data Document.
+      used directly, with no references to the Spring Container, much like
-      Besides the very comprehensive (and sometimes disarming) documentation
+      JdbcTemplate can be used 'standalone' without any other services of the
-      that explains in detail the Spring Framework, there are a lot of
+      Spring container. To leverage all the features of Spring Data document,
-      articles, blog entries and books on the matter - take a look at the
+      such as it's repository support, then you will need to configure the
-      Spring framework <ulink
+      container using Spring.</para>
+
+      <para>To learn more about Spring, you can refer to the 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.</para>
     </section><section id="get-started:first-steps:nosql">

src/docbkx/reference/mongodb.xml

@@ -39,11 +39,6 @@
       <para>Persistence and mapping lifecycle events</para>
     </listitem>
 
-    <listitem>
-      <para>Low-level mapping using MongoReader/MongoWriter
-      abstractions</para>
-    </listitem>
-
     <listitem>
       <para>Java based Query, Criteria, and Update DSLs</para>
     </listitem>
@@ -71,15 +66,16 @@
     </listitem>
   </itemizedlist>
 
-  <para>For most tasks you will find yourself using MongoTemplate or the
+  <para>For most tasks you will find yourself using
-  Repository support that both leverage the rich mapping functionality.
+  <classname>MongoTemplate</classname> or the Repository support that both
-  MongoTemplate is the place to look for accessing functionality such as
+  leverage the rich mapping functionality. MongoTemplate is the place to look
-  incrementing counters or ad-hoc CRUD operations. MongoTemplate also provides
+  for accessing functionality such as incrementing counters or ad-hoc CRUD
-  callback methods so that it is easy for you to get a hold of the low level
+  operations. MongoTemplate also provides callback methods so that it is easy
-  API artifacts such as <literal>org.mongo.DB</literal> to communicate
+  for you to get a hold of the low level API artifacts such as
-  directly with MongoDB. The goal with naming conventions on various API
+  <literal>org.mongo.DB</literal> to communicate directly with MongoDB. The
-  artifacts is to copy those in the base MongoDB Java driver so you can easily
+  goal with naming conventions on various API artifacts is to copy those in
-  map your existing knowledge onto the Spring APIs.</para>
+  the base MongoDB Java driver so you can easily map your existing knowledge
+  onto the Spring APIs.</para>
 
   <section id="mongodb-requirements">
     <title>Getting Started</title>
@@ -110,21 +106,13 @@
   &lt;dependency&gt;
     &lt;groupId&gt;org.springframework.data&lt;/groupId&gt;
     &lt;artifactId&gt;spring-data-mongodb&lt;/artifactId&gt;
-    &lt;version&gt;1.0.0.M2&lt;/version&gt;
+    &lt;version&gt;1.0.0.M3&lt;/version&gt;
-  &lt;/dependency&gt;
-
-  &lt;dependency&gt;
-    &lt;groupId&gt;cglib&lt;/groupId&gt;
-    &lt;artifactId&gt;cglib&lt;/artifactId&gt;
-    &lt;version&gt;2.2&lt;/version&gt;
   &lt;/dependency&gt;
 
 &lt;/dependencies&gt;
 </programlisting>
 
-    <para>The cglib dependency is there as we will use Spring's Java
+    <para>Also change the version of Spring in the pom.xml to be</para>
-    configuration style. Also change the version of Spring in the pom.xml to
-    be</para>
 
     <programlisting lang="" language="xml">&lt;spring.framework.version&gt;3.0.5.RELEASE&lt;/spring.framework.version&gt;</programlisting>
 
@@ -145,105 +133,98 @@
     here</ulink>.</para>
 
     <para>You may also want to set the logging level to DEBUG to see some
-    additional information, edit the log4j.properties file and add</para>
+    additional information, edit the log4j.properties file to have</para>
 
-    <programlisting>log4j.category.org.springframework.data.document.mongodb=DEBUG</programlisting>
+    <programlisting>log4j.category.org.springframework.data.document.mongodb=DEBUG
+log4j.appender.stdout.layout.ConversionPattern=%-5p [%c{3}]: %m%n</programlisting>
 
-    <para>Next, in the org.spring.mongodb package in the
+    <para>Create a simple Person class to persist</para>
-    <literal>src/test/java</literal> directory create a class as shown
-    below.</para>
 
-    <programlisting lang="" language="java">package org.spring.mongodb;
+    <programlisting language="java">package org.spring.mongodb;
-
-import org.springframework.context.annotation.Configuration;
-import org.springframework.data.document.mongodb.MongoTemplate;
-import org.springframework.data.document.mongodb.config.AbstractMongoConfiguration;
 
-import com.mongodb.Mongo;
+public class Person {
 
-@Configuration
+  private String id;
-public class MongoConfig extends AbstractMongoConfiguration {
+  private String firstName;
+  private String lastName;
+  private int age;
 
-  @Override
+  public Person(String firstName, String lastName, int age) {
-  public Mongo mongo() throws Exception {
+    this.firstName = firstName;
-    return new Mongo("localhost");
+    this.lastName = lastName;
+    this.age = age;
   }
-
+  public String getFirstName() {
-  @Override
+    return firstName;
-  public MongoTemplate mongoTemplate() throws Exception {
-    return new MongoTemplate(mongo() , "database", "mongoexample");
   }
 
-}</programlisting>
+  public void setFirstName(String firstName) {
-
+    this.firstName = firstName;
-    <para>Then create a simple Person class to persist</para>
+  }
-
-    <programlisting language="java">package org.spring.mongodb;
-
-public class Person {
-
-  private String id;
 
-  private String name;
+  public String getLastName() {
+    return lastName;
+  }
 
-  public Person(String id, String name) {
+  public void setLastName(String lastName) {
-    this.id = id;
+    this.lastName = lastName;
-    this.name = name;
   }
 
-  public String getId() {
+  public int getAge() {
-    return id;
+    return age;
   }
 
-  public String getName() {
+  public void setAge(int age) {
-    return name;
+    this.age = age;
   }
 
   @Override
   public String toString() {
-    return "Person [id=" + id + ", name=" + name + "]";
+    return "Person [id=" + id + ", firstName=" + firstName + ", lastName="
+        + lastName + ", age=" + age + "]";
   }
 
+  
 }</programlisting>
 
     <para>And a main application to run</para>
 
     <programlisting language="java">package org.spring.mongodb;
 
+import static org.springframework.data.document.mongodb.query.Criteria.where;
+
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
-import org.springframework.context.ApplicationContext;
-import org.springframework.context.annotation.AnnotationConfigApplicationContext;
 import org.springframework.data.document.mongodb.MongoOperations;
-import org.springframework.data.document.mongodb.query.Criteria;
+import org.springframework.data.document.mongodb.MongoTemplate;
 import org.springframework.data.document.mongodb.query.Query;
 
+import org.spring.mongodb.Person;
+
 public class MongoApp {
 
   private static final Log log = LogFactory.getLog(MongoApp.class);
 
   public static void main(String[] args) {
-    ApplicationContext ctx = new AnnotationConfigApplicationContext(MongoConfig.class);
-    MongoOperations mongoOps = ctx.getBean(MongoOperations.class);
 
-    mongoOps.insert(new Person("1234", "Joe"));
+    MongoOperations mongoOps = new MongoTemplate(new Mongo(), "database");
+   
+    mongoOps.insert(new Person("Joe", "Swanson", 34));
 
-    log.info(mongoOps.findOne(new Query(Criteria.where("name").is("Joe")), Person.class));
+    log.info( mongoOps.findOne(new Query(where("firstName").is("Joe")), Person.class) );
+
+    mongoOps.dropCollection("person");
   }
 
 }</programlisting>
 
     <para>This will produce the following output</para>
 
-    <programlisting>MongoPersistentEntityIndexCreator] - &lt;Analyzing class class org.spring.mongodb.Person for index information.&gt;
+    <programlisting>DEBUG [mongodb.mapping.MongoPersistentEntityIndexCreator]: Analyzing class class org.mongo.demo2.domain.Person for index information.
-LoggingEventListener] - &lt;onBeforeConvert: Person [id=1234, name=Joe]&gt;
+DEBUG [document.mongodb.MongoTemplate]: insert DBObject containing fields: [_class, lastName, age, firstName] in collection: Person
-LoggingEventListener] - &lt;onBeforeSave: Person [id=1234, name=Joe], { "_id" : "1234" , "name" : "Joe"}&gt;
+DEBUG [document.mongodb.MongoTemplate]: findOne using query: { "firstName" : "Joe"} in db.collection: database.Person
-MongoTemplate] - &lt;insert DBObject: { "_id" : "1234" , "name" : "Joe"}&gt;
+INFO  [spring.mongodb.MongoApp]: Person [id=4ddb2f629e60ab6a21da5fdb, firstName=Joe, lastName=Swanson, age=34]
-LoggingEventListener] - &lt;onAfterSave: Person [id=1234, name=Joe], { "_id" : "1234" , "name" : "Joe"}&gt;
+DEBUG [document.mongodb.MongoTemplate]: Dropped collection [database.person]</programlisting>
-MongoTemplate] - &lt;findOne using query: { "name" : "Joe"} in db.collection: database.person&gt;
-LoggingEventListener] - &lt;onAfterLoad: { "_id" : "1234" , "name" : "Joe"}&gt;
-LoggingEventListener] - &lt;onAfterConvert: { "_id" : "1234" , "name" : "Joe"}, Person [id=1234, name=Joe]&gt;
-MongoApp] - &lt;Person [id=1234, name=Joe]&gt;</programlisting>
 
     <note>
       <para>If you are not using Maven then you would need to include the
@@ -299,13 +280,7 @@ MongoApp] - &lt;Person [id=1234, name=Joe]&gt;</programlisting>
           <listitem>
             <para>spring-expression-3.0.5.RELEASE.jar</para>
           </listitem>
-
-          <listitem>
-            <para>spring-tx-3.0.5.RELEASE.jar</para>
-          </listitem>
         </itemizedlist></para>
-
-      <para> </para>
     </note>
   </section>
 
@@ -319,7 +294,7 @@ MongoApp] - &lt;Person [id=1234, name=Joe]&gt;</programlisting>
   </section>
 
   <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 create a
     <classname>com.mongodb.Mongo</classname> object using the IoC container.