[hibernate-commits] Hibernate SVN: r11289 - trunk/HibernateExt/annotations/doc/reference/en/modules.

[hibernate-commits at lists.jboss.org]

Author: epbernard
Date: 2007-03-15 13:33:39 -0400 (Thu, 15 Mar 2007)
New Revision: 11289

Modified:
   trunk/HibernateExt/annotations/doc/reference/en/modules/entity.xml
Log:
ANN-574 more precise doc for cascading

Modified: trunk/HibernateExt/annotations/doc/reference/en/modules/entity.xml
===================================================================
--- trunk/HibernateExt/annotations/doc/reference/en/modules/entity.xml	2007-03-15 11:38:45 UTC (rev 11288)
+++ trunk/HibernateExt/annotations/doc/reference/en/modules/entity.xml	2007-03-15 17:33:39 UTC (rev 11289)
@@ -1669,7 +1669,7 @@
         </sect4>
       </sect3>
 
-      <sect3>
+      <sect3 id="entity-mapping-association-cascade">
         <title>Transitive persistence with cascading</title>
 
         <para>You probably have noticed the <literal>cascade</literal>
@@ -1700,6 +1700,12 @@
           </listitem>
         </itemizedlist>
 
+        <note>
+          <para>CascadeType.ALL also covers Hibernate specific operations like
+          save-update, lock etc... Check <xref
+          linkend="entity-hibspec-cascade" /> for more information</para>
+        </note>
+
         <para>Please refer to the chapter 6.3 of the EJB3 specification for
         more information on cascading and create/merge semantics.</para>
       </sect3>
@@ -2933,8 +2939,7 @@
               <para>a custom collection persister (ie the persistence strategy
               used) using <literal>@Persister</literal>: the class must
               implement
-              <classname>org.hibernate.persister.collectionCollectionPersister</classname>
-              </para>
+              <classname>org.hibernate.persister.collectionCollectionPersister</classname></para>
             </listitem>
           </itemizedlist></para>
 
@@ -3269,10 +3274,81 @@
       </sect3>
     </sect2>
 
+    <sect2 id="entity-hibspec-cascade" xreflabel="Cascade">
+      <title>Cascade</title>
+
+      <para>Hibernate offers more operations than the Java Persistence
+      specification. You can use the <literal>@Cascade</literal> annotation to
+      cascade the following operations:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>PERSIST</para>
+        </listitem>
+
+        <listitem>
+          <para>MERGE</para>
+        </listitem>
+
+        <listitem>
+          <para>REMOVE</para>
+        </listitem>
+
+        <listitem>
+          <para>REFRESH</para>
+        </listitem>
+
+        <listitem>
+          <para>DELETE</para>
+        </listitem>
+
+        <listitem>
+          <para>SAVE_UPDATE</para>
+        </listitem>
+
+        <listitem>
+          <para>REPLICATE</para>
+        </listitem>
+
+        <listitem>
+          <para>DELETE_ORPHAN</para>
+        </listitem>
+
+        <listitem>
+          <para>LOCK</para>
+        </listitem>
+
+        <listitem>
+          <para>EVICT</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>This is especially useful for <literal>SAVE_UPDATE</literal>
+      (which is the operation cascaded at flush time if you use plain
+      Hibernate Annotations - Hibernate EntityManager cascade
+      <literal>PERSIST</literal> at flush time as per the specification).
+      DELETE_ORPHAN applies only to <literal>@OneToMany</literal>
+      associations, and indicates that the
+      <methodname>delete()/remove()</methodname> operation should be applied
+      to any child object that is removed from the association. In other
+      words, if a child is dereferenced by a persistent parent and if
+      <literal>DELETE_ORPHAN</literal> is used, the "orphaned" child is
+      deleted.</para>
+
+      <programlisting>@OneToMany( cascade = {CascadeType.PERSIST, CascadeType.MERGE} <emphasis
+          role="bold">)
+ at Cascade({org.hibernate.annotations.CascadeType.SAVE_UPDATE,
+          org.hibernate.annotations.CascadeType.DELETE_ORPHAN})</emphasis>
+public Collection&lt;Employer&gt; getEmployers()</programlisting>
+
+      <para>It is recommended to use @Cascade to compliment @*To*(cascade=...)
+      as shown in the previous example.</para>
+    </sect2>
+
     <sect2>
       <title>Cache</title>
 
-      <para>In order to optimize your database accesses, you can activave the
+      <para>In order to optimize your database accesses, you can activate the
       so called second level cache of Hibernate. This cache is configurable on
       a per entity and per collection basis.</para>