diff --git a/spring-framework-reference/src/transaction.xml b/spring-framework-reference/src/transaction.xml index 67f7c31ef79..43b20f57ca4 100644 --- a/spring-framework-reference/src/transaction.xml +++ b/spring-framework-reference/src/transaction.xml @@ -47,10 +47,10 @@ Framework's transaction support model describes why you would use the Spring Framework's transaction abstraction instead of EJB Container-Managed Transactions - (CMT) or choosing to drive transactions through a proprietary API such - as Hibernate. + (CMT) or choosing to drive local transactions through a proprietary + API such as Hibernate. - + @@ -65,7 +65,7 @@ Synchronizing resources with transactions describes how the application code ensures that resources are created, reused, and cleaned up - properly. + properly. @@ -83,7 +83,7 @@
- Advantages of the Spring Framework's transaction support model<!--Renamed section to make it more to the point.--> + Advantages of the Spring Framework's transaction support model<!--Renamed section to make it more to the point. TR: OK--> Traditionally, Java EE developers have had two choices for transaction management: global or @@ -93,7 +93,7 @@ transaction management support addresses the limitations of the global and local transaction models. - +
Global transactions @@ -152,13 +152,13 @@ programmatic transaction management. Most users prefer declarative transaction management, which is recommended in most cases. - + With programmatic transaction management, developers work with the Spring Framework transaction abstraction, which can run over any underlying transaction infrastructure. With the preferred declarative model, developers typically write little or no code related to transaction management, and hence do not depend on the Spring Framework transaction API, or any other transaction @@ -199,13 +199,14 @@ TR: I think it's fine as is - the concepts apply to both programmatic and declar configuration file, rather than your code, needs to change. +TR: REVISED, PLS REVIEW - changed to say "some of the bean definitions in your configuration file"-->
- Understanding the Spring Framework transaction abstraction<!--If this section applies only to prog. tx management, we should say that up front. Add info? TR: It's relevant for declarative tx as well--> + Understanding the Spring Framework transaction abstraction<!--If this section applies only to prog. tx management, we should say that up front. Add info? +TR: OK AS IS - It's relevant for declarative tx as well--> The key to the Spring transaction abstraction is the notion of a transaction strategy. A transaction strategy is @@ -227,7 +228,7 @@ TR: changed to say "some of the bean definitions in your configuration file"--> can be used programmatically from your application code. Because +TR: REVISED, PLS REVIEW - spelled SPI out and added a bit of clarification at the end-->Because PlatformTransactionManager is an interface, it can be easily mocked or stubbed as necessary. It is not tied to a lookup strategy such as JNDI. @@ -256,7 +257,7 @@ TR: spelled SPI out and added a bit of clarification at the end-->Because transaction exists in the current call stack. The implication in this latter case is that, as with Java EE transaction contexts, a TransactionStatus is associated with a - thread of execution. + thread of execution. The TransactionDefinition interface specifies: @@ -272,9 +273,9 @@ TR: spelled SPI out and added a bit of clarification at the end-->Because Propagation: Typically, all code executed within a transaction scope will run in that transaction. - However, you have options for specifying behavior in the event that a - transactional method is executed when a transaction context already - exists. For + However, you have the option of specifying the behavior in the event + that a transactional method is executed when a transaction context + already exists. For example, code can continue running in the existing transaction (the common case); or the existing transaction can be suspended and a new transaction created. Spring offers all of the transaction @@ -291,10 +292,12 @@ TR: spelled SPI out and added a bit of clarification at the end-->Because Read-only status: A read-only - transaction does not modify any data. + transaction can be used when your code reads but does not modify data. Read-only transactions can be a useful optimization in some cases, - such as when you are using Hibernate. + such as when you are using Hibernate. + + @@ -332,7 +335,7 @@ TR: spelled SPI out and added a bit of clarification at the end-->Because dependency injection. PlatformTransactionManager @@ -365,7 +368,7 @@ TR: spelled SPI out and added a bit of clarification at the end-->Because conjunction with Spring's JtaTransactionManager. This is what the JTA and JNDI lookup version would look like: - + <?xml version="1.0" encoding="UTF-8"?> <beans xmlns="http://www.springframework.org/schema/beans" @@ -448,7 +451,7 @@ TR: spelled SPI out and added a bit of clarification at the end-->Because transactions, then you should simply use the same JtaTransactionManager as in the previous JTA example for JDBC. <bean id="txManager" class="org.springframework.transaction.jta.JtaTransactionManager"/> @@ -482,7 +485,7 @@ TR: spelled SPI out and added a bit of clarification at the end-->Because resources are created, reused, and cleaned up properly. The section also discusses how transaction synchronization is triggered (optionally) through the relevant - PlatformTransactionManager. + PlatformTransactionManager.
High-level synchronization approach @@ -499,7 +502,7 @@ TR: spelled SPI out and added a bit of clarification at the end-->Because access using the JdbcTemplate. All of these solutions are detailed in subsequent chapters of this reference documentation. +TR: REVISED, PLS REVIEW - I re-wrote this to match the current preferred approaches-->
@@ -551,7 +554,9 @@ TR: I re-wrote this to match the current preferred approaches--> occurs behind the scenes and you won't need to write any special code. - +
@@ -563,7 +568,8 @@ TR: I re-wrote this to match the current preferred approaches--> wraps the target DataSource to add awareness of Spring-managed transactions. In this respect, it is similar to a transactional JNDI DataSource as - provided by a Java EE server. + provided by a Java EE server. It should almost never be necessary or desirable to use this class, except when existing code must be called and passed a standard @@ -602,7 +608,8 @@ TR: I re-wrote this to match the current preferred approaches--> Unlike EJB CMT, which is tied to JTA, the Spring Framework's declarative transaction management works in any environment. It can work with JTA transactions or local transactions using JDBC, JPA, - Hibernate or JDO by simple adjusting the configuration files. + Hibernate or JDO by simple adjusting the configuration files. @@ -653,7 +660,7 @@ TR: I re-wrote this to match the current preferred approaches--> The concept of rollback rules is important: they enable you to - specify which exceptions (and throwables) should + specify which exceptions (and throwables) should cause automatic rollback. You specify this declaratively, in configuration, not in Java code. So, although you can still call setRollbackOnly()on the @@ -674,7 +681,8 @@ TR: I re-wrote this to match the current preferred approaches--> EJB convention (roll back is automatic only on unchecked exceptions), it is often useful to customize this behavior. - +
Understanding the Spring Framework's declarative transaction @@ -706,7 +714,8 @@ TR: I re-wrote this to match the current preferred approaches--></para> <para>Conceptually, calling a method on a transactional proxy looks like this...</para> - <!--I don't see this image in src file or in pdf. Maybe it was added to src after pdf was created?--> + <!--I don't see this image in src file or in pdf. Maybe it was added to src after pdf was created? +TR: OK AS IS - images don't show up in the editor, but they do show up in the generated docs--> <para><mediaobject> <imageobject role="fo"> @@ -901,7 +910,8 @@ public class DefaultFooService implements FooService { <para>The above configuration will be used to create a transactional proxy around the object that is created from the - <literal>fooService</literal> bean definition. <!--Clarify what you mean by around the object; do you mean associated with the object? Revise to clarify. Around is vague.-->The + <literal>fooService</literal> bean definition. <!--Clarify what you mean by around the object; do you mean associated with the object? Revise to clarify. Around is vague. +TR: OK AS IS - around is used a lot in AOP, so I think the audience will understand this usage-->The proxy will be configured with the transactional advice, so that when an appropriate method is invoked <emphasis>on the proxy</emphasis>, a transaction is started, suspended, marked as read-only, and so on, @@ -973,7 +983,7 @@ Exception in thread "main" java.lang.UnsupportedOperationException configuration, will catch any unhandled <exceptionname>Exception</exceptionname> as it bubbles up the call stack, and mark the transaction for rollback.<!--I changed to *can be configured* because next sentence says it does not do this by default in all cases. -TR: I changed it to *in its default configuration*--></para> +TR: REVISED, PLS REVIEW - I changed it to *in its default configuration*--></para> <para>However, the Spring Framework's transaction infrastructure code, by default, <emphasis>only</emphasis> mark a transaction for rollback in @@ -984,7 +994,7 @@ TR: I changed it to *in its default configuration*--></para> in a rollback). Checked exceptions that are thrown from a transactional method do <emphasis>not</emphasis> result in rollback.<!--I revised preceding because it says ONLY first case is rolled back by default, but then says Errors are also marked by default. -TR: Errors aren't thrown by application code, only checked or unchecked exceptions are. So the Errors part is just clarifying that +TR: OK AS IS - Errors aren't thrown by application code, only checked or unchecked exceptions are. So the Errors part is just clarifying that if the underlying application server infrastructure throws an Error the transaction will be rolled back--></para> <para>You can configure exactly which @@ -1406,10 +1416,12 @@ public class DefaultFooService implements FooService { <interfacename>@Transactional</interfacename> annotation is not enough to activate the transactional behavior. The <interfacename>@Transactional</interfacename> annotation is simply - metadata that can be consumed by something<!--Please identify *something* .--> - that is <interfacename>@Transactional</interfacename>-aware and that can - use the metadata to configure the appropriate beans with transactional - behavior. In the preceding example, the + metadata that can be consumed by something<!--Please identify *something* . +TR: OK AS IS - it's not defined what this something is - could be code written by the user or could be an +existing BeanPostProcessor provided or something else--> that is + <interfacename>@Transactional</interfacename>-aware and that can use the + metadata to configure the appropriate beans with transactional behavior. + In the preceding example, the <literal><tx:annotation-driven/></literal> element <emphasis>switches on</emphasis> the transactional behavior.</para> @@ -1440,8 +1452,9 @@ public class DefaultFooService implements FooService { <interfacename>@Transactional</interfacename>.</para> </note> - <para>Consider the use of AspectJ mode (see below) if you expect - self-invocations to be wrapped with transactions as well. <!--*see below* is not clear re AspectJmode. Provide clear x-ref to mode in table below, or to Using Transactional with AspectJ section. Also clarify reference to *as well*. As well as what?--><!--Below, *in this case* meaning in *what* case? Explain what table shows.-->In + <para>Consider the use of AspectJ mode (see mode attribute in table + below) if you expect self-invocations to be wrapped with transactions as + well. <!--*see below* is not clear re AspectJmode. Provide clear x-ref to mode in table below, or to Using Transactional with AspectJ section. Also clarify reference to *as well*. As well as what?--><!--Below, *in this case* meaning in *what* case? Explain what table shows. TR: REVISED, PLS REVIEW-->In this case, there will not be a proxy in the first place; instead, the target class will be weaved (that is, its byte code will be modified) in order to turn <interfacename>@Transactional</interfacename> into runtime @@ -1547,12 +1560,13 @@ public class DefaultFooService implements FooService { <interfacename>WebApplicationContext</interfacename> for a <classname>DispatcherServlet</classname>, it only checks for <interfacename>@Transactional</interfacename> beans in your - controllers, and not your services. <!--I don't understand the logic of preceding explanation. Also identify *it* in first sentence of Note.-->See - <xref linkend="mvc-servlet" /> for more information.</para> + controllers, and not your services. <!--I don't understand the logic of preceding explanation. Also identify *it* in first sentence of Note. +TR: OK AS IS - "it" refers to <tx:annotation-driven/>-->See <xref + linkend="mvc-servlet" /> for more information.</para> </note> <para>The most derived location takes precedence when evaluating the - transactional settings for a method. <!--Do you need to clarify what *most derived* location means? Lowest level?-->In + transactional settings for a method. <!--Do you need to clarify what *most derived* location means? Lowest level? TR: OK AS IS - following sentence explains it-->In the case of the following example, the <classname>DefaultFooService</classname> class is annotated at the class level with the settings for a read-only transaction, but the @@ -1610,7 +1624,7 @@ public class DefaultFooService implements FooService { <listitem> <para>Any <exceptionname>RuntimeException</exceptionname> triggers rollback, and any checked <exceptionname>Exception</exceptionname> - does not.<!--Bullet list above does not exactly map to properties in table.ok?--></para> + does not.<!--Bullet list above does not exactly map to properties in table.ok? TR: OK AS IS--></para> </listitem> </itemizedlist> @@ -1720,8 +1734,8 @@ public class DefaultFooService implements FooService { shown in a transaction monitor, if applicable (for example, WebLogic's transaction monitor), and in logging output. For declarative transactions, the transaction name is always the fully-qualified class - name + "." + <!--Meaning of symbols is unclear.-->method name of the - transactionally-advised class. For example, if the + name + "." + <!--Meaning of symbols is unclear. TR: OK AS IS - means concatenation and it would be clear to any programmer reading the docs-->method + name of the transactionally-advised class. For example, if the <methodname>handlePayment(..)</methodname> method of the <classname>BusinessService</classname> class started a transaction, the name of the transaction would be: @@ -1733,7 +1747,7 @@ public class DefaultFooService implements FooService { <title>Transaction propagation +TR: REVISED, PLS REVIEW - changed it back; it's not just settings, the section discusses propagation in general as well as the settings--> This section describes some semantics of transaction propagation in Spring. Please note that this section is not an introduction to @@ -1764,11 +1778,11 @@ TR: changed it back; it's not just settings, the section discusses propagation i transaction scope can determine rollback-only status individually, with an outer transaction scope being logically independent from the inner transaction scope. Of course, in case of standard - PROPAGATION_REQUIRED behavior, all these scopes + PROPAGATION_REQUIRED behavior, all these scopes will be mapped to the same physical transaction. So a rollback-only marker set in the inner transaction scope does affect the outer transaction's chance to actually commit (as you would expect it - to). + to). However, in the case where an inner transaction scope sets the rollback-only marker, the outer transaction has not decided on the @@ -1822,7 +1836,7 @@ TR: changed it back; it's not just settings, the section discusses propagation i
- Advising transactional operations<!--Need better heading? Executing transactional advice?--> + Advising transactional operations<!--Need better heading? Executing transactional advice? TR: OK AS IS--> Suppose you want to execute both transactional and some basic profiling advice. How @@ -1830,7 +1844,7 @@ TR: changed it back; it's not just settings, the section discusses propagation i <tx:annotation-driven/>? When you invoke the updateFoo(Foo) - method, you want to see the following actions: + method, you want to see the following actions: @@ -1863,7 +1877,7 @@ TR: changed it back; it's not just settings, the section discusses propagation i Here is the code for a simple profiling aspect discussed above. - The + The ordering of advice is controlled through the Ordered interface. For full details on advice ordering, see The result of the above configuration is a fooService bean that has profiling and transactional aspects applied to it in the desired order. You +TR: REVISED, PLS REVIEW - changed to 'desired'; seems clear that the desired order is profiling first followed by transactional aspect-->You configure any number of additional aspects in similar fashion. The following example effects the same setup as above, but uses @@ -2016,7 +2030,7 @@ TR: changed to 'desired'; seems clear that the desired order is profiling first transactional advice on the way in, and before the transactional advice on the way out, then you simply swap the value of the profiling aspect bean's order property so that it - is higher than the transactional advice's order value. + is higher than the transactional advice's order value. You configure additional aspects in similar fashion.
@@ -2383,7 +2397,7 @@ txManager.commit(status); Use the correct PlatformTransactionManager implementation - based on your choice of transactional technologies and requirements. + based on your choice of transactional technologies and requirements. Used properly, the Spring Framework merely provides a straightforward and portable abstraction. If you are using global transactions, you must use the