[Springnet-commits] Spring.Net/doc/reference/src dbprovider.xml, 1.17, 1.18

[Mark P. <mar...@us...>]

Update of /cvsroot/springnet/Spring.Net/doc/reference/src
In directory sc8-pr-cvs8.sourceforge.net:/tmp/cvs-serv6758

Modified Files:
	dbprovider.xml 
Log Message:
SPRNET-858 - Added IDbProvider implementation, UserCredentialsDbProvider, to allow changing of username, password connection strings at runtime

Index: dbprovider.xml
===================================================================
RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/dbprovider.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -C2 -d -r1.17 -r1.18
*** dbprovider.xml	24 Jan 2008 17:32:36 -0000	1.17
--- dbprovider.xml	29 Jan 2008 18:18:44 -0000	1.18
***************
*** 372,398 ****
    </section>
  
!   <section>
!     <title>MultiDelegatingDbProvider</title>
  
!     <para>There are use-cases in which there will need to be a runtime
!     selection of the database to connect to among many possible candidates.
!     This is often the case where the same schema is installed in separate
!     databases for different clients. The
!     <classname>MultiDelegatingDbProvider</classname> implements the
!     <classname>IDbProvider</classname> interface and provides an abstraction
!     to the multiple databases and can be used in DAO layer such that the DAO
!     layer is unaware of the switching between databases.
!     <classname>MultiDelegatingDbProvider</classname> does its job by looking
!     into thread local storage under the key dbProviderName. This storage
!     location stores the name of the dbProvider that is to be used for
!     processing the request. <classname>MultiDelegatingDbProvider</classname>
!     is configured using the dictionary property
!     <literal>TargetDbProviders</literal>. The key of this dictionary contains
!     the name of a dbProvider and its value is a dbProvider object. During
!     request processing, once you have determined which target dbProvider
!     should be use, in this example database1ProviderName, you should execute
!     the following code <literal>LogicalThreadContext.SetData("dbProviderName",
!     "database1ProviderName")</literal> and then call the data access
!     layer.</para>
    </section>
  </chapter>
\ No newline at end of file
--- 372,454 ----
    </section>
  
!   <section id="dbprovider-additional">
!     <title>Additional IDbProvider implementations</title>
  
!     <para>Spring provides some convenient implementations of the IDbProvider
!     interface that add addtional behavior on top of the standard
!     implementation. </para>
! 
!     <section id="dbprovider-usercredentials">
!       <title>UserCredentialsDbProvider</title>
! 
!       <para>This <classname>UserCredentialsDbProvider</classname> will allow
!       you to change the username and password of a database connection at
!       runtime. The API contains the properties <literal>Username</literal> and
!       <literal>Password</literal> which are used as the default strings
!       representing the user and password in the connection string. You can
!       then change the value of these properties in the connection string by
!       calling the method <literal>SetCredentialsForCurrentThread</literal> and
!       fall back to the default values by calling the method
!       <literal>RemoveCredentialsFromCurrentThread</literal>. You call the
!       <literal>SetCredentialsForCurrentThread</literal> method at runtime,
!       before any data access occurs, to determine which database user should
!       be used for the current user-case. Which user to select is up to you.
!       You may retrieve the user information from an HTTP session for example.
!       Example configuration and usage is shown below</para>
! 
!       <programlisting>&lt;object id="DbProvider" type="Spring.Data.Common.UserCredentialsDbProvider, Spring.Data"&gt;
!   &lt;property name="TargetDbProvider" ref="targetDbProvider"/&gt;
!   &lt;property name="Username" value="User ID=defaultName"/&gt;
!   &lt;property name="Password" value="Password=defaultPass"/&gt;
! &lt;/object&gt;
!  
! &lt;db:provider id="targetDbProvider" provider="SqlServer-2.0"
!     connectionString="Data Source=MARKT60\SQL2005;Database=Spring;Trusted_Connection=False"/&gt;</programlisting>
! 
!       <para>If you use dependency injection to configure a class with a
!       property of the type <literal>IDbProvider</literal>, you will need to
!       downcast to the subtype or you can change your class to have a property
!       of the type <literal>UserCredentialsDbProvider</literal> instead of
!       <literal>IDbProvider</literal>.</para>
! 
!       <programlisting>userCredentialsDbProvider.SetCredentialsForCurrentThread("User ID=springqa", "Password=springqa");</programlisting>
! 
!       <para><literal>UserCredentialsDbProvider's</literal> has a base class,
!       <literal>DelegatingDbProvider</literal>, and is intended for you to use
!       in your own implementations that delegate calls to a target
!       <literal>IDbProvider</literal> instance. This class in meant to be
!       subclassed with subclasses overriding only those methods, such as
!       <literal>CreateConnection()</literal>, that should not simply delegate
!       to the target <literal>IDbProvider</literal>.</para>
!     </section>
! 
!     <section id="dbprovider-multidelegating">
!       <title>MultiDelegatingDbProvider</title>
! 
!       <para>There are use-cases in which there will need to be a runtime
!       selection of the database to connect to among many possible candidates.
!       This is often the case where the same schema is installed in separate
!       databases for different clients. The
!       <classname>MultiDelegatingDbProvider</classname> implements the
!       <classname>IDbProvider</classname> interface and provides an abstraction
!       to the multiple databases and can be used in DAO layer such that the DAO
!       layer is unaware of the switching between databases.
!       <classname>MultiDelegatingDbProvider</classname> does its job by looking
!       into thread local storage under the key dbProviderName. This storage
!       location stores the name of the dbProvider that is to be used for
!       processing the request. <classname>MultiDelegatingDbProvider</classname>
!       is configured using the dictionary property
!       <literal>TargetDbProviders</literal>. The key of this dictionary
!       contains the name of a dbProvider and its value is a dbProvider object.
!       (You can also provide this dictionary as a constructor argument.) During
!       request processing, once you have determined which target dbProvider
!       should be use, in this example database1ProviderName, you should execute
!       the following code
!       <literal>LogicalThreadContext.SetData("dbProviderName",
!       "database1ProviderName")</literal> and then call the data access
!       layer.</para>
! 
!       <para></para>
!     </section>
    </section>
  </chapter>
\ No newline at end of file