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

HHH-5149 documentation for versioning 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@19407 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Emmanuel Bernard 2010-05-07 15:36:30 +00:00
parent 12d44898a5
commit 8f4401349f
1 changed files with 41 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -2962,8 +2962,20 @@ public class Cat implements Serializable {
for good scalability and works particularly well in read-often
write-sometimes situations.</para>
<para>You can use two approaches: a dedicated version number or a
timestamp.</para>
<para>A version or timestamp property should never be null for a
detached instance. Hibernate will detect any instance with a null
version or timestamp as transient, irrespective of what other
<literal>unsaved-value</literal> strategies are specified.
<emphasis>Declaring a nullable version or timestamp property is an easy
way to avoid problems with transitive reattachment in Hibernate. It is
especially useful for people using assigned identifiers or composite
keys</emphasis>.</para>
<section id="entity-mapping-entity-version">
<title>Versioning for optimistic locking</title>
<title>Version number</title>
<para>You can add optimistic locking capability to an entity using the
<literal>@Version</literal> annotation:</para>
@ -2981,9 +2993,8 @@ public class Flight implements Serializable {
to detect conflicting updates (preventing lost updates you might
otherwise see with the last-commit-wins strategy).</para>
<para>The version column may be a numeric (the recommended solution)
or a timestamp. Hibernate supports any kind of type provided that you
define and implement the appropriate
<para>The version column may be a numeric. Hibernate supports any kind
of type provided that you define and implement the appropriate
<classname>UserVersionType</classname>.</para>
<para>The application must not alter the version number set up by
@ -2991,15 +3002,12 @@ public class Flight implements Serializable {
check in Hibernate Entity Manager's reference documentation
<literal>LockModeType.OPTIMISTIC_FORCE_INCREMENT</literal> or
<literal>LockModeType.PESSIMISTIC_FORCE_INCREMENT</literal>.</para>
</section>
<section id="mapping-declaration-version" revision="4">
<title>Version</title>
<para>If the version number is generated by the database (via a
trigger for example), make sure to use
<code>@org.hibernate.annotations.Generated(GenerationTime.ALWAYS).</code></para>
<para>The <literal>&lt;version&gt;</literal> element is optional and
indicates that the table contains versioned data. This is particularly
useful if you plan to use <emphasis>long transactions</emphasis>. See
below for more information:</para>
<para>To declare a version property in hbm.xml, use:</para>
<programlistingco role="XML">
<areaspec>
@ -3080,30 +3088,32 @@ public class Flight implements Serializable {
</callout>
</calloutlist>
</programlistingco>
<para>Version numbers can be of Hibernate type
<literal>long</literal>, <literal>integer</literal>,
<literal>short</literal>, <literal>timestamp</literal> or
<literal>calendar</literal>.</para>
<para>A version or timestamp property should never be null for a
detached instance. Hibernate will detect any instance with a null
version or timestamp as transient, irrespective of what other
<literal>unsaved-value</literal> strategies are specified.
<emphasis>Declaring a nullable version or timestamp property is an
easy way to avoid problems with transitive reattachment in Hibernate.
It is especially useful for people using assigned identifiers or
composite keys</emphasis>.</para>
</section>
<section id="mapping-declaration-timestamp" revision="4">
<title>Timestamp (optional)</title>
<title>Timestamp</title>
<para>The optional <literal>&lt;timestamp&gt;</literal> element
indicates that the table contains timestamped data. This provides an
alternative to versioning. Timestamps are a less safe implementation
of optimistic locking. However, sometimes the application might use
the timestamps in other ways.</para>
<para>Alternatively, you can use a timestamp. Timestamps are a less
safe implementation of optimistic locking. However, sometimes the
application might use the timestamps in other ways.</para>
<para>Simply mark a property of type <classname>Date</classname> or
<classname>Calendar</classname> as
<classname>@Version</classname>.</para>
<programlisting language="JAVA" role="JAVA">@Entity
public class Flight implements Serializable {
...
@Version
public Date getLastUpdate() { ... }
} </programlisting>
<para>Like version numbers, the timestamp can be generated by the
database instead of Hibernate. To do that, use
<code>@org.hibernate.annotations.Generated(GenerationTime.ALWAYS).</code></para>
<para>In hbm.xml, use the <literal>&lt;timestamp&gt;</literal>
element:</para>
<programlistingco role="XML">
<areaspec>