[hibernate-commits] Hibernate SVN: r19618 - core/trunk/documentation/manual/src/main/docbook/en-US/content.

[hibernate-commits at lists.jboss.org]

Author: epbernard
Date: 2010-05-26 12:20:08 -0400 (Wed, 26 May 2010)
New Revision: 19618

Modified:
   core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
Log:
HHH-5149 merge natural id documentation

Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
===================================================================
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml	2010-05-26 16:19:35 UTC (rev 19617)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml	2010-05-26 16:20:08 UTC (rev 19618)
@@ -4515,20 +4515,47 @@
     <section id="mapping-declaration-naturalid">
       <title>Natural-id</title>
 
-      <programlisting role="XML">&lt;natural-id mutable="true|false"/&gt;
-        &lt;property ... /&gt;
-        &lt;many-to-one ... /&gt;
-        ......
-&lt;/natural-id&gt;</programlisting>
-
       <para>Although we recommend the use of surrogate keys as primary keys,
       you should try to identify natural keys for all entities. A natural key
       is a property or combination of properties that is unique and non-null.
-      It is also immutable. Map the properties of the natural key inside the
+      It is also immutable. Map the properties of the natural key as
+      <classname>@NaturalId</classname> or map them inside the
       <literal>&lt;natural-id&gt;</literal> element. Hibernate will generate
       the necessary unique key and nullability constraints and, as a result,
       your mapping will be more self-documenting.</para>
 
+      <programlisting language="JAVA" role="JAVA">@Entity
+public class Citizen {
+    @Id
+    @GeneratedValue
+    private Integer id;
+    private String firstname;
+    private String lastname;
+    
+    @NaturalId
+    @ManyToOne
+    private State state;
+
+    @NaturalId
+    private String ssn;
+    ...
+}
+
+
+
+//and later on query
+List results = s.createCriteria( Citizen.class )
+                .add( Restrictions.naturalId().set( "ssn", "1234" ).set( "state", ste ) )
+                .list();</programlisting>
+
+      <para>Or in XML,</para>
+
+      <programlisting role="XML">&lt;natural-id mutable="true|false"/&gt;
+        &lt;property ... /&gt;
+        &lt;many-to-one ... /&gt;
+        ......
+&lt;/natural-id&gt;</programlisting>
+
       <para>It is recommended that you implement <literal>equals()</literal>
       and <literal>hashCode()</literal> to compare the natural key properties
       of the entity.</para>