[Springnet-commits] Spring.Net/doc/reference/src index.xml, 1.84, 1.85 transaction.xml, 1.28, 1.29

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

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

Modified Files:
	index.xml transaction.xml 
Log Message:
update programmatic tx docs.

Index: index.xml
===================================================================
RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/index.xml,v
retrieving revision 1.84
retrieving revision 1.85
diff -C2 -d -r1.84 -r1.85
*** index.xml	4 Apr 2008 21:42:11 -0000	1.84
--- index.xml	9 Apr 2008 18:40:10 -0000	1.85
***************
*** 54,58 ****
      <subtitle>Reference Documentation</subtitle>
      <releaseinfo>Version 1.1.1</releaseinfo>
!     <pubdate>Last Updated April 7, 2008</pubdate>
      <authorgroup>
        <author>
--- 54,58 ----
      <subtitle>Reference Documentation</subtitle>
      <releaseinfo>Version 1.1.1</releaseinfo>
!     <pubdate>Last Updated April 9, 2008</pubdate>
      <authorgroup>
        <author>

Index: transaction.xml
===================================================================
RCS file: /cvsroot/springnet/Spring.Net/doc/reference/src/transaction.xml,v
retrieving revision 1.28
retrieving revision 1.29
diff -C2 -d -r1.28 -r1.29
*** transaction.xml	3 Apr 2008 02:36:53 -0000	1.28
--- transaction.xml	9 Apr 2008 18:40:10 -0000	1.29
***************
*** 1711,1715 ****
    </sect1>
  
!   <sect1 id="ptm">
      <title>Programmatic transaction management</title>
  
--- 1711,1715 ----
    </sect1>
  
!   <sect1 id="transaction-programmatic">
      <title>Programmatic transaction management</title>
  
***************
*** 1734,1739 ****
      <classname>TransactionTemplate</classname>)</para>
  
!     <sect2>
!       <title>Using the TransactionTemplate</title>
  
        <para>The TransactionTemplate adopts the same approach as other Spring
--- 1734,1739 ----
      <classname>TransactionTemplate</classname>)</para>
  
!     <sect2 id="tx-prog-template">
!       <title>Using the <classname>TransactionTemplate</classname></title>
  
        <para>The TransactionTemplate adopts the same approach as other Spring
***************
*** 1741,1766 ****
        <classname>HibernateTemplate</classname>. It uses a callback approach,
        to free application code from having to do the boilerplate acquisition
!       and release of resources. Granted that the using construct of
!       System.Transaction alleviates much of this. One key difference with the
!       approach taken with the TransactionTemplate is that a commit is assumed
!       - throwing an exception triggers a rollback instead of using the
!       TransactionScope API to commit or rollback.</para>
! 
!       <para>Like many of the other template classes in Spring, a
!       TransactionTemplate instance is threadsafe.</para>
  
        <para>Application code that must execute in a transaction context looks
!       like this. Note that the
        <interfacename>ITransactionCallback</interfacename> can be used to
        return a value:</para>
  
!       <programlisting>TransactionTemplate tt = new TransactionTemplate(TransactionManager);
  
! string userId = "Stewie";
  
! object result = tt.Execute(delegate {
!                              dao.UpdateOperation(userId);
!                              return dao.UpdateOperation2();
!                            });</programlisting>
  
        <para>This code example is specific to .NET 2.0 since it uses anonymous
--- 1741,1788 ----
        <classname>HibernateTemplate</classname>. It uses a callback approach,
        to free application code from having to do the boilerplate acquisition
!       and release of resources, and results in code that is intention driven,
!       in that the code that is written focuses solely on what the developer
!       wants to do. Granted that the using construct of System.Transaction
!       alleviates much of this. One key difference with the approach taken with
!       the TransactionTemplate is that a commit is assumed - throwing an
!       exception triggers a rollback instead of using the TransactionScope API
!       to commit or rollback. This also allows for the use of rollback rules,
!       that is a commit can still occur for exceptions of certain types. <note>
!           <para>As you will immediately see in the examples that follow, using
!           the <literal>TransactionTemplate</literal> absolutely couples you to
!           Spring's transaction infrastructure and APIs. Whether or not
!           programmatic transaction management is suitable for your development
!           needs is a decision that you will have to make yourself.</para>
!         </note></para>
  
        <para>Application code that must execute in a transaction context looks
!       like this. You, as an application developer, will write a
!       ITransactionCallback implementation (typically expressed as an anonymous
!       delegate) that will contain all of the code that you need to have
!       execute in the context of a transaction. You will then pass an instance
!       of your custom ITransactionCallback to the Execute(..) method exposed on
!       the TransactionTemplate. Note that the
        <interfacename>ITransactionCallback</interfacename> can be used to
        return a value:</para>
  
