hibernate-commits

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

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

Modified Files:
	advanced_or_mapping.xml basic_or_mapping.xml 
Log Message:
minor changes

Index: advanced_or_mapping.xml
===================================================================
RCS file: /cvsroot/hibernate/Hibernate2/doc/reference/src/advanced_or_mapping.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -C2 -d -r1.12 -r1.13
*** advanced_or_mapping.xml	29 Mar 2003 09:51:27 -0000	1.12
--- advanced_or_mapping.xml	29 Mar 2003 13:31:22 -0000	1.13
***************
*** 48,53 ****
              </para>
  
!             <programlisting><![CDATA[
! Cat cat = new DomesticCat();
  Cat kitten = new DomesticCat();
  ....
--- 48,52 ----
              </para>
  
!             <programlisting><![CDATA[Cat cat = new DomesticCat();
  Cat kitten = new DomesticCat();
  ....
***************
*** 56,59 ****
--- 55,59 ----
  cat.setKittens(kittens);
  session.save(cat);
+ kittens = cat.getKittens(); //Okay, kittens collection is a Set
  (HashSet) cat.getKittens(); //Error!]]></programlisting>
  

Index: basic_or_mapping.xml
===================================================================
RCS file: /cvsroot/hibernate/Hibernate2/doc/reference/src/basic_or_mapping.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -C2 -d -r1.10 -r1.11
*** basic_or_mapping.xml	29 Mar 2003 09:51:27 -0000	1.10
--- basic_or_mapping.xml	29 Mar 2003 13:31:22 -0000	1.11
***************
*** 250,254 ****
              <para>
                  Mapped classes <emphasis>must</emphasis> declare the primary key column of the database 
!                 table. Some classes may also have a JavaBeans-style property holding the unique identifier 
                  of an instance. The <literal>&lt;id&gt;</literal> element defines the mapping from that
                  property to the primary key column.
--- 250,254 ----
              <para>
                  Mapped classes <emphasis>must</emphasis> declare the primary key column of the database 
!                 table. Most classes will also have a JavaBeans-style property holding the unique identifier 
                  of an instance. The <literal>&lt;id&gt;</literal> element defines the mapping from that
                  property to the primary key column.
***************
*** 289,293 ****
                      <callout arearefs="id4">
                          <para>
!                             <literal>unsaved-value</literal> (optional - defaults to <literal>any</literal>): 
                              An identifier property value that indicates that an instance is newly instantiated
                              (unsaved), distinguishing it from transient instances that were saved or loaded
--- 289,293 ----
                      <callout arearefs="id4">
                          <para>
!                             <literal>unsaved-value</literal> (optional - defaults to <literal>null</literal>): 
                              An identifier property value that indicates that an instance is newly instantiated
                              (unsaved), distinguishing it from transient instances that were saved or loaded
***************
*** 304,320 ****
              
              <para>
!                 The <literal>unsaved-value</literal> attribute is required if (only if) you wish to use
!                 the <literal>Session.update()</literal> functionality.
              </para>
  
              <para>
                  The required <literal>&lt;generator&gt;</literal> child element names a Java class used 
                  to generate unique identifiers for instances of the persistent class. If any parameters 
!                 are required to initialize the ID generator, they are passed using the 
!                 <literal>&lt;param&gt;</literal> element. eg:
              </para>
  
!             <programlisting><![CDATA[<id name="id" type="long" column="uid"  unsaved-value="null">
!         <generator class="net.sf.hibernate.id.HiLoGenerator">
                  <param name="table">uid_table</param>
                  <param name="column">next_hi_value_column</param>
--- 304,328 ----
              
              <para>
!                 The <literal>unsaved-value</literal> attribute is important! If the identfier property of your 
!                 class does not default to <literal>null</literal>, then you should specify the actual default.
              </para>
  
+              <para>
+                 There is an alternative <literal>&lt;composite-id&gt;</literal> declaration to allow access to 
+                 legacy data with composite keys. We strongly discourage its use for anything else.
+             </para>
+             
+             <sect3 id="or-mapping-s1-4--generator">
+             <title>generator</title>
+             
              <para>
                  The required <literal>&lt;generator&gt;</literal> child element names a Java class used 
                  to generate unique identifiers for instances of the persistent class. If any parameters 
!                 are required to configure or initialize the generator instance, they are passed using the 
!                 <literal>&lt;param&gt;</literal> element.
              </para>
  
!             <programlisting><![CDATA[<id name="id" type="long" column="uid" unsaved-value="0">
!         <generator class="net.sf.hibernate.id.TableHiLoGenerator">
                  <param name="table">uid_table</param>
                  <param name="column">next_hi_value_column</param>
***************
*** 323,330 ****
  
              <para>
!                 ID generators implement the interface <literal>net.sf.hibernate.id.IdentifierGenerator</literal>. 
                  This is a very simple interface; some applications may choose to provide their own specialized
!                 implementations. However, Hibernate provides a range of built-in implementations.
!                 There are shortcut names for the built-in ID generators:
  
                  <variablelist>
--- 331,338 ----
  
              <para>
!                 All generators implement the interface <literal>net.sf.hibernate.id.IdentifierGenerator</literal>. 
                  This is a very simple interface; some applications may choose to provide their own specialized
!                 implementations. However, Hibernate provides a range of built-in implementations. There are shortcut 
!                 names for the built-in generators:
  
                  <variablelist>
***************
*** 365,372 ****
                                  uses a hi/lo algorithm to efficiently generate identifiers of
                                  type <literal>long</literal>, <literal>short</literal> or <literal>int</literal>, 
!                                 given a table and column (by default "hibernate_unique_key" and "next" 
!                                 respectively) as a source of hi values. The hi/lo algorithm generates identifiers 
!                                 that are unique only for a particular database. <emphasis>Do not use this generator 
!                                 with connections enlisted with JTA or with a user-supplied connection.</emphasis>
                              </para>
                          </listitem>
--- 373,381 ----
                                  uses a hi/lo algorithm to efficiently generate identifiers of
                                  type <literal>long</literal>, <literal>short</literal> or <literal>int</literal>, 
!                                 given a table and column (by default <literal>hibernate_unique_key</literal> and 
!                                 <literal>next</literal> respectively) as a source of hi values. The hi/lo algorithm 
!                                 generates identifiers that are unique only for a particular database. <emphasis>Do not 
!                                 use this generator with connections enlisted with JTA or with a user-supplied 
!                                 connection.</emphasis>
                              </para>
                          </listitem>
***************
*** 376,381 ****
                          <listitem>
                              <para>
!                                 uses a hi/lo algorithm to efficiently generate identifiers of
!                                 type <literal>long</literal>, <literal>short</literal> or <literal>int</literal>, 
                                  given a named database sequence.
                              </para>
--- 385,390 ----
                          <listitem>
                              <para>
!                                 uses a hi/lo algorithm to efficiently generate identifiers of type
!                                 <literal>long</literal>, <literal>short</literal> or <literal>int</literal>, 
                                  given a named database sequence.
                              </para>
***************
*** 423,427 ****
              
              </para>
! 
              <para>
                  The UUIDs contain: IP address, startup time of the JVM (accurate to a quarter
--- 432,455 ----
              
              </para>
!             </sect3>
!             
!             <sect3 id="or-mapping-s1-4-hilo">
!             <title>Hi/Lo Algorithm</title>
!             <para>
!                 The <literal>hilo</literal> and <literal>seqhilo</literal> generators provide two alternate
!                 implementations of the hi/lo algorithm, a favorite approach to identifier generation. The
!                 first implementation requires a "special" database table to hold the next available "hi" value. 
!                 The second uses an Oracle-style sequence (where supported).
!             </para>
!             <para>
!                 Unfortunately, you can't use <literal>hilo</literal> when supplying your own <literal>Connection</literal> 
!                 to Hibernate, or when Hibernate is using an application server datasource to obtain connections 
!                 enlisted with JTA. Hibernate must be able to fetch the "hi" value in a new transaction. A standard
!                 approach in an EJB environment is to implement the hi/lo algorithm using a stateless session bean.
!             </para>
!             </sect3>
!             
!             <sect3 id="or-mapping-s1-4-uuid">
!             <title>UUID Algorithm</title>
              <para>
                  The UUIDs contain: IP address, startup time of the JVM (accurate to a quarter
***************
*** 430,434 ****
--- 458,470 ----
                  the best we can do without using JNI.
              </para>
+             
+             <para>
+                 Don't try to use <literal>uuid.string</literal> in PostgreSQL.
+             </para>
+             
+             </sect3>
  
+             <sect3 id="or-mapping-s1-4-sequences">
+             <title>Identity Columns and Sequences</title>
              <para>
                  For databases which support identity columns (DB2, MySQL, Sybase, MS SQL), you
***************
*** 436,440 ****
                  sequences (DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) you may use
                  <literal>sequence</literal> style key generation. Both these strategies require 
!                 two SQL queries to insert a new object. eg.
              </para>
  
--- 472,476 ----
                  sequences (DB2, Oracle, PostgreSQL, Interbase, McKoi, SAP DB) you may use
                  <literal>sequence</literal> style key generation. Both these strategies require 
!                 two SQL queries to insert a new object.
              </para>
  
***************
*** 448,472 ****
          <generator class="native"/>
  </id>]]></programlisting>
! 
              <para>
                  If you want the application to assign identifiers (as opposed to having
                  Hibernate generate them), you may use the <literal>assigned</literal> generator.
                  This special generator will use the identifier value already assigned to the 
!                 object's identifier property. We hope you won't use this feature to assign keys 
!                 with business meaning (almost always a terrible design decision).
!             </para>
! 
!             <para>
!                 Don't try to use <literal>uuid.string</literal> in PostgreSQL.
!                 Don't try to use <literal>hilo</literal> when supplying your own 
!                 <literal>Connection</literal> to Hibernate, or when Hibernate is
!                 using an application server datasource to obtain connections enlisted with JTA.
!             </para>
! 
!             <para>
!                 There is an alternative <literal>&lt;composite-id&gt;</literal>
!                 declaration to allow access to legacy data with composite keys. We strongly
!                 discourage its use for anything else.
              </para>
          </sect2>
  
--- 484,508 ----
          <generator class="native"/>
  </id>]]></programlisting>
!             
!             <para>
!                 For cross-platform development, the <literal>native</literal> strategy will
!                 choose from the <literal>identity</literal>, <literal>sequence</literal> and
!                 <literal>hilo</literal> strategies, dependant upon the capabalities of the
!                 underlying database.
!             </para>
!             
!             </sect3>
!             
!             <sect3 id="or-mapping-s1-4-assigned">
!             <title>Assigned Identifiers</title>
              <para>
                  If you want the application to assign identifiers (as opposed to having
                  Hibernate generate them), you may use the <literal>assigned</literal> generator.
                  This special generator will use the identifier value already assigned to the 
!                 object's identifier property. Be very careful when using this feature to assign 
!                 keys with business meaning (almost always a terrible design decision).
              </para>
+             </sect3>
+             
          </sect2>