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

[hibernate-commits at lists.jboss.org]

Author: epbernard
Date: 2010-05-07 11:36:30 -0400 (Fri, 07 May 2010)
New Revision: 19407

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

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-07 15:13:09 UTC (rev 19406)
+++ core/trunk/documentation/manual/src/main/docbook/en-US/content/basic_mapping.xml	2010-05-07 15:36:30 UTC (rev 19407)
@@ -2962,8 +2962,20 @@
       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 @@
         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 @@
         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,31 +3088,33 @@
             </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>
             <area coords="2" id="timestamp1" />