Update of /cvsroot/springframework/spring/docs/reference/src
In directory sc8-pr-cvs8.sourceforge.net:/tmp/cvs-serv19803/docs/reference/src
Modified Files:
aop-api.xml
Log Message:
Minor edits.
Index: aop-api.xml
===================================================================
RCS file: /cvsroot/springframework/spring/docs/reference/src/aop-api.xml,v
retrieving revision 1.7
retrieving revision 1.8
diff -C2 -d -r1.7 -r1.8
*** aop-api.xml 6 Aug 2006 17:43:26 -0000 1.7
--- aop-api.xml 7 Aug 2006 07:16:42 -0000 1.8
***************
*** 563,567 ****
the introduction: that is, if the invoked method is on an introduced
interface, the introduction interceptor is responsible for handling
! the method call--it cannot invoke <literal>proceed()</literal>.</para>
--- 563,567 ----
the introduction: that is, if the invoked method is on an introduced
interface, the introduction interceptor is responsible for handling
! the method call - it cannot invoke <literal>proceed()</literal>.</para>
***************
*** 723,727 ****
<para>The introduction advisor required is simple. All it needs to do
is hold a distinct <literal>LockMixin</literal> instance, and specify
! the introduced interfaces--in this case, just
<literal>Lockable</literal>. A more complex example might take a
reference to the introduction interceptor (which would be defined as a
--- 723,727 ----
<para>The introduction advisor required is simple. All it needs to do
is hold a distinct <literal>LockMixin</literal> instance, and specify
! the introduced interfaces - in this case, just
<literal>Lockable</literal>. A more complex example might take a
reference to the introduction interceptor (which would be defined as a
***************
*** 788,798 ****
<para>If you're using the Spring IoC container (an ApplicationContext or
! BeanFactory) for your business objects--and you should be!--you will want
to use one of Spring's AOP FactoryBeans. (Remember that a factory bean
introduces a layer of indirection, enabling it to create objects of a
different type).</para>
! <remark>The Spring 2.0 AOP support also uses factory beans under the covers.</remark>
!
<para>The basic way to create an AOP proxy in Spring is to use the
<emphasis>org.springframework.aop.framework.ProxyFactoryBean</emphasis>.
--- 788,800 ----
<para>If you're using the Spring IoC container (an ApplicationContext or
! BeanFactory) for your business objects - and you should be! - you will want
to use one of Spring's AOP FactoryBeans. (Remember that a factory bean
introduces a layer of indirection, enabling it to create objects of a
different type).</para>
! <note>
! <para>The Spring 2.0 AOP support also uses factory beans under the covers.</para>
! </note>
!
<para>The basic way to create an AOP proxy in Spring is to use the
<emphasis>org.springframework.aop.framework.ProxyFactoryBean</emphasis>.
***************
*** 810,819 ****
<literal>foo</literal> see is not the
<literal>ProxyFactoryBean</literal> instance itself, but an object
! created by the <literal>ProxyFactoryBean's</literal> implementation of
the <literal>getObject() </literal>method. This method will create an
AOP proxy wrapping a target object.</para>
<para>One of the most important benefits of using a
! <literal>ProxyFactoryBean</literal> or other IoC-aware class to create
AOP proxies, is that it means that advices and pointcuts can also be
managed by IoC. This is a powerful feature, enabling certain approaches
--- 812,821 ----
<literal>foo</literal> see is not the
<literal>ProxyFactoryBean</literal> instance itself, but an object
! created by the <literal>ProxyFactoryBean</literal>'s implementation of
the <literal>getObject() </literal>method. This method will create an
AOP proxy wrapping a target object.</para>
<para>One of the most important benefits of using a
! <literal>ProxyFactoryBean</literal> or another IoC-aware class to create
AOP proxies, is that it means that advices and pointcuts can also be
managed by IoC. This is a powerful feature, enabling certain approaches
***************
*** 850,854 ****
<para>
<literal>proxyTargetClass</literal>: <literal>true</literal> if the
! target class is to be proxied, rather than the target class' interfaces.
If this property value is set to <literal>true</literal>, then CGLIB proxies
will be created (but see also below the section entitled
--- 852,856 ----
<para>
<literal>proxyTargetClass</literal>: <literal>true</literal> if the
! target class is to be proxied, rather than the target class's interfaces.
If this property value is set to <literal>true</literal>, then CGLIB proxies
will be created (but see also below the section entitled
***************
*** 936,941 ****
method is called. Several <interfacename>FactoryBean</interfacename>
implementations offer such a method. The default value is
! <literal>true</literal>. If you want to use stateful advice --
! for example, for stateful mixins -- use prototype advices along
with a singleton value of <literal>false</literal>.
</para>
--- 938,943 ----
method is called. Several <interfacename>FactoryBean</interfacename>
implementations offer such a method. The default value is
! <literal>true</literal>. If you want to use stateful advice -
! for example, for stateful mixins - use prototype advices along
with a singleton value of <literal>false</literal>.
</para>
***************
*** 965,970 ****
referred to as the target class) doesn't implement any interfaces, then
a CGLIB-based proxy will be created. This is the easiest scenario, because
! JDK proxies are interface based, and no interfaces means no JDK proxying
! is even possible. One simply plugs in the target bean, and specifies the
list of interceptors via the <literal>interceptorNames</literal> property.
Note that a CGLIB-based proxy will be created even if the
--- 967,972 ----
referred to as the target class) doesn't implement any interfaces, then
a CGLIB-based proxy will be created. This is the easiest scenario, because
! JDK proxies are interface based, and no interfaces means JDK proxying
! isn't even possible. One simply plugs in the target bean, and specifies the
list of interceptors via the <literal>interceptorNames</literal> property.
Note that a CGLIB-based proxy will be created even if the
***************
*** 1074,1085 ****
significant.</para>
! <remark>You might be wondering why the list doesn't hold bean
! references. The reason for this is that if the ProxyFactoryBean's
! singleton property is set to false, it must be able to return
! independent proxy instances. If any of the advisors is itself a
! prototype, an independent instance would need to be returned, so it's
! necessary to be able to obtain an instance of the prototype from the
! factory; holding a reference isn't sufficient.</remark>
!
<para>The "person" bean definition above can be used in place of a
Person implementation, as follows:</para>
--- 1076,1089 ----
significant.</para>
! <note>
! <para>You might be wondering why the list doesn't hold bean
! references. The reason for this is that if the ProxyFactoryBean's
! singleton property is set to false, it must be able to return
! independent proxy instances. If any of the advisors is itself a
! prototype, an independent instance would need to be returned, so it's
! necessary to be able to obtain an instance of the prototype from the
! factory; holding a reference isn't sufficient.</para>
! </note>
!
<para>The "person" bean definition above can be used in place of a
Person implementation, as follows:</para>
***************
*** 1177,1181 ****
<listitem>
<para>You'll need the CGLIB 2 binaries on your classpath; dynamic
! proxies are available with the JDK</para>
</listitem>
</itemizedlist>
--- 1181,1185 ----
<listitem>
<para>You'll need the CGLIB 2 binaries on your classpath; dynamic
! proxies are available with the JDK.</para>
</listitem>
</itemizedlist>
***************
*** 1234,1238 ****
definition, which to wraps the target of the proxy as an inner bean
definition, since the target will never be used on its own
! anyways.<programlisting><bean id="myService" parent="txProxyTemplate">
<property name="target">
<bean class="org.springframework.samples.MyServiceImpl">
--- 1238,1242 ----
definition, which to wraps the target of the proxy as an inner bean
definition, since the target will never be used on its own
! anyway.<programlisting><bean id="myService" parent="txProxyTemplate">
<property name="target">
<bean class="org.springframework.samples.MyServiceImpl">
***************
*** 1287,1291 ****
MyBusinessInterface tb = (MyBusinessInterface) factory.getProxy();</programlisting></para>
! <para>The first step is to construct a object of type
<literal>org.springframework.aop.framework.ProxyFactory</literal>. You can
create this with a target object, as in the above example, or specify the
--- 1291,1295 ----
MyBusinessInterface tb = (MyBusinessInterface) factory.getProxy();</programlisting></para>
! <para>The first step is to construct an object of type
<literal>org.springframework.aop.framework.ProxyFactory</literal>. You can
create this with a target object, as in the above example, or specify the
***************
*** 1298,1308 ****
<para>There are also convenience methods on ProxyFactory (inherited from
! AdvisedSupport) allowing you to add other advice types such as before and
! throws advice. AdvisedSupport is the superclass of both ProxyFactory and
! ProxyFactoryBean.</para>
! <remark>Integrating AOP proxy creation with the IoC framework is best
! practice in most applications. We recommend that you externalize
! configuration from Java code with AOP, as in general.</remark>
</section>
--- 1302,1314 ----
<para>There are also convenience methods on ProxyFactory (inherited from
! <classname>AdvisedSupport</classname>) allowing you to add other advice types
! such as before and throws advice. AdvisedSupport is the superclass of both
! ProxyFactory and ProxyFactoryBean.</para>
! <tip>
! <para>Integrating AOP proxy creation with the IoC framework is best
! practice in most applications. We recommend that you externalize
! configuration from Java code with AOP, as in general.</para>
! </tip>
</section>
***************
*** 1350,1354 ****
Advisor. Usually the advisor holding pointcut and advice will be the
generic <literal>DefaultPointcutAdvisor</literal>, which can be used with
! any advice or pointcut (but not for introduction).</para>
<para>By default, it's possible to add or remove advisors or interceptors
--- 1356,1360 ----
Advisor. Usually the advisor holding pointcut and advice will be the
generic <literal>DefaultPointcutAdvisor</literal>, which can be used with
! any advice or pointcut (but not for introductions).</para>
<para>By default, it's possible to add or remove advisors or interceptors
***************
*** 1378,1391 ****
oldAdvisorCount + 2, advised.getAdvisors().length);</programlisting></para>
! <remark>It's questionable whether it's advisable (no pun intended) to
! modify advice on a business object in production, although there are no
! doubt legitimate usage cases. However, it can be very useful in
! development: for example, in tests. I have sometimes found it very useful
! to be able to add test code in the form of an interceptor or other advice,
! getting inside a method invocation I want to test. (For example, the
! advice can get inside a transaction created for that method: for example,
! to run SQL to check that a database was correctly updated, before marking
! the transaction for roll back.)</remark>
!
<para>Depending on how you created the proxy, you can usually set a
<literal>frozen</literal> flag, in which case the
--- 1384,1399 ----
oldAdvisorCount + 2, advised.getAdvisors().length);</programlisting></para>
! <note>
! <para>It's questionable whether it's advisable (no pun intended) to
! modify advice on a business object in production, although there are no
! doubt legitimate usage cases. However, it can be very useful in
! development: for example, in tests. I have sometimes found it very useful
! to be able to add test code in the form of an interceptor or other advice,
! getting inside a method invocation I want to test. (For example, the
! advice can get inside a transaction created for that method: for example,
! to run SQL to check that a database was correctly updated, before marking
! the transaction for roll back.)</para>
! </note>
!
<para>Depending on how you created the proxy, you can usually set a
<literal>frozen</literal> flag, in which case the
***************
*** 1393,1397 ****
return true, and any attempts to modify advice through addition or removal
will result in an <literal>AopConfigException</literal>. The ability to
! freeze the state of an advised object is useful in some cases: For
example, to prevent calling code removing a security interceptor. It may
also be used in Spring 1.1 to allow aggressive optimization if runtime
--- 1401,1405 ----
return true, and any attempts to modify advice through addition or removal
will result in an <literal>AopConfigException</literal>. The ability to
! freeze the state of an advised object is useful in some cases
example, to prevent calling code removing a security interceptor. It may
also be used in Spring 1.1 to allow aggressive optimization if runtime
***************
*** 1420,1424 ****
<listitem>
<para>Using an autoproxy creator that refers to specific beans in the
! current context</para>
</listitem>
--- 1428,1432 ----
<listitem>
<para>Using an autoproxy creator that refers to specific beans in the
! current context.</para>
</listitem>
***************
*** 1426,1430 ****
<para>A special case of autoproxy creation that deserves to be
considered separately; autoproxy creation driven by source-level
! metadata attributes</para>
</listitem>
</itemizedlist>
--- 1434,1438 ----
<para>A special case of autoproxy creation that deserves to be
considered separately; autoproxy creation driven by source-level
! metadata attributes.</para>
</listitem>
</itemizedlist>
***************
*** 1452,1456 ****
<para>As with <literal>ProxyFactoryBean</literal>, there is an
! interceptorNames property rather than a list of interceptor, to allow
correct behavior for prototype advisors. Named "interceptors" can be
advisors or any advice type.</para>
--- 1460,1464 ----
<para>As with <literal>ProxyFactoryBean</literal>, there is an
! <literal>interceptorNames</literal> property rather than a list of interceptor, to allow
correct behavior for prototype advisors. Named "interceptors" can be
advisors or any advice type.</para>
***************
*** 1488,1492 ****
<para>Specifying a
<literal>DefaultAdvisorAutoProxyCreator</literal> bean
! definition</para>
</listitem>
--- 1496,1500 ----
<para>Specifying a
<literal>DefaultAdvisorAutoProxyCreator</literal> bean
! definition.</para>
</listitem>
***************
*** 1537,1541 ****
you can simply add new business objects without including specific
proxy configuration. You can also drop in additional aspects very
! easily--for example, tracing or performance monitoring aspects--with
minimal change to configuration.</para>
--- 1545,1549 ----
you can simply add new business objects without including specific
proxy configuration. You can also drop in additional aspects very
! easily - for example, tracing or performance monitoring aspects - with
minimal change to configuration.</para>
***************
*** 1547,1551 ****
interface to ensure correct ordering if this is an issue. The
TransactionAttributeSourceAdvisor used in the above example has a
! configurable order value; default is unordered.</para>
</section>
--- 1555,1559 ----
interface to ensure correct ordering if this is an issue. The
TransactionAttributeSourceAdvisor used in the above example has a
! configurable order value; the default setting is unordered.</para>
</section>
***************
*** 1654,1663 ****
class="org.springframework.transaction.jta.JtaTransactionManager"/></programlisting>
! <remark>If you require only declarative transaction management, using
! these generic XML definitions will result in Spring automatically
! proxying all classes or methods with transaction attributes. You won't
! need to work directly with AOP, and the programming model is similar to
! that of .NET ServicedComponents.</remark>
!
<para>This mechanism is extensible. It's possible to do autoproxying
based on custom attributes. You need to:</para>
--- 1662,1673 ----
class="org.springframework.transaction.jta.JtaTransactionManager"/></programlisting>
! <tip>
! <para>If you require only declarative transaction management, using
! these generic XML definitions will result in Spring automatically
! proxying all classes or methods with transaction attributes. You won't
! need to work directly with AOP, and the programming model is similar to
! that of .NET ServicedComponents.</para>
! </tip>
!
<para>This mechanism is extensible. It's possible to do autoproxying
based on custom attributes. You need to:</para>
***************
*** 1730,1737 ****
how you can use them.</para>
! <remark>When using a custom target source, your target will usually need
! to be a prototype rather than a singleton bean definition. This allows
! Spring to create a new target instance when required.</remark>
!
<section id="aop-ts-swap">
<title>Hot swappable target sources</title>
--- 1740,1749 ----
how you can use them.</para>
! <tip>
! <para>When using a custom target source, your target will usually need
! to be a prototype rather than a singleton bean definition. This allows
! Spring to create a new target instance when required.</para>
! </tip>
!
<section id="aop-ts-swap">
<title>Hot swappable target sources</title>
***************
*** 1769,1774 ****
target.</para>
! <para>Although this example doesn't add any advice--and it's not
! necessary to add advice to use a <literal>TargetSource</literal>--of
course any <literal>TargetSource</literal> can be used in conjunction
with arbitrary advice.</para>
--- 1781,1786 ----
target.</para>
! <para>Although this example doesn't add any advice - and it's not
! necessary to add advice to use a <literal>TargetSource</literal> - of
course any <literal>TargetSource</literal> can be used in conjunction
with arbitrary advice.</para>
***************
*** 1811,1816 ****
</bean></programlisting></para>
! <para>Note that the target object--"businessObjectTarget" in the
! example--<emphasis>must</emphasis> be a prototype. This allows the
<literal>PoolingTargetSource</literal> implementation to create new
instances of the target to grow the pool as necessary. See the Javadoc
--- 1823,1828 ----
</bean></programlisting></para>
! <para>Note that the target object - "businessObjectTarget" in the
! example - <emphasis>must</emphasis> be a prototype. This allows the
<literal>PoolingTargetSource</literal> implementation to create new
instances of the target to grow the pool as necessary. See the Javadoc
***************
*** 1848,1856 ****
System.out.println("Max pool size is " + conf.getMaxSize());]]></programlisting>
! <remark>Pooling stateless service objects is not usually necessary. We
! don't believe it should be the default choice, as most stateless objects
! are naturally thread safe, and instance pooling is problematic if
! resources are cached.</remark>
!
<para>Simpler pooling is available using autoproxying. It's possible to
set the TargetSources used by any autoproxy creator.</para>
--- 1860,1870 ----
System.out.println("Max pool size is " + conf.getMaxSize());]]></programlisting>
! <note>
! <para>Pooling stateless service objects is not usually necessary. We
! don't believe it should be the default choice, as most stateless objects
! are naturally thread safe, and instance pooling is problematic if
! resources are cached.</para>
! </note>
!
<para>Simpler pooling is available using autoproxying. It's possible to
set the TargetSources used by any autoproxy creator.</para>
***************
*** 1895,1910 ****
</bean>]]></programlisting>
! <para><emphasis>ThreadLocals come with serious issues (potentially
! resulting in memory leaks) when incorrectly using them in a
! multi-threaded and multi-classloader environments. One should always
! consider wrapping a threadlocal in some other class and never directly
! use the <classname>ThreadLocal</classname> itself (except of course in the wrapper class).
! Also, one should always remember to correctly set and unset (where the
! latter simply involved a call to <literal>ThreadLocal.set(null)</literal>) the resource
! local to the thread. Unsetting should be done in any case since not
! unsetting it might result in problematic behavior. Spring's ThreadLocal
! support is doing this for you and should always be considered in favor
! of using ThreadLocals without other proper handling
! code.</emphasis></para>
</section>
</section>
--- 1909,1926 ----
</bean>]]></programlisting>
! <note>
! <para>ThreadLocals come with serious issues (potentially
! resulting in memory leaks) when incorrectly using them in a
! multi-threaded and multi-classloader environments. One should always
! consider wrapping a threadlocal in some other class and never directly
! use the <classname>ThreadLocal</classname> itself (except of course in the wrapper class).
! Also, one should always remember to correctly set and unset (where the
! latter simply involved a call to <literal>ThreadLocal.set(null)</literal>) the resource
! local to the thread. Unsetting should be done in any case since not
! unsetting it might result in problematic behavior. Spring's ThreadLocal
! support does this for you and should always be considered in favor
! of using ThreadLocals without other proper handling
! code.</para>
! </note>
</section>
</section>
***************
*** 1927,1931 ****
<para>Please refer to the
<literal>org.springframework.aop.framework.adapter</literal> package's
! Javadocs for further information</para>
</section>
--- 1943,1947 ----
<para>Please refer to the
<literal>org.springframework.aop.framework.adapter</literal> package's
! Javadocs for further information.</para>
</section>
***************
*** 1940,1949 ****
<para>The JPetStore's default configuration illustrates the use of the
<classname>TransactionProxyFactoryBean</classname> for declarative transaction
! management</para>
</listitem>
<listitem>
<para>The <literal>/attributes</literal> directory of the JPetStore
! illustrates the use of attribute-driven declarative transaction management</para>
</listitem>
</itemizedlist>
--- 1956,1965 ----
<para>The JPetStore's default configuration illustrates the use of the
<classname>TransactionProxyFactoryBean</classname> for declarative transaction
! management.</para>
</listitem>
<listitem>
<para>The <literal>/attributes</literal> directory of the JPetStore
! illustrates the use of attribute-driven declarative transaction management.</para>
</listitem>
</itemizedlist>
|