DATAMONGO-1019 - Corrected examples in reference documentation.

Examples were not properly converted. One table got dropped, so I added it back. Fix IMPORTANT notes.

Original pull requests: #214.

Author: gregturn

src/main/asciidoc/index.adoc

@@ -2,8 +2,11 @@
 Mark Pollack, Thomas Risberg, Oliver Gierke, Costin Leau, Jon Brisbin, Thomas Darimont, Christoph Strobl
 :toc:
 :spring-data-commons-docs: https://raw.githubusercontent.com/spring-projects/spring-data-commons/master/src/main/asciidoc
+
 {version}
 
+© 2008-2014 The original authors.
+
 NOTE: _Copies of this document may be made for your own use and for distribution to others, provided that you do not charge any fee for such copies and further provided that each copy contains this Copyright Notice, whether distributed in print or electronically._
 
 include::preface.adoc[]

src/main/asciidoc/reference/cross-store.adoc

@@ -10,8 +10,8 @@ Assuming that you have a working JPA application and would like to add some cros
 
 First of all you need to add a dependency on the  module. Using Maven this is done by adding a dependency to your pom:
 
-=== Example Maven pom.xml with spring-data-mongodb-cross-store dependency
-
+.Example Maven pom.xml with spring-data-mongodb-cross-store dependency
+====
 [source,xml]
 ----
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -31,11 +31,12 @@ First of all you need to add a dependency on the  module. Using Maven this is do
 
 </project>
 ----
+====
 
 Once this is done we need to enable AspectJ for the project. The cross-store support is implemented using AspectJ aspects so by enabling compile time AspectJ support the cross-store features will become available to your project. In Maven you would add an additional plugin to the <build> section of the pom:
 
-=== Example Maven pom.xml with AspectJ plugin enabled
-
+.Example Maven pom.xml with AspectJ plugin enabled
+====
 [source,xml]
 ----
 <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@@ -100,11 +101,12 @@ Once this is done we need to enable AspectJ for the project. The cross-store sup
 
 </project>
 ----
+====
 
 Finally, you need to configure your project to use MongoDB and also configure the aspects that are used. The following XML snippet should be added to your application context:
 
-=== Example application context with MongoDB and cross-store aspect support
-
+.Example application context with MongoDB and cross-store aspect support
+====
 [source,xml]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
@@ -150,14 +152,15 @@ Finally, you need to configure your project to use MongoDB and also configure th
 
 </beans>
 ----
+====
 
 [[mongodb_cross-store-application]]
 == Writing the Cross Store Application
 
 We are assuming that you have a working JPA application so we will only cover the additional steps needed to persist part of your Entity in your Mongo database. First you need to identify the field you want persisted. It should be a domain class and follow the general rules for the Mongo mapping support covered in previous chapters. The field you want persisted in MongoDB should be annotated using the `@RelatedDocument` annotation. That is really all you need to do!. The cross-store aspects take care of the rest. This includes marking the field with `@Transient` so it won't be persisted using JPA, keeping track of any changes made to the field value and writing them to the database on successful transaction completion, loading the document from MongoDB the first time the value is used in your application. Here is an example of a simple Entity that has a field annotated with `@RelatedEntity`.
 
-=== Example of Entity with @RelatedDocument
-
+.Example of Entity with @RelatedDocument
+====
 [source,java]
 ----
 @Entity
@@ -177,9 +180,10 @@ public class Customer {
   // getters and setters omitted
 }
 ----
+====
 
-=== Example of domain class to be stored as document
-
+.Example of domain class to be stored as document
+====
 [source,java]
 ----
 public class SurveyInfo {
@@ -208,11 +212,12 @@ public class SurveyInfo {
   }
 }
 ----
+====
 
 Once the SurveyInfo has been set on the Customer object above the MongoTemplate that was configured above is used to save the SurveyInfo along with some metadata about the JPA Entity is stored in a MongoDB collection named after the fully qualified name of the JPA Entity class. The following code:
 
