From hibernate-commits at lists.jboss.org Thu Mar 15 13:33:40 2007
Content-Type: multipart/mixed; boundary="===============3080377566130612720=="
MIME-Version: 1.0
From: hibernate-commits at lists.jboss.org
To: hibernate-commits at lists.jboss.org
Subject: [hibernate-commits] Hibernate SVN: r11289 -
 trunk/HibernateExt/annotations/doc/reference/en/modules.
Date: Thu, 15 Mar 2007 13:33:40 -0400
Message-ID: <E1HRtpc-0006Va-2b@committer01.frg.pub.inap.atl.jboss.com>

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

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
=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
--- 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=3D"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=3D"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 stra=
tegy
               used) using <literal>@Persister</literal>: the class must
               implement
-              <classname>org.hibernate.persister.collectionCollectionPersi=
ster</classname>
-              </para>
+              <classname>org.hibernate.persister.collectionCollectionPersi=
ster</classname></para>
             </listitem>
           </itemizedlist></para>
 =

@@ -3269,10 +3274,81 @@
       </sect3>
     </sect2>
 =

+    <sect2 id=3D"entity-hibspec-cascade" xreflabel=3D"Cascade">
+      <title>Cascade</title>
+
+      <para>Hibernate offers more operations than the Java Persistence
+      specification. You can use the <literal>@Cascade</literal> annotatio=
n 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 appli=
ed
+      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 =3D {CascadeType.PERSIST, Cascad=
eType.MERGE} <emphasis
+          role=3D"bold">)
+(a)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=
=3D...)
+      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 configurabl=
e on
       a per entity and per collection basis.</para>
 =



--===============3080377566130612720==--