Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

HHH-5149 merge natural id documentation 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@19618 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Emmanuel Bernard 2010-05-26 16:20:08 +00:00
parent d5e59832f2
commit 7c5f43737e
1 changed files with 35 additions and 8 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

43
documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml
View File

@ -4515,20 +4515,47 @@ public long getObjectVolume()</programlisting>
<section id="mapping-declaration-naturalid">
<title>Natural-id</title>
<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 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>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
<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>
<para>It is recommended that you implement <literal>equals()</literal>
and <literal>hashCode()</literal> to compare the natural key properties
of the entity.</para>