-=== Example of code using the JPA Entity configured for cross-store persistence
-
+.Example of code using the JPA Entity configured for cross-store persistence
+====
 [source,java]
 ----
 Customer customer = new Customer();
@@ -225,11 +230,12 @@ SurveyInfo surveyInfo = new SurveyInfo()
 customer.setSurveyInfo(surveyInfo);
 customerRepository.save(customer);
 ----
+====
 
 Executing the code above results in the following JSON document stored in MongoDB.
 
-=== Example of JSON document stored in MongoDB
-
+.Example of JSON document stored in MongoDB
+====
 [source,javascript]
 ----
 { "_id" : ObjectId( "4d9e8b6e3c55287f87d4b79e" ),
@@ -241,3 +247,4 @@ Executing the code above results in the following JSON document stored in MongoD
     "citizenship" : "Norwegian" },
   "_entity_field_class" : "org.springframework.data.mongodb.examples.custsvc.domain.SurveyInfo" }
 ----
+====

src/main/asciidoc/reference/jmx.adoc

@@ -8,8 +8,8 @@ The JMX support for MongoDB exposes the results of executing the 'serverStatus'
 
 Spring's Mongo namespace enables you to easily enable JMX functionality
 
-=== XML schema to configure MongoDB
-
+.XML schema to configure MongoDB
+====
 [source,xml]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
@@ -45,6 +45,7 @@ Spring's Mongo namespace enables you to easily enable JMX functionality
 
 </beans>
 ----
+====
 
 This will expose several MBeans
 

src/main/asciidoc/reference/mapping.adoc

@@ -43,8 +43,8 @@ Unless explicitly configured, an instance of `MongoMappingConverter` is created
 
 You can configure the `MongoMappingConverter` as well as `com.mongodb.Mongo` and MongoTemplate either using Java or XML based metadata. Here is an example using Spring's Java based configuration
 
-=== @Configuration class to configure MongoDB mapping support
-
+.@Configuration class to configure MongoDB mapping support
+====
 [source,java]
 ----
 @Configuration
@@ -83,6 +83,7 @@ public class GeoSpatialAppConfig extends AbstractMongoConfiguration {
   }
 }
 ----
+====
 
 `AbstractMongoConfiguration` requires you to implement methods that define a `com.mongodb.Mongo` as well as provide a database name. `AbstractMongoConfiguration` also has a method you can override named '`getMappingBasePackage`' which tells the converter where to scan for classes annotated with the `@org.springframework.data.mongodb.core.mapping.Document` annotation.
 
@@ -94,8 +95,8 @@ You can also override the method `UserCredentials getUserCredentials()` to provi
 
 Spring's MongoDB namespace enables you to easily enable mapping functionality in XML
 
-=== XML schema to configure MongoDB mapping support
-
+.XML schema to configure MongoDB mapping support
+====
 [source,xml]
 ----
 <?xml version="1.0" encoding="UTF-8"?>
@@ -134,6 +135,7 @@ Spring's MongoDB namespace enables you to easily enable mapping functionality in
 
 </beans>
 ----
+====
 
 The `base-package` property tells it where to scan for classes annotated with the `@org.springframework.data.mongodb.core.mapping.Document` annotation.
 
@@ -142,8 +144,8 @@ The `base-package` property tells it where to scan for classes annotated with th
 
 To take full advantage of the object mapping functionality inside the Spring Data/MongoDB support, you should annotate your mapped objects with the `@org.springframework.data.mongodb.core.mapping.Document` annotation. Although it is not necessary for the mapping framework to have this annotation (your POJOs will be mapped correctly, even without any annotations), it allows the classpath scanner to find and pre-process your domain objects to extract the necessary metadata. If you don't use this annotation, your application will take a slight performance hit the first time you store a domain object because the mapping framework needs to build up its internal metadata model so it knows about the properties of your domain object and how to persist them.
 
