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

[hibernate-commits at lists.jboss.org]

Author: epbernard
Date: 2008-03-14 12:20:09 -0400 (Fri, 14 Mar 2008)
New Revision: 14426

Modified:
   annotations/trunk/doc/reference/en/modules/entity.xml
Log:
ANN-610 rewriting of the bidirectional indexed collection example

Modified: annotations/trunk/doc/reference/en/modules/entity.xml
===================================================================
--- annotations/trunk/doc/reference/en/modules/entity.xml	2008-03-14 15:50:34 UTC (rev 14425)
+++ annotations/trunk/doc/reference/en/modules/entity.xml	2008-03-14 16:20:09 UTC (rev 14426)
@@ -2422,9 +2422,10 @@
       attribute.</para>
 
       <para>Contrary to their standard counterpart,
-      <literal>@GenericGenerator</literal> and <literal>@GenericGenerators</literal>
-      can be used in package level annotations, making them application level generators
-      (just like if they were in a JPA XML file).</para>
+      <literal>@GenericGenerator</literal> and
+      <literal>@GenericGenerators</literal> can be used in package level
+      annotations, making them application level generators (just like if they
+      were in a JPA XML file).</para>
 
       <programlisting>@GenericGenerators(
     {
@@ -3049,29 +3050,32 @@
           <para></para>
         </sect4>
 
-        <sect4 id="entity-hibspec-collection-extratype-indexbidir">
+        <sect4 id="entity-hibspec-collection-extratype-indexbidir"
+               revision="2">
           <title>Bidirectional association with indexed collections</title>
 
-          <para>A bidirectional association where one end is represented as a
-          <literal>@IndexColumn</literal> or
-          <literal>@org.hibernate.annotations.MapKey[ManyToMany]</literal>
-          requires special consideration. If there is a property of the child
-          class which maps to the index column, no problem, we can continue
-          using <literal>mappedBy</literal> on the collection mapping:</para>
+          <para>A bidirectional association where one end is an indexed
+          collection (ie. represented as a <literal>@IndexColumn</literal>,
+          <literal>@org.hibernate.annotations.MapKey</literal> or
+          <classname>@org.hibernate.annotations.MapKeyManyToMany</classname>)
+          requires special consideration. If a property on the associated
+          class explicitly maps the indexed value, the use of
+          <methodname>mappedBy</methodname> is permitted:</para>
 
           <programlisting>@Entity
 public class Parent {
     @OneToMany(mappedBy="parent")
-    @org.hibernate.annotations.MapKey(columns=@Column(name="name"))
-    private Map&lt;String, Child&gt; children;
+    @org.hibernate.annotations.IndexColumn(name="order")
+    private List&lt;Child&gt; children;
     ...
 }
 
 @Entity
 public class Child {
     ...
-    @Basic
-    private String name;
+    //the index column is mapped as a property in the associated entity
+    @Column(name="order")
+    private int order;
 
     @ManyToOne
     @JoinColumn(name="parent_id", nullable=false)
@@ -3082,16 +3086,16 @@
           <para>But, if there is no such property on the child class, we can't
           think of the association as truly bidirectional (there is
           information available at one end of the association that is not
-          available at the other end). In this case, we can't map the
-          collection <literal>mappedBy</literal>. Instead, we could use the
-          following mapping:</para>
+          available at the other end: the index). In this case, we can't map
+          the collection as <literal>mappedBy</literal>. Instead, we could use
+          the following mapping:</para>
 
           <programlisting>@Entity
 public class Parent {
     @OneToMany
-    @org.hibernate.annotations.MapKey(columns=@Column(name="name"))
+    @org.hibernate.annotations.IndexColumn(name="order")
     @JoinColumn(name="parent_id", nullable=false)
-    private Map&lt;String, Child&gt; children;
+    private List&lt;Child&gt; children;
     ...
 }
 
@@ -3105,7 +3109,7 @@
 }</programlisting>
 
           <para>Note that in this mapping, the collection-valued end of the
-          association is responsible for updates to the foreign key.</para>
+          association is responsible for updating the foreign key.</para>
         </sect4>
 
         <sect4>