[Hibernate-commits] Hibernate2/doc/reference/src advanced_or_mapping.xml,1.5,1.6

[<one...@us...>]

Update of /cvsroot/hibernate/Hibernate2/doc/reference/src
In directory sc8-pr-cvs1:/tmp/cvs-serv9067/reference/src

Modified Files:
	advanced_or_mapping.xml 
Log Message:
improved collections doco

Index: advanced_or_mapping.xml
===================================================================
RCS file: /cvsroot/hibernate/Hibernate2/doc/reference/src/advanced_or_mapping.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** advanced_or_mapping.xml	16 Jan 2003 08:56:02 -0000	1.5
--- advanced_or_mapping.xml	17 Jan 2003 08:38:05 -0000	1.6
***************
*** 7,11 ****
  
          <sect2 id="adv-or-mapping-s1-1">
!             <title>Persistent Collection Styles</title>
  
              <para>
--- 7,11 ----
  
          <sect2 id="adv-or-mapping-s1-1">
!             <title>Persistent Collections</title>
  
              <para>
***************
*** 28,31 ****
--- 28,32 ----
                  may also be persisted with "bag" semantics.
              </para>
+             
              <para>
                  Now the caveat: persistent collections do not retain any extra semantics added by the class 
***************
*** 65,72 ****
  
              <para>
!                 Collections may contain any other Hibernate type. All collection types except
!                 <literal>Set</literal> and bag have an <emphasis>index</emphasis> - an array or list 
!                 index or map key. The index of a <literal>Map</literal> may be of any basic type, an 
!                 entity type or even a composite type (it may not be a collection).
              </para>
  
--- 66,93 ----
  
              <para>
!                 Collection instances are distinguished in the database by a foreign key to
!                 the owning entity. This foreign key is referred to as the <emphasis>collection key
!                 </emphasis> (Collections may not contain other collections). The collection key
!                 is mapped by the <literal>&lt;key&gt;</literal> element.
!             </para>
! 
!             <para>
!                 Collections may contain almost any other Hibernate type, including all basic types,
!                 custom types, entity types and components. Collections may not contain other
!                 collections. The contained type is referred to as the emphasis>collection element
!                 type</emphasis>. Collection elements are mapped by using <literal>&lt;element&gt;</literal>,
!                 <literal>&lt;composite-element&gt;</literal>, <literal>&lt;one-to-many&gt;</literal> or
!                 <literal>&lt;many-to-many&gt;</literal>.
!             </para>
!             </para>
!             
!             <para>
!                 All collection types except <literal>Set</literal> and bag have an <emphasis>index
!                 </emphasis> column - a column that maps to an array or <literal>List</literal> index or 
!                 <literal>Map</literal> key. The index of a <literal>Map</literal> may be of any 
!                 basic type, an entity type or even a composite type (it may not be a collection). The
!                 index of an array or list is always of type <literal>integer</literal>. Indexes are
!                 mapped using <literal>&lt;index&gt;</literal>, <literal>&lt;index-many-to-many&gt;</literal>
!                 or <literal>&lt;composite-index&gt;</literal>.
              </para>
  
***************
*** 77,90 ****
                  translate to database tables.
              </para>
-         </sect2>
- 
- 
-         <sect2 id="adv-or-mapping-s1-2">
-             <title>Collections Keys</title>
- 
-             <para>
-                 Collection instances are distinguished in the database by a foreign key to
-                 the owning object. (Hence collections may not contain other collections.)
-             </para>
  
          </sect2>
--- 98,101 ----
***************
*** 110,113 ****
--- 121,125 ----
      schema="schema_name
      lazy="true|false"
+     inverse="true|false"
      cascade="all|none|save-update|delete"
      sort="unsorted|natural|comparatorClass"
***************
*** 145,148 ****
--- 157,166 ----
                  <listitem>
                      <para>
+                         <literal>inverse</literal> (optional - defaults to <literal>false</literal>)
+                         mark this collection as the "inverse" end of a bidirectional association
+                     </para>
+                 </listitem>
+                 <listitem>
+                     <para>
                          <literal>cascade</literal> (optional - defaults to <literal>none</literal>)
                          enable operations to cascade to child entities (not used for toplevel
***************
*** 170,178 ****
  
              <para>
!                 Most collection roles require a table of their own. This includes any collection
!                 of values and any collection of entities that has the natural semantics for a
!                 Java collection. The table requires an identifier column, an element column (or
!                 column<emphasis>s</emphasis> if it is a collection of components) and possibly
!                 an index column.
              </para>
  
--- 188,194 ----
  
              <para>
!                 A collection table is required for any collection of values and any collection of entities 
!                 mapped as a many-to-many association (the natural semantics for a Java collection). The 
!                 table requires identifier column(s), element column(s) and possibly index column(s).
              </para>
  
***************
*** 180,184 ****
                  A collection of entities with its own table corresponds to the relational notion
                  of <emphasis>many-to-many association</emphasis>. A many to many association is the 
!                 most natural mapping of a Java collection but is not always the best relational model.
              </para>
  
--- 196,200 ----
                  A collection of entities with its own table corresponds to the relational notion
                  of <emphasis>many-to-many association</emphasis>. A many to many association is the 
!                 most natural mapping of a Java collection but is not usually the best relational model.
              </para>