!       <programlisting>public class SimpleService : IService
! {
!   private TransactionTemplate transactionTemplate;
  
!   public SimpleService(IPlatformTransactionManager transactionManager)
!   {
!      AssertUtils.ArgumentNotNull(transactionManager, "transactionManager");
!      transactionTemplate = new TransactionTemplate(transactionManager);
!   }
  
!   public object SomeServiceMethod()
!   {
!      return tt.Execute(delegate {
!                              UpdateOperation(userId);
!                              return ResultOfUpdateOperation2();
!                        });
!   }
! }
! </programlisting>
  
        <para>This code example is specific to .NET 2.0 since it uses anonymous
***************
*** 1777,1783 ****
        <programlisting>tt.Execute(delegate(ITransactionStatus status)
             {
!              adoTemplate.ExecuteNonQuery(CommandType.Text, "insert into dbo.Debits (DebitAmount) VALUES (@amount)", "amount", DbType.Decimal, 0,555);
!              // decide you need to rollback...
!              status.RollbackOnly = true;
               return null;
             });</programlisting>
--- 1799,1808 ----
        <programlisting>tt.Execute(delegate(ITransactionStatus status)
             {
!              try {
!                UpdateOperation1();
!                UpdateOperation2();
!              } catch (SomeBusinessException ex) {
!                status.RollbackOnly = true;
!              }           
               return null;
             });</programlisting>
***************
*** 1815,1821 ****
        to unit test such classes with a mock or stub
        <interfacename>IPlatformTransactionManager</interfacename>.</para>
      </sect2>
  
!     <sect2>
        <title>Using the PlatformTransactionManager</title>
  
--- 1840,1905 ----
        to unit test such classes with a mock or stub
        <interfacename>IPlatformTransactionManager</interfacename>.</para>
+ 
+       <sect3>
+         <title>Specifying transaction settings</title>
+ 
+         <para>Transaction settings such as the propagation mode, the isolation
+         level, the timeout, and so forth can be set on the
+         <classname>TransactionTemplate</classname> either programmatically or
+         in configuration. <classname>TransactionTemplate</classname> instances
+         by default have the default transactional settings. Find below an
+         example of programmatically customizing the transactional settings for
+         a specific <classname>TransactionTemplate</classname>.</para>
+ 
+         <programlisting>public class SimpleService : IService
+ {
+   private TransactionTemplate transactionTemplate;
+ 
+   public SimpleService(IPlatformTransactionManager transactionManager)
+   {
+      AssertUtils.ArgumentNotNull(transactionManager, "transactionManager");
+      transactionTemplate = new TransactionTemplate(transactionManager);
+ 
+      // the transaction settings can be set here explicitly if so desired
+ 
+      transactionTemplate.TransactionIsolationLevel = IsolationLevel.ReadUncommitted;
+      transactionTemplate.TransactionTimeout = 30;
+ 
+      // and so forth...
+   }
+ 
+   . . .
+ 
+ }
+ 
+ </programlisting>
+ 
+         <para>Find below an example of defining a
+         <classname>TransactionTemplate</classname> with some custom
+         transactional settings, using Spring XML configuration. The
+         '<literal>sharedTransactionTemplate</literal>' can then be injected
+         into as many services as are required.</para>
+ 
+         <programlisting>&lt;object id="sharedTransactionTemplate"
+         type="Spring.Transaction.Support.TransactionTemplate, Sprng.Data"&gt;
+   &lt;property name="TransactionIsolationLevel" value="IsolationLevel.ReadUncommitted"/&gt;
+   &lt;property name="TransactionTimeout" value="30"/&gt;
+ &lt;/object&gt;</programlisting>
+ 
+         <para>Finally, instances of the
+         <classname>TransactionTemplate</classname> class are threadsafe, in
+         that instances do not maintain any conversational state.
+         <classname>TransactionTemplate</classname> instances do however
+         maintain configuration state, so while a number of classes may choose
+         to share a single instance of a
+         <classname>TransactionTemplate</classname>, if a class needed to use a
+         <classname>TransactionTemplate</classname> with different settings
+         (for example, a different isolation level), then two distinct
+         <classname>TransactionTemplate</classname> instances would need to be
+         created and used.</para>
+       </sect3>
      </sect2>
  
!     <sect2 id="transaction-programmatic-ptm">
        <title>Using the PlatformTransactionManager</title>