From hibernate-commits at lists.jboss.org Wed May 26 12:20:09 2010
Content-Type: multipart/mixed; boundary="===============3025756651068096387=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r19618 -
 core/trunk/documentation/manual/src/main/docbook/en-US/content.
Date: Wed, 26 May 2010 12:20:09 -0400
Message-ID: <201005261620.o4QGK9lA022817@svn01.web.mwc.hst.phx2.redhat.com>

--===============3025756651068096387==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

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_map=
ping.xml
Log:
HHH-5149 merge natural id documentation

Modified: core/trunk/documentation/manual/src/main/docbook/en-US/content/ba=
sic_mapping.xml
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_ma=
pping.xml	2010-05-26 16:19:35 UTC (rev 19617)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_ma=
pping.xml	2010-05-26 16:20:08 UTC (rev 19618)
@@ -4515,20 +4515,47 @@
     <section id=3D"mapping-declaration-naturalid">
       <title>Natural-id</title>
 =

-      <programlisting role=3D"XML">&lt;natural-id mutable=3D"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 key=
s,
       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-nu=
ll.
-      It is also immutable. Map the properties of the natural key inside t=
he
+      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 genera=
te
       the necessary unique key and nullability constraints and, as a resul=
t,
       your mapping will be more self-documenting.</para>
 =

+      <programlisting language=3D"JAVA" role=3D"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 =3D s.createCriteria( Citizen.class )
+                .add( Restrictions.naturalId().set( "ssn", "1234" ).set( "=
state", ste ) )
+                .list();</programlisting>
+
+      <para>Or in XML,</para>
+
+      <programlisting role=3D"XML">&lt;natural-id mutable=3D"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()</litera=
l>
       and <literal>hashCode()</literal> to compare the natural key propert=
ies
       of the entity.</para>


--===============3025756651068096387==--