-=== Example domain object
-
+.Example domain object
+====
 [source,java]
 ----
 package com.mycompany.domain;
@@ -163,17 +165,18 @@ public class Person {
   private String lastName;
 }
 ----
+====
 
-The `@Id` annotation tells the mapper which property you want to use for the MongoDB `_id` property and the `@Indexed` annotation tells the mapping framework to call `ensureIndex` on that property of your document, making searches faster.
+IMPORTANT: The `@Id` annotation tells the mapper which property you want to use for the MongoDB `_id` property and the `@Indexed` annotation tells the mapping framework to call `ensureIndex` on that property of your document, making searches faster.
 
-Automatic index creation is only done for types annotated with `@Document`.
+IMPORTANT: Automatic index creation is only done for types annotated with `@Document`.
 
 [[mapping-usage-annotations]]
 === Mapping annotation overview
 
 The MappingMongoConverter can use metadata to drive the mapping of objects to documents. An overview of the annotations is provided below
 
-* `@Id `- applied at the field level to mark the field used for identiy purpose.
+* `@Id` - applied at the field level to mark the field used for identiy purpose.
 * `@Document` - applied at the class level to indicate this class is a candidate for mapping to the database. You can specify the name of the collection where the database will be stored.
 * `@DBRef` - applied at the field to indicate it is to be stored using a com.mongodb.DBRef.
 * `@Indexed` - applied at the field level to describe how to index the field.
@@ -292,8 +295,8 @@ NOTE: Compound indexes are very important to improve the performance of queries
 
 Here's an example that creates a compound index of `lastName` in ascending order and `age` in descending order:
 
-==== Example Compound Index Usage
-
+.Example Compound Index Usage
+====
 [source,java]
 ----
 package com.mycompany.domain;
@@ -312,6 +315,7 @@ public class Person {
 
 }
 ----
+====
 
 [[mapping-usage-indexes.text-index]]
 === Text Indexes
@@ -320,8 +324,8 @@ NOTE: The text index feature is disabled by default for mongodb v.2.4.
 
 Creating a text index allows to accumulate several fields into a searchable full text index. It is only possible to have one text index per collection so all fields marked with `@TextIndexed` are combined into this index. Properties can be weighted to influence document score for ranking results. The default language for the text index is english, to change the default language set `@Document(language="spanish")` to any language you want. Using a property called `language` or `@Language` allows to define a language override on a per document base.
 
-==== Example Text Index Usage
-
+.Example Text Index Usage
+====
 [source,java]
 ----
 @Document(language = "spanish")
@@ -340,6 +344,7 @@ class Nested {
     String roo;
 }
 ----
+====
 
 [[mapping-usage-references]]
 === Using DBRefs
@@ -348,6 +353,7 @@ The mapping framework doesn't have to store child objects embedded within the do
 
 Here's an example of using a DBRef to refer to a specific document that exists independently of the object in which it is referenced (both classes are shown in-line for brevity's sake):
 
+====
 [source,java]
 ----
 @Document
@@ -369,10 +375,11 @@ public class Person {
   private List<Account> accounts;
 }
 ----
+====
 
 There's no need to use something like `@OneToMany` because the mapping framework sees that you're wanting a one-to-many relationship because there is a List of objects. When the object is stored in MongoDB, there will be a list of DBRefs rather than the `Account` objects themselves.
 
-The mapping framework does not handle cascading saves. If you change an `Account` object that is referenced by a `Person` object, you must save the Account object separately. Calling `save` on the `Person` object will not automatically save the `Account` objects in the property `accounts`.
+IMPORTANT: The mapping framework does not handle cascading saves. If you change an `Account` object that is referenced by a `Person` object, you must save the Account object separately. Calling `save` on the `Person` object will not automatically save the `Account` objects in the property `accounts`.
 
 [[mapping-usage-events]]
 === Mapping Framework Events