[Nhibernate-commit] SF.net SVN: nhibernate:[4612] trunk/nhibernate/doc/reference/modules/ basic_mapping.xml

[<fab...@us...>]

Revision: 4612
          http://nhibernate.svn.sourceforge.net/nhibernate/?rev=4612&view=rev
Author:   fabiomaulo
Date:     2009-07-14 13:12:28 +0000 (Tue, 14 Jul 2009)

Log Message:
-----------
Merge r4611

Modified Paths:
--------------
    trunk/nhibernate/doc/reference/modules/basic_mapping.xml

Modified: trunk/nhibernate/doc/reference/modules/basic_mapping.xml
===================================================================
--- trunk/nhibernate/doc/reference/modules/basic_mapping.xml	2009-07-14 13:11:16 UTC (rev 4611)
+++ trunk/nhibernate/doc/reference/modules/basic_mapping.xml	2009-07-14 13:12:28 UTC (rev 4612)
@@ -1656,7 +1656,45 @@
            <programlisting><![CDATA[<one-to-one name="Employee" class="Employee" property-ref="Person"/>]]></programlisting>
 
         </sect2>
-
+        
+        <sect2 id="mapping-declaration-naturalid">
+            <title>natural-id</title>
+            
+            <programlisting><![CDATA[<natural-id mutable="true|false"/>
+        <property ... />
+        <many-to-one ... />
+        ......
+</natural-id>]]></programlisting>
+            
+            <para>
+                Even though we recommend the use of surrogate keys as primary keys, you should still try
+                to identify natural keys for all entities. A natural key is a property or combination of
+                properties that is unique and non-null. If it is also immutable, even better. Map the
+                properties of the natural key inside the <literal>&lt;natural-id&gt;</literal> element.
+                Hibernate will generate the necessary unique key and nullability constraints, and your
+                mapping will be more self-documenting.
+            </para>
+            
+            <para>
+                We strongly recommend that you implement <literal>Equals()</literal> and
+                <literal>GetHashCode()</literal> to compare the natural key properties of the entity.
+            </para>
+            
+            <para>
+                This mapping is not intended for use with entities with natural primary keys.
+            </para>
+            
+            <itemizedlist spacing="compact">
+                <listitem>
+                    <para>
+                        <literal>mutable</literal> (optional, defaults to <literal>false</literal>):
+                        By default, natural identifier properties as assumed to be immutable (constant).
+                    </para>
+                </listitem>
+            </itemizedlist>
+            
+        </sect2>
+        
         <sect2 id="mapping-declaration-component">
             <title>component, dynamic-component</title>
 


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.