[Hibernate-commits] Hibernate2/doc/reference/src basic_or_mapping.xml,1.17,1.18 best_practices.xml,1.2,1.3 manipulating_data.xml,1.8,1.9 transactions.xml,1.5,1.6

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

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

Modified Files:
	basic_or_mapping.xml best_practices.xml manipulating_data.xml 
	transactions.xml 
Log Message:
doco fixes

Index: basic_or_mapping.xml
===================================================================
RCS file: /cvsroot/hibernate/Hibernate2/doc/reference/src/basic_or_mapping.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -C2 -d -r1.17 -r1.18
*** basic_or_mapping.xml	26 Apr 2003 01:42:29 -0000	1.17
--- basic_or_mapping.xml	26 Apr 2003 03:58:29 -0000	1.18
***************
*** 527,532 ****
              <programlisting><![CDATA[<composite-id
          name="propertyName"
!         class="ClassName"
!         unsaved-value="any|none|null">
  
          <key-property name="propertyName" type="typename" column="column_name"/>
--- 527,531 ----
              <programlisting><![CDATA[<composite-id
          name="propertyName"
!         class="ClassName">
  
          <key-property name="propertyName" type="typename" column="column_name"/>
***************
*** 573,585 ****
                          <literal>class</literal> (optional - defaults to the property type determined by 
                          reflection): The component class used as a composite identifier (see next section).
-                     </para>
-                 </listitem>
-                 <listitem>
-                     <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
-                         in a previous session. Once again, this attibute applies only when a component
-                         class is used to represent the composite identifier.
                      </para>
                  </listitem>
--- 572,575 ----

Index: best_practices.xml
===================================================================
RCS file: /cvsroot/hibernate/Hibernate2/doc/reference/src/best_practices.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** best_practices.xml	23 Feb 2003 13:53:24 -0000	1.2
--- best_practices.xml	26 Apr 2003 03:58:29 -0000	1.3
***************
*** 40,44 ****
              <listitem>
                  <para>
- 
                      Deploy the mappings along with the classes they map.
                  </para>
--- 40,43 ----
***************
*** 58,63 ****
              <listitem>
                  <para>
!                      As in JDBC, always replace non-constant
!                     values by "?". Never use string manipulation to bind a non-constant value in a query!
                  </para>
              </listitem>
--- 57,63 ----
              <listitem>
                  <para>
!                      As in JDBC, always replace non-constant values by "?". Never use string manipulation to 
!                      bind a non-constant value in a query! Even better, consider using named parameters in
!                      queries.
                  </para>
              </listitem>
***************
*** 77,83 ****
              <listitem>
                  <para>
!                      Suppose you have a Java type, say
!                     from some library, that needs to be persisted but doesn't provide the accessors
!                     needed to map it as a component. You should consider implementing
                      <literal>net.sf.hibernate.UserType</literal>. This approach frees the application
                      code from implementing transformations to / from a Hibernate type.
--- 77,82 ----
              <listitem>
                  <para>
!                     Suppose you have a Java type, say from some library, that needs to be persisted but doesn't 
!                     provide the accessors needed to map it as a component. You should consider implementing
                      <literal>net.sf.hibernate.UserType</literal>. This approach frees the application
                      code from implementing transformations to / from a Hibernate type.
***************
*** 135,139 ****
                      This is more of a necessary paractice than a "best" practice. When an exception occurs, roll back 
                      the <literal>Transaction</literal> and close the <literal>Session</literal>. If you don't, Hibernate
!                     can't guarantee that in-memory state accurately represents persistent state
                  </para>
              </listitem>
--- 134,164 ----
                      This is more of a necessary paractice than a "best" practice. When an exception occurs, roll back 
                      the <literal>Transaction</literal> and close the <literal>Session</literal>. If you don't, Hibernate
!                     can't guarantee that in-memory state accurately represents persistent state. As a special case of this,
!                     do not use <literal>Session.load()</literal> to determine if an instance with the given identifier 
!                     exists on the database; use <literal>find()</literal> instead.
!                 </para>
!             </listitem>
!         </varlistentry>
!         <varlistentry>
!             <term>Prefer lazy fetching for associations.</term>
!             <listitem>
!                 <para>
!                     Use eager (outer-join) fetching sparingly. Use proxies and/or lazy collections for most associations
!                     to classes that are not cached at the JVM-level. For associations to cached classes, where there is
!                     a high probability of a cache hit, explicitly disable eager fetching using 
!                     <literal>outer-join="false"</literal>. When an outer-join fetch is appropriate to a particular use
!                     case, use a query with a <literal>left join</literal>.
!                 </para>
!             </listitem>
!         </varlistentry>
!         <varlistentry>
!             <term>Consider abstracting your business logic from Hibernate.</term>
!             <listitem>
!                 <para>
!                     Hide (Hibernate) data-access code behind an interface. Combine the <emphasis>DAO</emphasis> and 
!                     <emphasis>Thread Local Session</emphasis> patterns. You can even have some classes persisted by
!                     handcoded JDBC, associated to Hibernate via a <literal>UserType</literal>. (This advice is 
!                     intended for "sufficiently large" applications; it is not appropriate for an application with
!                     five tables!)
                  </para>
              </listitem>

Index: manipulating_data.xml
===================================================================
RCS file: /cvsroot/hibernate/Hibernate2/doc/reference/src/manipulating_data.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -C2 -d -r1.8 -r1.9
*** manipulating_data.xml	22 Apr 2003 20:28:14 -0000	1.8
--- manipulating_data.xml	26 Apr 2003 03:58:29 -0000	1.9
***************
*** 460,464 ****
              <listitem>
                  <para>
!                 <literal>any</literal> - always save (this is the default!)
                  </para>
              </listitem>
--- 460,464 ----
              <listitem>
                  <para>
!                 <literal>any</literal> - always save
                  </para>
              </listitem>
***************
*** 470,474 ****
              <listitem>
                  <para>
!                 <literal>null</literal> - save when identifier is null
                  </para>
              </listitem>
--- 470,474 ----
              <listitem>
                  <para>
!                 <literal>null</literal> - save when identifier is null (this is the default)
                  </para>
              </listitem>

Index: transactions.xml
===================================================================
RCS file: /cvsroot/hibernate/Hibernate2/doc/reference/src/transactions.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** transactions.xml	18 Mar 2003 09:55:27 -0000	1.5
--- transactions.xml	26 Apr 2003 03:58:29 -0000	1.6
***************
*** 258,262 ****
      while ( iter.hasNext() ) {
          Foo foo = (Foo) iter.next();
!         s.lock(foo, LockMode.SHARED);    //check that foo isn't stale
          bar.getFooTable().put( foo.getName(), foo );
      }
--- 258,262 ----
      while ( iter.hasNext() ) {
          Foo foo = (Foo) iter.next();
!         s.lock(foo, LockMode.READ);    //check that foo isn't stale
          bar.getFooTable().put( foo.getName(), foo );
      }