From c79989ce99fb0700f02b27352b1810f3f483f7e8 Mon Sep 17 00:00:00 2001
From: Thomas Risberg <trisberg@vmware.com>
Date: Mon, 23 May 2011 12:30:04 -0400
Subject: [PATCH] DATADOC-56 added a section documenting _id conversion rules

---
 src/docbkx/reference/mongodb.xml | 55 +++++++++++++++++++++++++++++++-
 1 file changed, 54 insertions(+), 1 deletion(-)

diff --git a/src/docbkx/reference/mongodb.xml b/src/docbkx/reference/mongodb.xml
index 516d4ad10..052fdc586 100644
--- a/src/docbkx/reference/mongodb.xml
+++ b/src/docbkx/reference/mongodb.xml
@@ -142,7 +142,7 @@
 
     <para>The repository is also <ulink
     url="http://shrub.appspot.com/maven.springframework.org/milestone/org/springframework/data/">browseable
-    here</ulink>. </para>
+    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>
@@ -707,6 +707,59 @@ Number of people = : 0</programlisting>
     <para>The query stynax used in the example is explained in more detail in
     the section <link linkend="mongo.query">Querying Documents</link>.</para>
 
+    <section>
+      <title>How the '_id' field is handled in the mapping layer</title>
+
+      <para>Mongo requires that you have an '_id' field for all documents. If
+      you don't provide one the driver will assign a ObjectId with a generated
+      value. When using the <classname>MongoMappingConverter</classname> there
+      are certain rules that govern how properties from the Java class is
+      mapped to this '_id' field. </para>
+
+      <para>The following outlines what property will be mapped to the '_id'
+      field:</para>
+
+      <para><itemizedlist>
+          <listitem>
+            <para>A property or field annotated with
+            <classname>@Id</classname>
+            (<classname>org.springframework.data.annotation.Id</classname>)
+            will be mapped to the '_id' field.</para>
+          </listitem>
+
+          <listitem>
+            <para>A property or field named <classname>id</classname> will be
+            mapped to the '_id' field.</para>
+          </listitem>
+
+          <listitem>
+            <para>A property or field declared as a String in the Java class
+            will be converted to and stored as an ObjectId if possible
+            (conversions and rules would be handled by the Mongo Java driver).
+            If it cannot be converted to an ObjectId, then the value will be
+            stored as a string in the database.</para>
+          </listitem>
+
+          <listitem>
+            <para>A property or field declared as anything but a String in the
+            Java class will be stored as the type it is declared as, which
+            means it must be one of the basic types supported by the Mongo
+            Java driver.</para>
+          </listitem>
+        </itemizedlist></para>
+
+      <para>If no field or property specified above is present in the Java
+      class then an implicit '_id' file will be generated by the driver but
+      not mapped to a property or field of the Java class.</para>
+
+      <para>When querying and updating the <classname>JdbcTemplate</classname>
+      will use the converter to handle conversions of the
+      <classname>Query</classname> and <classname>Update</classname> objects
+      that correspond to the above rules for saving documents so field names
+      and types used in your queries will be able to match what is in your
+      domain classes.</para>
+    </section>
+
     <section>
       <title>Methods for saving and inserting documents</title>