From 5dbf70699ee1c398d9810d5e38be5584e5156d65 Mon Sep 17 00:00:00 2001
From: markpollack <mark.pollack@springsource.com>
Date: Wed, 16 Dec 2009 17:47:42 +0000
Subject: [PATCH] SPRNET-1250  -  Document use of
 'DelegatingLocalSessionFactoryObject' and 'UserCredentialsDbProvider'

---
 doc/reference/src/dbprovider.xml | 70 ++++++++++++++++++--------------
 doc/reference/src/orm.xml        | 13 +++++-
 2 files changed, 52 insertions(+), 31 deletions(-)

diff --git a/doc/reference/src/dbprovider.xml b/doc/reference/src/dbprovider.xml
index 30be6d9d..d88833c2 100644
--- a/doc/reference/src/dbprovider.xml
+++ b/doc/reference/src/dbprovider.xml
@@ -119,14 +119,14 @@
 
     <itemizedlist>
       <listitem>
-        <para><literal>SqlServer-1.1</literal> - Microsoft SQL Server, provider
-        V1.0.5000.0 in framework .NET V1.1</para>
+        <para><literal>SqlServer-1.1</literal> - Microsoft SQL Server,
+        provider V1.0.5000.0 in framework .NET V1.1</para>
       </listitem>
 
       <listitem>
         <para><literal>SqlServer-2.0</literal> (aliased to
-        <literal>System.Data.SqlClient</literal>) - Microsoft SQL Server, provider
-        V2.0.0.0 in framework .NET V2.0</para>
+        <literal>System.Data.SqlClient</literal>) - Microsoft SQL Server,
+        provider V2.0.0.0 in framework .NET V2.0</para>
       </listitem>
 
       <listitem>
@@ -153,8 +153,8 @@
 
       <listitem>
         <para><literal>OracleClient-2.0</literal> (aliased to
-        <literal>System.Data.OracleClient</literal>) - Oracle, Microsoft provider
-        V2.0.0.0</para>
+        <literal>System.Data.OracleClient</literal>) - Oracle, Microsoft
+        provider V2.0.0.0</para>
       </listitem>
 
       <listitem>
@@ -201,7 +201,7 @@
         <para><literal>MySql-5.2.3</literal> - MySQL, MySQL provider
         5.2.3.0</para>
       </listitem>
-      
+
       <listitem>
         <para><literal>MySql-6.1.3</literal> (aliased to
         <literal>MySql.Data.MySqlClient</literal>) - MySQL, MySQL provider
@@ -244,36 +244,35 @@
         <literal>IBM.Data.DB2.9.1.0</literal>) - IBM DB2 Data Provider 9.1.0
         for .NET Framework 2.0</para>
       </listitem>
-      
+
       <listitem>
-        <para><literal>iDB2-10.0.0.0</literal> - IBM iSeries DB2 Data Provider 10.0.0.0 
-        for .NET Framework 2.0</para>
+        <para><literal>iDB2-10.0.0.0</literal> - IBM iSeries DB2 Data Provider
+        10.0.0.0 for .NET Framework 2.0</para>
       </listitem>
 
       <listitem>
-        <para><literal>SQLite-1.0.43</literal> - SQLite provider 1.0.43 for .NET
-        Framework 2.0</para>
-      </listitem>
-      
-      <listitem>
-        <para><literal>SQLite-1.0.44</literal> - SQLite provider 1.0.44 for .NET
-        Framework 2.0</para>
+        <para><literal>SQLite-1.0.43</literal> - SQLite provider 1.0.43 for
+        .NET Framework 2.0</para>
       </listitem>
 
       <listitem>
-        <para><literal>SQLite-1.0.47</literal> - SQLite provider 1.0.47 for .NET
-        Framework 2.0</para>
-      </listitem>
-      
-      <listitem>
-        <para><literal>SQLite-1.0.56</literal> - SQLite provider 1.0.56 for .NET 
-        Framework 2.0</para>
+        <para><literal>SQLite-1.0.44</literal> - SQLite provider 1.0.44 for
+        .NET Framework 2.0</para>
       </listitem>
 
       <listitem>
-        <para><literal>SQLite-1.0.65</literal> (aliased to
-        System.Data.SQLite) - SQLite provider 1.0.65 for .NET Framework
-        2.0</para>
+        <para><literal>SQLite-1.0.47</literal> - SQLite provider 1.0.47 for
+        .NET Framework 2.0</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>SQLite-1.0.56</literal> - SQLite provider 1.0.56 for
+        .NET Framework 2.0</para>
+      </listitem>
+
+      <listitem>
+        <para><literal>SQLite-1.0.65</literal> (aliased to System.Data.SQLite)
+        - SQLite provider 1.0.65 for .NET Framework 2.0</para>
 
         <note>
           <para>The default parameter prefix used in SQLite is : and not @,
@@ -284,7 +283,8 @@
 
       <listitem>
         <para><literal>Firebird-2.1</literal> (aliased to
-        <literal>Firebird-2.1</literal>) - Firebird Server, provider V2.1.0.0 in framework .NET V2.0</para>
+        <literal>Firebird-2.1</literal>) - Firebird Server, provider V2.1.0.0
+        in framework .NET V2.0</para>
       </listitem>
 
       <listitem>
@@ -314,8 +314,8 @@
 
       <listitem>
         <para><literal>Cache-2.0.0.1</literal> (aliased to
-          <literal>InterSystems.Data.CacheClient</literal>) - Cache provider Version 2.0.0.1
-          in framework .NET V2</para>
+        <literal>InterSystems.Data.CacheClient</literal>) - Cache provider
+        Version 2.0.0.1 in framework .NET V2</para>
       </listitem>
     </itemizedlist>
 
@@ -501,6 +501,16 @@
     interface that add addtional behavior on top of the standard
     implementation.</para>
 
+    <note>
+      <para>These provider implementations do not take into account usage with
+      NHibernate. NHibernate scopes a SessionFactory, where second level
+      caching is managed, to each connection. This <link
+      ns6:href="http://forum.springframework.net/showthread.php?t=4462">forum
+      thread</link>, contains an implementation of the class
+      LocalDelegatingSessionFactoryObject that will create multiple
+      SessionFactories for each database connection.</para>
+    </note>
+
     <section xml:id="dbprovider-usercredentials">
       <title>UserCredentialsDbProvider</title>
 
diff --git a/doc/reference/src/orm.xml b/doc/reference/src/orm.xml
index cbde9422..46c15d88 100644
--- a/doc/reference/src/orm.xml
+++ b/doc/reference/src/orm.xml
@@ -395,6 +395,18 @@
         implementation of <literal>MultiDelegatingDbProvider</literal>.</para>
       </note>
 
+      <section>
+        <title>Using FluentNHibernate to configure mappings with
+        LocalSessionFactoryObject</title>
+
+        <para>Direct support for configuration of NHibernate mapping files
+        using FluentNHibernate will be included in a future release. Until
+        then, to see how you can extend LocalSessionFactoryObject to suppport
+        using FluentNHibernate follow the instructions on Benny Michielson's
+        blog post <link
+        ns6:href="http://www.bennymichielsen.be/post/2009/01/04/Using-Fluent-NHibernate-in-SpringNet.aspx">here</link>.</para>
+      </section>
+
       <section xml:id="orm-hibernate-bytecodeprovider">
         <title>Spring's IByteCodeProvider implementation</title>
 
@@ -591,7 +603,6 @@ public class HibernateCustomerDao : ICustomerDao {
       </section>
     </section>
 
-
     <section xml:id="orm-hibernate-tx-declarative">
       <title>Declarative transaction demarcation</title>