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">)
+(a)Cascade({org.hibernate.annotations.CascadeType.SAVE_UPDATE,
+ org.hibernate.annotations.CascadeType.DELETE_ORPHAN})</emphasis>
+public Collection<Employer> 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>