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

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&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>