root
/
spring-framework
mirror of https://github.com/spring-projects/spring-framework.git
1
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

Document @Enable* annotations 

Update reference manual with details of Java configuration @Enable*
annotations. Examples of Java style @Configuration is provided
when appropriate alongside existing XML samples.

Several existing @Configuration samples have been changed to placing
the @Enable annotation below the @Configuration annotation.
This has been done to provide consistency with existing Javadoc.

Issue: SPR-9920
This commit is contained in:
Phillip Webb 2012-11-20 12:09:44 -08:00
parent da50a0213b
commit 59b27004de
9 changed files with 415 additions and 275 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

165
src/reference/docbook/aop.xml
View File

@ -327,27 +327,46 @@
automatically generate a proxy for that bean to intercept method
invocations and ensure that advice is executed as needed.</para>
<para>The @AspectJ support is enabled by including the following element
inside your spring configuration:</para>
<para>The @AspectJ support can be enabled with XML or Java style
configuration. In either case you will also need to ensure that
AspectJ's <filename class="libraryfile">aspectjrt.jar</filename>
library is on the classpath of your application (version 1.6.8 or later).
This library is available in the <filename class="directory">'lib'</filename>
directory of an AspectJ distribution or via the Maven Central repository.</para>
<programlisting language="xml">&lt;aop:aspectj-autoproxy/&gt;</programlisting>
<section id="aop-enable-aspectj-java">
<title>Enabling @AspectJ Support with Java configuration</title>
<para>This assumes that you are using schema support as described in
<xref linkend="xsd-config" />. See <xref
linkend="xsd-config-body-schemas-aop" /> for how to import the tags in
the aop namespace.</para>
<para>To enable @AspectJ support with Java
<interfacename>@Configuration</interfacename> add the
<interfacename>@EnableAspectJAutoProxy</interfacename> annotation:</para>
<para>If you are using the DTD, it is still possible to enable @AspectJ
support by adding the following definition to your application
context:</para>
<programlisting language="java">@Configuration
@EnableAspectJAutoProxy
public class AppConfig {
<programlisting language="xml">&lt;bean class="org.springframework.aop.aspectj.annotation.AnnotationAwareAspectJAutoProxyCreator" /&gt;</programlisting>
}</programlisting>
</section>
<para>You will also need AspectJ's
<filename class="libraryfile">aspectjrt.jar</filename> library on the
classpath of your application, version 1.6.8 or later. This library is
available in the <filename class="directory">'lib'</filename> directory
of an AspectJ distribution or via the Maven Central repository.</para>
<section id="aop-enable-aspectj-xml">
<title>Enabling @AspectJ Support with XML configuration</title>
<para>To enable @AspectJ support with XML based configuration use the
<literal>aop:aspectj-autoproxy</literal> element:</para>
<programlisting language="xml">&lt;aop:aspectj-autoproxy/&gt;</programlisting>
<para>This assumes that you are using schema support as described in
<xref linkend="xsd-config" />. See <xref
linkend="xsd-config-body-schemas-aop" /> for how to import the tags in
the aop namespace.</para>
<para>If you are using the DTD, it is still possible to enable @AspectJ
support by adding the following definition to your application
context:</para>
<programlisting language="xml">&lt;bean class="org.springframework.aop.aspectj.annotation.AnnotationAwareAspectJAutoProxyCreator" /&gt;</programlisting>
</section>
</section>
<section id="aop-at-aspectj">
@ -2929,10 +2948,21 @@ public class Account {
linkend="aop-aj-ltw"/>). The
<classname>AnnotationBeanConfigurerAspect</classname> itself needs
configuring by Spring (in order to obtain a reference to the bean
factory that is to be used to configure new objects). The Spring <link
factory that is to be used to configure new objects). If you are
using Java based configuration simply add
<interfacename>@EnableSpringConfigured</interfacename> to any
<interfacename>@Configuration</interfacename> class.</para>
<programlisting language="java">@Configuration
@EnableSpringConfigured
public class AppConfig {
}</programlisting>
<para>If you prefer XML based configuration, the Spring <link
linkend="xsd-config-body-schemas-context"><literal>context</literal>
namespace</link> defines a convenient tag for doing this: just include
the following in your application context configuration:</para>
namespace</link> defines a convenient
<literal>context:spring-configured</literal> element:</para>
<programlisting language="xml">&lt;context:spring-configured/&gt;</programlisting>
@ -3000,7 +3030,7 @@ public class Account {
there is one aspect instance per classloader that defines the type.
This means that if you define multiple application contexts within the
same classloader hierarchy you need to consider where to define the
<literal>&lt;context:spring-configured/&gt;</literal> bean and where to
<interfacename>@EnableSpringConfigured</interfacename> bean and where to
place <filename class="libraryfile">spring-aspects.jar</filename> on
the classpath.</para>
@ -3011,7 +3041,7 @@ public class Account {
these contexts will co-exist within the same classloader hierarchy,
and so the <literal>AnnotationBeanConfigurerAspect</literal> can only
hold a reference to one of them. In this case we recommend defining
the <literal>&lt;context:spring-configured/&gt;</literal> bean in the
the <interfacename>@EnableSpringConfigured</interfacename> bean in the
shared (parent) application context: this defines the services that
you are likely to want to inject into domain objects. A consequence is
that you cannot configure domain objects with references to beans
@ -3199,6 +3229,16 @@ public class Account {
finer-grained profiling tool to that specific area immediately
afterwards.</para>
<note>
<para>The example presented here uses XML style configuration, it is
also possible to configure and use @AspectJ with
<link linkend="beans-java">Java Configuration</link>.
Specifically the <interfacename>@EnableLoadTimeWeaving</interfacename>
annotation can be used as an alternative to
<literal>&lt;context:load-time-weaver/&gt;</literal>
(see <link linkend="aop-aj-ltw-spring">below</link> for details).</para>
</note>
<para>Here is the profiling aspect. Nothing too fancy, just a
quick-and-dirty time-based profiler, using the @AspectJ-style of
aspect declaration.</para>
@ -3477,7 +3517,7 @@ public final class Main {
</tip>
<para>Configuring a <interfacename>LoadTimeWeaver</interfacename>
using XML for a particular
for a particular
<interfacename>ApplicationContext</interfacename> can be as easy as
adding one line. (Please note that you almost certainly will need to
be using an <interfacename>ApplicationContext</interfacename> as your
@ -3489,9 +3529,17 @@ public final class Main {
<para>To enable the Spring Framework's LTW support, you need to
configure a <interfacename>LoadTimeWeaver</interfacename>, which
typically is done using the
<literal>&lt;context:load-time-weaver/&gt;</literal> element. Find
below a valid <literal>&lt;context:load-time-weaver/&gt;</literal>
definition that uses default settings.</para>
<interfacename>@EnableLoadTimeWeaving</interfacename> annotation.</para>
<programlisting language="java">@Configuration
@EnableLoadTimeWeaving
public class AppConfig {
}</programlisting>
<para>Alternatively, if you prefer XML based configuration, use the
<literal>&lt;context:load-time-weaver/&gt;</literal> element. Note
that the element is defined in the '<literal>context</literal>' namespace.</para>
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
@ -3507,19 +3555,11 @@ http://www.springframework.org/schema/context
&lt;/beans&gt;</programlisting>
<para>The above <literal>&lt;context:load-time-weaver/&gt;</literal>
bean definition will define and register a number of LTW-specific
infrastructure beans for you automatically, such as a
<interfacename>LoadTimeWeaver</interfacename> and an
<classname>AspectJWeavingEnabler</classname>. Notice how the
<literal>&lt;context:load-time-weaver/&gt;</literal> is defined in the
'<literal>context</literal>' namespace; note also that the referenced
XML Schema file is only available in versions of Spring 2.5 and
later.</para>
<para>What the above configuration does is define and register a
default <interfacename>LoadTimeWeaver</interfacename> bean for you.
The default <interfacename>LoadTimeWeaver</interfacename> is the
<para>The above configuration will define and register a number of
LTW-specific infrastructure beans for you automatically, such
as a <interfacename>LoadTimeWeaver</interfacename> and an
<classname>AspectJWeavingEnabler</classname>. The default
<interfacename>LoadTimeWeaver</interfacename> is the
<classname>DefaultContextLoadTimeWeaver</classname> class, which
attempts to decorate an automatically detected
<interfacename>LoadTimeWeaver</interfacename>: the exact type of
@ -3595,12 +3635,26 @@ http://www.springframework.org/schema/context
when using the <classname>DefaultContextLoadTimeWeaver</classname>: it
is of course possible to specify exactly which
<interfacename>LoadTimeWeaver</interfacename> implementation that you
wish to use by specifying the fully-qualified classname as the value
of the '<literal>weaver-class</literal>' attribute of the
<literal>&lt;context:load-time-weaver/&gt;</literal> element. Find
below an example of doing just that:</para>
wish to use.</para>
<para>To specify a specific <interfacename>LoadTimeWeaver</interfacename>
with Java configuration implement the
<interfacename>LoadTimeWeavingConfigurer</interfacename> interface and override
the <literal>getLoadTimeWeaver()</literal> method:</para>
<programlisting language="java">@Configuration
@EnableLoadTimeWeaving
public class AppConfig implements LoadTimeWeavingConfigurer {
@Override
public LoadTimeWeaver getLoadTimeWeaver() {
return new ReflectiveLoadTimeWeaver();
}
}</programlisting>
<para>If you are using XML based configuration you can specify the fully-qualified
classname as the value of the '<literal>weaver-class</literal>' attribute on the
<literal>&lt;context:load-time-weaver/&gt;</literal> element:</para>
<!-- removed <emphasis> below to solve NPE problem -->
<programlisting language="xml">&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
@ -3617,8 +3671,7 @@ http://www.springframework.org/schema/context
&lt;/beans&gt;</programlisting>
<para>The <interfacename>LoadTimeWeaver</interfacename> that is
defined and registered by the
<literal>&lt;context:load-time-weaver/&gt;</literal> element can be
defined and registered by the configuration can be
later retrieved from the Spring container using the well-known name
'<literal>loadTimeWeaver</literal>'. Remember that the
<interfacename>LoadTimeWeaver</interfacename> exists just as a
@ -3632,41 +3685,45 @@ http://www.springframework.org/schema/context
details, because the specifics of how the weaving is actually effected
is beyond the scope of this section.</para>
<para>There is one final attribute of the
<literal>&lt;context:load-time-weaver/&gt;</literal> left to discuss:
the '<literal>aspectj-weaving</literal>' attribute. This is a simple
<para>There is one final attribute of the configuration left to discuss:
the '<literal>aspectjWeaving</literal>' attribute
(or '<literal>aspectj-weaving</literal>' if you are using XML). This is a simple
attribute that controls whether LTW is enabled or not, it is as simple
as that. It accepts one of three possible values, summarised below,
with the default value if the attribute is not present being '
<literal>autodetect</literal>'</para>
with the default value if the attribute is not present being
'<literal>autodetect</literal>'</para>
<table id="aop-aj-ltw-ltw-tag-attrs" pgwide="1">
<title>'<literal>aspectj-weaving</literal>' attribute values</title>
<title>AspectJ weaving attribute values</title>
<tgroup cols="2">
<tgroup cols="3">
<colspec align="left" />
<thead>
<row>
<entry>Attribute Value</entry>
<entry>Annotation Value</entry>
<entry>XML Value</entry>
<entry>Explanation</entry>
</row>
</thead>
<tbody>
<row>
<entry><para><literal>ENABLED</literal></para></entry>
<entry><para><literal>on</literal></para></entry>
<entry><para>AspectJ weaving is on, and aspects will be woven
at load-time as appropriate.</para></entry>
</row>
<row>
<entry><para><literal>DISABLED</literal></para></entry>
<entry><para><literal>off</literal></para></entry>
<entry><para>LTW is off... no aspect will be woven at
load-time.</para></entry>
</row>
<row>
<entry><para><literal>AUTODETECT</literal></para></entry>
<entry><para><literal>autodetect</literal></para></entry>
<entry><para>If the Spring LTW infrastructure can find at
least one '<filename>META-INF/aop.xml</filename>' file, then
@ -3809,7 +3866,7 @@ TR: REVISED, PLS REVIEW. Chnaged the last one to *inside*--> is recommended
Oracle Containers for Java EE (OC4J 10.1.3.1 and above), Resin (3.1 and above) and JBoss (5.x or above)
provide a ClassLoader that is capable of local instrumentation.
Spring's native LTW leverages such ClassLoaders to enable AspectJ weaving.
You can enable LTW by simply activating <literal>context:load-time-weaver</literal>
You can enable LTW by simply activating load-time weaving
as described earlier. Specifically, you do <emphasis>not</emphasis>
need to modify the launch script to add
<literal>-javaagent:path/to/spring-instrument.jar</literal>.</para>

21
src/reference/docbook/beans.xml
View File

@ -953,18 +953,25 @@ List userList = service.getUsernameList();
<section id="context-load-time-weaver">
<title>Registering a <interfacename>LoadTimeWeaver</interfacename></title>
<para>The <literal>context</literal> namespace introduced in Spring 2.5
provides a <literal>load-time-weaver</literal>
element.<!--Need to explain purpose of LoadTimeWeaver? Is this section ok here? --></para>
<para>The <interfacename>LoadTimeWeaver</interfacename> is used by Spring to dynamically
transform classes as they are loaded into the Java virtual machine (JVM).</para>
<para>To enable load-time weaving add the <interfacename>@EnableLoadTimeWeaving</interfacename>
to one of your <interfacename>@Configuration</interfacename> classes:</para>
<programlisting language="java">@Configuration
@EnableLoadTimeWeaving
public class AppConfig {
}</programlisting>
<para>Alternatively for XML configuration use the <literal>context:load-time-weaver</literal> element:</para>
<programlisting language="xml">&lt;beans&gt;
&lt;context:load-time-weaver/&gt;
&lt;/beans&gt;</programlisting>
<para>Adding this element to an XML-based Spring configuration file
activates a Spring <interfacename>LoadTimeWeaver</interfacename> for the
<para>Once configured for the
<interfacename>ApplicationContext</interfacename>. Any bean within that
<interfacename>ApplicationContext</interfacename> may implement
<interfacename>LoadTimeWeaverAware</interfacename>, thereby receiving a

31
src/reference/docbook/cache.xml
View File

@ -273,8 +273,17 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
<title>Enable caching annotations</title>
<para>It is important to note that even though declaring the cache annotations does not automatically triggers their actions - like many things in Spring, the feature has to be declaratively
enabled (which means if you ever suspect caching is to blame, you can disable it by removing only one configuration line rather then all the annotations in your code). In practice, this
translates to one line that informs Spring that it should process the cache annotations, namely:</para>
enabled (which means if you ever suspect caching is to blame, you can disable it by removing only one configuration line rather then all the annotations in your code).</para>
<para>To enable caching annotations add the annotation <interfacename>@EnableCaching</interfacename> to one of your <interfacename>@Configuration</interfacename> classes:</para>
<programlisting language="java">@Configuration
@EnableCaching
public class AppConfig {
}</programlisting>
<para>Alternatively for XML configuration use the <literal>cache:annotation-driven</literal> element:</para>
<programlisting language="xml"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"]]>
<emphasis role="bold">xmlns:cache="http://www.springframework.org/schema/cache"</emphasis><![CDATA[
@ -283,18 +292,20 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
<emphasis role="bold"><![CDATA[<cache:annotation-driven />]]></emphasis>
<![CDATA[</beans>]]></programlisting>
<para>The namespace allows various options to be specified that influence the way the caching behaviour is added to the application through AOP. The configuration is similar (on purpose)
with that of <literal><ulink url="tx-annotation-driven-settings">tx:annotation-driven</ulink></literal>:
<para>Both the <literal>cache:annotation-driven</literal> element and <interfacename>@EnableCaching</interfacename> annotation allow various options to be specified that influence the way the
caching behaviour is added to the application through AOP. The configuration is intentionally similar
with that of <link linkend="tx-annotation-driven-settings"><interfacename>@Transactional</interfacename></link>:
</para>
<para><table id="cache-annotation-driven-settings">
<title><literal>&lt;cache:annotation-driven/&gt;</literal>
settings</title>
<title>Cache annotation settings</title>
<tgroup cols="3">
<tgroup cols="4">
<thead>
<row>
<entry>Attribute</entry>
<entry>XML Attribute</entry>
<entry>Annotation Attribute</entry>
<entry>Default</entry>
@ -305,6 +316,7 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
<tbody>
<row>
<entry><literal>cache-manager</literal></entry>
<entry>N/A (See <literal>CachingConfigurer</literal> Javadoc)</entry>
<entry>cacheManager</entry>
@ -316,6 +328,7 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
<row>
<entry><literal>mode</literal></entry>
<entry><literal>mode</literal></entry>
<entry>proxy</entry>
@ -334,6 +347,7 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
<row>
<entry><literal>proxy-target-class</literal></entry>
<entry><literal>proxyTargetClass</literal></entry>
<entry>false</entry>
@ -351,6 +365,7 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
<row>
<entry><literal>order</literal></entry>
<entry><literal>order</literal></entry>
<entry>Ordered.LOWEST_PRECEDENCE</entry>

10
src/reference/docbook/index.xml
View File

@ -176,9 +176,16 @@
<author>
<firstname>Rossen</firstname>
<surname>Stoyanchev</surname>
</author>
<author>
<firstname>Phillip</firstname>
<surname>Webb</surname>
</author>
</authorgroup>
<copyright>
@ -189,7 +196,8 @@
Kopylenko, Mark Pollack, Thierry Templier, Erwin Vervaet, Portia Tung,
Ben Hale, Adrian Colyer, John Lewis, Costin Leau, Mark Fisher, Sam
Brannen, Ramnivas Laddad, Arjen Poutsma, Chris Beams, Tareq Abedrabbo,
Andy Clement, Dave Syer, Oliver Gierke, Rossen Stoyanchev</holder>
Andy Clement, Dave Syer, Oliver Gierke, Rossen Stoyanchev,
Phillip Webb</holder>
</copyright>
<legalnotice>

31
src/reference/docbook/jmx.xml
View File

@ -433,7 +433,6 @@ public class JmxTestBean implements IJmxTestBean {
<emphasis>must</emphasis> be configured with an implementation instance
of the <classname>JmxAttributeSource</classname> interface for it to
function correctly (there is <emphasis>no</emphasis> default).</para>
<para>To mark a bean for export to JMX, you should annotate the bean
class with the <classname>ManagedResource</classname> annotation. Each
method you wish to expose as an operation must be marked with the
@ -1076,21 +1075,31 @@ public class AnnotationTestBean implements IJmxTestBean {
</section>
<section id="jmx-context-mbeanexport">
<title>The <literal>&lt;context:mbean-export/&gt;</literal> element</title>
<para>If you are using at least Java 5, then a convenience subclass of
<title>Configuring annotation based MBean export</title>
<para>If you prefer using <link linkend="jmx-interface-metadata">the annotation based
approach</link> to define your management interfaces, then a convenience subclass of
<classname>MBeanExporter</classname> is available:
<classname>AnnotationMBeanExporter</classname>.
When defining an instance of this subclass, the <literal>namingStrategy</literal>,
<literal>assembler</literal>, and <literal>attributeSource</literal>
configuration is no longer needed, since it will always use standard Java
annotation-based metadata (autodetection is always enabled as well). In fact,
an even simpler syntax is supported by Spring's
'<literal>context</literal>' namespace.. Rather than defining an
<classname>MBeanExporter</classname> bean, just provide this single element:</para>
rather than defining an <classname>MBeanExporter</classname> bean, an even
simpler syntax is supported by the <interfacename>@EnableMBeanExport</interfacename>
<interfacename>@Configuration</interfacename> annotation.</para>
<programlisting language="java">@Configuration
@EnableMBeanExport
public class AppConfig {
}</programlisting>
<para>If you prefer XML based configuration the '<literal>context:mbean-export'</literal>
element serves the same purpose.</para>
<programlisting language="xml"><![CDATA[<context:mbean-export/>]]></programlisting>
<para>You can provide a reference to a particular MBean server if
<para>You can provide a reference to a particular MBean <literal>server</literal> if
necessary, and the <literal>defaultDomain</literal> attribute
(a property of <classname>AnnotationMBeanExporter</classname>)
accepts an alternate value for the generated MBean
@ -1100,7 +1109,13 @@ public class AnnotationTestBean implements IJmxTestBean {
<link linkend="jmx-naming-metadata"><classname>MetadataNamingStrategy</classname></link>.
</para>
<programlisting language="xml"><![CDATA[<context:mbean-export server="myMBeanServer" default-domain="myDomain"/>]]></programlisting>.
<programlisting language="java">@EnableMBeanExport(server="myMBeanServer", defaultDomain="myDomain")
@Configuration
ContextConfiguration {
}</programlisting>
<programlisting language="xml"><![CDATA[<context:mbean-export server="myMBeanServer" default-domain="myDomain"/>]]></programlisting>
<note>
<para>Do not use interface-based AOP proxies in combination with autodetection of

40
src/reference/docbook/mvc.xml
View File

@ -4560,8 +4560,8 @@ public class MyWebApplicationInitializer implements WebApplicationInitializer {
<interfacename>@EnableWebMvc</interfacename> to one of your
<interfacename>@Configuration</interfacename> classes:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
public class WebConfig {
}</programlisting>
@ -4702,8 +4702,8 @@ public class WebConfig {
methods to override. See <interfacename>WebMvcConifgurer</interfacename> for
a list of all methods and the Javadoc for further details:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4753,8 +4753,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
<para>An example of registering interceptors in Java:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4799,8 +4799,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
<para>An example of customizing content negotiation in Java:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4839,8 +4839,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
<para>An example of forwarding a request for <literal>"/"</literal>
to a view called <literal>"home"</literal> in Java:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4875,8 +4875,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
<code>/resources/**</code> from a <code>public-resources</code>
directory within the web application root you would use:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4894,8 +4894,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
maximum use of the browser cache and a reduction in HTTP requests made
by the browser:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4972,8 +4972,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
annotation and then inject the <classname>Environment</classname>
abstraction for access to all defined properties:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
@PropertySource("/WEB-INF/spring/application.properties")
public class WebConfig extends WebMvcConfigurerAdapter {
@ -5020,8 +5020,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
<para>To enable the feature using the default setup use:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -5047,8 +5047,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
the default Servlet name is unknown, then the default Servlet's name
must be explicitly provided as in the following example:</para>
<programlisting language="java">@EnableWebMvc
@Configuration
<programlisting language="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override

2
src/reference/docbook/orm.xml
View File

@ -1474,7 +1474,7 @@ TR: OK AS IS. The requirement is to provide the classloader for the runtime envi
<para>As described in the aforementioned section, you can configure a context-wide <interfacename>LoadTimeWeaver</interfacename>
using the <literal>context:load-time-weaver</literal> configuration element. (This has been available since Spring 2.5.)
using the <interfacename>@EnableLoadTimeWeaving</interfacename> annotation of <literal>context:load-time-weaver</literal> XML element.
Such a global weaver is picked up by all JPA <classname>LocalContainerEntityManagerFactoryBeans</classname>
automatically. This is the preferred way of setting up a load-time weaver, delivering autodetection of the platform
(WebLogic, OC4J, GlassFish, Tomcat, Resin, JBoss or VM agent) and automatic propagation of the weaver to all weaver-aware beans:</para>

344
src/reference/docbook/scheduling.xml
View File

@ -357,155 +357,52 @@ public class TaskExecutorExample {
</section>
</section>
<section id="scheduling-task-namespace">
<title>The Task Namespace</title>
<para>Beginning with Spring 3.0, there is an XML namespace for configuring
<interfacename>TaskExecutor</interfacename> and
<interfacename>TaskScheduler</interfacename> instances. It also provides a
convenient way to configure tasks to be scheduled with a trigger.</para>
<section id="scheduling-task-namespace-scheduler">
<title>The 'scheduler' element</title>
<para>The following element will create a
<classname>ThreadPoolTaskScheduler</classname> instance with the
specified thread pool size.</para>
<programlisting language="xml">&lt;task:scheduler id="scheduler" pool-size="10"/&gt;</programlisting>
<para>The value provided for the 'id' attribute will be used as the
prefix for thread names within the pool. The 'scheduler' element is
relatively straightforward. If you do not provide a 'pool-size'
attribute, the default thread pool will only have a single thread. There
are no other configuration options for the scheduler.</para>
</section>
<section id="scheduling-task-namespace-executor">
<title>The 'executor' element</title>
<para>The following will create a
<classname>ThreadPoolTaskExecutor</classname> instance: <programlisting
language="xml">&lt;task:executor id="executor" pool-size="10"/&gt;</programlisting></para>
<para>As with the scheduler above, the value provided for the 'id'
attribute will be used as the prefix for thread names within the pool.
As far as the pool size is concerned, the 'executor' element supports
more configuration options than the 'scheduler' element. For one thing,
the thread pool for a <classname>ThreadPoolTaskExecutor</classname> is
itself more configurable. Rather than just a single size, an executor's
thread pool may have different values for the <emphasis>core</emphasis>
and the <emphasis>max</emphasis> size. If a single value is provided
then the executor will have a fixed-size thread pool (the core and max
sizes are the same). However, the 'executor' element's 'pool-size'
attribute also accepts a range in the form of "min-max". <programlisting
language="xml">&lt;task:executor id="executorWithPoolSizeRange"
pool-size="5-25"
queue-capacity="100"/&gt;</programlisting></para>
<para>As you can see from that configuration, a 'queue-capacity' value
has also been provided. The configuration of the thread pool should also
be considered in light of the executor's queue capacity. For the full
description of the relationship between pool size and queue capacity,
consult the documentation for <ulink
url="http://java.sun.com/javase/6/docs/api/java/util/concurrent/ThreadPoolExecutor.html">ThreadPoolExecutor</ulink>.
The main idea is that when a task is submitted, the executor will first
try to use a free thread if the number of active threads is currently
less than the core size. If the core size has been reached, then the
task will be added to the queue as long as its capacity has not yet been
reached. Only then, if the queue's capacity <emphasis>has</emphasis>
been reached, will the executor create a new thread beyond the core
size. If the max size has also been reached, then the executor will
reject the task.</para>
<para>By default, the queue is <emphasis>unbounded</emphasis>, but this
is rarely the desired configuration, because it can lead to
<classname>OutOfMemoryErrors</classname> if enough tasks are added to
that queue while all pool threads are busy. Furthermore, if the queue is
unbounded, then the max size has no effect at all. Since the executor
will always try the queue before creating a new thread beyond the core
size, a queue must have a finite capacity for the thread pool to grow
beyond the core size (this is why a <emphasis>fixed size</emphasis> pool
is the only sensible case when using an unbounded queue).</para>
<para>In a moment, we will review the effects of the keep-alive setting
which adds yet another factor to consider when providing a pool size
configuration. First, let's consider the case, as mentioned above, when
a task is rejected. By default, when a task is rejected, a thread pool
executor will throw a <classname>TaskRejectedException</classname>.
However, the rejection policy is actually configurable. The exception is
thrown when using the default rejection policy which is the
<classname>AbortPolicy</classname> implementation. For applications
where some tasks can be skipped under heavy load, either the
<classname>DiscardPolicy</classname> or
<classname>DiscardOldestPolicy</classname> may be configured instead.
Another option that works well for applications that need to throttle
the submitted tasks under heavy load is the
<classname>CallerRunsPolicy</classname>. Instead of throwing an
exception or discarding tasks, that policy will simply force the thread
that is calling the submit method to run the task itself. The idea is
that such a caller will be busy while running that task and not able to
submit other tasks immediately. Therefore it provides a simple way to
throttle the incoming load while maintaining the limits of the thread
pool and queue. Typically this allows the executor to "catch up" on the
tasks it is handling and thereby frees up some capacity on the queue, in
the pool, or both. Any of these options can be chosen from an
enumeration of values available for the 'rejection-policy' attribute on
the 'executor' element.</para>
<programlisting language="xml">&lt;task:executor id="executorWithCallerRunsPolicy"
pool-size="5-25"
queue-capacity="100"
rejection-policy="CALLER_RUNS"/&gt;</programlisting>
</section>
<section id="scheduling-task-namespace-scheduled-tasks">
<title>The 'scheduled-tasks' element</title>
<para>The most powerful feature of Spring's task namespace is the
support for configuring tasks to be scheduled within a Spring
Application Context. This follows an approach similar to other
"method-invokers" in Spring, such as that provided by the JMS namespace
for configuring Message-driven POJOs. Basically a "ref" attribute can
point to any Spring-managed object, and the "method" attribute provides
the name of a method to be invoked on that object. Here is a simple
example.</para>
<programlisting language="xml">&lt;task:scheduled-tasks scheduler="myScheduler"&gt;
&lt;task:scheduled ref="beanA" method="methodA" fixed-delay="5000"/&gt;
&lt;/task:scheduled-tasks&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;</programlisting>
<para>As you can see, the scheduler is referenced by the outer element,
and each individual task includes the configuration of its trigger
metadata. In the preceding example, that metadata defines a periodic
trigger with a fixed delay indicating the number of milliseconds to wait
after each task execution has completed. Another option is 'fixed-rate',
indicating how often the method should be executed regardless of how long
any previous execution takes. Additionally, for both fixed-delay and
fixed-rate tasks an 'initial-delay' parameter may be specified indicating
the number of milliseconds to wait before the first execution of the
method. For more control, a "cron" attribute may be provided instead.
Here is an example demonstrating these other options.</para>
<programlisting language="xml">&lt;task:scheduled-tasks scheduler="myScheduler"&gt;
&lt;task:scheduled ref="beanA" method="methodA" fixed-delay="5000" initial-delay="1000"/&gt;
&lt;task:scheduled ref="beanB" method="methodB" fixed-rate="5000"/&gt;
&lt;task:scheduled ref="beanC" method="methodC" cron="*/5 * * * * MON-FRI"/&gt;
&lt;/task:scheduled-tasks&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;</programlisting>
</section>
</section>
<section id="scheduling-annotation-support">
<title>Annotation Support for Scheduling and Asynchronous
Execution</title>
<para>Spring 3.0 also adds annotation support for both task scheduling and
<para>Spring provides annotation support for both task scheduling and
asynchronous method execution.</para>
<section id="secheduling-enable-annotation-support">
<title>Enable scheduling annotations</title>
<para>To enable support for <interfacename>@Scheduled</interfacename> and
<interfacename>@Async</interfacename> annotations add
<interfacename>@EnableScheduling</interfacename> and
<interfacename>@EnableAsync</interfacename> to one of your
<interfacename>@Configuration</interfacename> classes:</para>
<programlisting language="java">@Configuration
@EnableAsync
@EnableSCheduling
public class AppConfig {
}</programlisting>
<para>You are free to pick and choose the relevant annotations
for your application. For example, if you only need support
for <interfacename>@Scheduled</interfacename>, simply omit
<interfacename>@EnableAsync</interfacename>. For more fine-grained
control you can additionally implement the
<interfacename>SchedulingConfigurer</interfacename> and/or
<interfacename>AsyncConfigurer</interfacename> interfaces. See
the Javadoc for full details.</para>
<para>If you prefer XML configuration use the
<literal>&lt;task:annotation-driven&gt;</literal> element.</para>
<programlisting language="xml">&lt;task:annotation-driven executor="myExecutor" scheduler="myScheduler"/&gt;
&lt;task:executor id="myExecutor" pool-size="5"/&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;}</programlisting>
<para>Notice with the above XML that an executor reference is provided
for handling those tasks that correspond to methods with the
<interfacename>@Async</interfacename> annotation, and the scheduler
reference is provided for managing those methods annotated
with <interfacename>@Scheduled</interfacename>.</para>
</section>
<section id="scheduling-annotation-support-scheduled">
<title>The @Scheduled Annotation</title>
@ -636,25 +533,6 @@ public class SampleBeanInititalizer {
}</programlisting>
</section>
<section id="scheduling-annotation-support-namespace">
<title>The &lt;annotation-driven&gt; Element</title>
<para>To enable both @Scheduled and @Async annotations, simply include
the 'annotation-driven' element from the task namespace in your
configuration.</para>
<programlisting language="xml">&lt;task:annotation-driven executor="myExecutor" scheduler="myScheduler"/&gt;
&lt;task:executor id="myExecutor" pool-size="5"/&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;}</programlisting>
<para>Notice that an executor reference is provided for handling those
tasks that correspond to methods with the @Async annotation, and the
scheduler reference is provided for managing those methods annotated
with @Scheduled.</para>
</section>
<section id="scheduling-annotation-support-qualification">
<title>Executor qualification with @Async</title>
@ -679,6 +557,148 @@ void doSomething(String s) {
</section>
</section>
<section id="scheduling-task-namespace">
<title>The Task Namespace</title>
<para>Beginning with Spring 3.0, there is an XML namespace for configuring
<interfacename>TaskExecutor</interfacename> and
<interfacename>TaskScheduler</interfacename> instances. It also provides a
convenient way to configure tasks to be scheduled with a trigger.</para>
<section id="scheduling-task-namespace-scheduler">
<title>The 'scheduler' element</title>
<para>The following element will create a
<classname>ThreadPoolTaskScheduler</classname> instance with the
specified thread pool size.</para>
<programlisting language="xml">&lt;task:scheduler id="scheduler" pool-size="10"/&gt;</programlisting>
<para>The value provided for the 'id' attribute will be used as the
prefix for thread names within the pool. The 'scheduler' element is
relatively straightforward. If you do not provide a 'pool-size'
attribute, the default thread pool will only have a single thread. There
are no other configuration options for the scheduler.</para>
</section>
<section id="scheduling-task-namespace-executor">
<title>The 'executor' element</title>
<para>The following will create a
<classname>ThreadPoolTaskExecutor</classname> instance: <programlisting
language="xml">&lt;task:executor id="executor" pool-size="10"/&gt;</programlisting></para>
<para>As with the scheduler above, the value provided for the 'id'
attribute will be used as the prefix for thread names within the pool.
As far as the pool size is concerned, the 'executor' element supports
more configuration options than the 'scheduler' element. For one thing,
the thread pool for a <classname>ThreadPoolTaskExecutor</classname> is
itself more configurable. Rather than just a single size, an executor's
thread pool may have different values for the <emphasis>core</emphasis>
and the <emphasis>max</emphasis> size. If a single value is provided
then the executor will have a fixed-size thread pool (the core and max
sizes are the same). However, the 'executor' element's 'pool-size'
attribute also accepts a range in the form of "min-max". <programlisting
language="xml">&lt;task:executor id="executorWithPoolSizeRange"
pool-size="5-25"
queue-capacity="100"/&gt;</programlisting></para>
<para>As you can see from that configuration, a 'queue-capacity' value
has also been provided. The configuration of the thread pool should also
be considered in light of the executor's queue capacity. For the full
description of the relationship between pool size and queue capacity,
consult the documentation for <ulink
url="http://java.sun.com/javase/6/docs/api/java/util/concurrent/ThreadPoolExecutor.html">ThreadPoolExecutor</ulink>.
The main idea is that when a task is submitted, the executor will first
try to use a free thread if the number of active threads is currently
less than the core size. If the core size has been reached, then the
task will be added to the queue as long as its capacity has not yet been
reached. Only then, if the queue's capacity <emphasis>has</emphasis>
been reached, will the executor create a new thread beyond the core
size. If the max size has also been reached, then the executor will
reject the task.</para>
<para>By default, the queue is <emphasis>unbounded</emphasis>, but this
is rarely the desired configuration, because it can lead to
<classname>OutOfMemoryErrors</classname> if enough tasks are added to
that queue while all pool threads are busy. Furthermore, if the queue is
unbounded, then the max size has no effect at all. Since the executor
will always try the queue before creating a new thread beyond the core
size, a queue must have a finite capacity for the thread pool to grow
beyond the core size (this is why a <emphasis>fixed size</emphasis> pool
is the only sensible case when using an unbounded queue).</para>
<para>In a moment, we will review the effects of the keep-alive setting
which adds yet another factor to consider when providing a pool size
configuration. First, let's consider the case, as mentioned above, when
a task is rejected. By default, when a task is rejected, a thread pool
executor will throw a <classname>TaskRejectedException</classname>.
However, the rejection policy is actually configurable. The exception is
thrown when using the default rejection policy which is the
<classname>AbortPolicy</classname> implementation. For applications
where some tasks can be skipped under heavy load, either the
<classname>DiscardPolicy</classname> or
<classname>DiscardOldestPolicy</classname> may be configured instead.
Another option that works well for applications that need to throttle
the submitted tasks under heavy load is the
<classname>CallerRunsPolicy</classname>. Instead of throwing an
exception or discarding tasks, that policy will simply force the thread
that is calling the submit method to run the task itself. The idea is
that such a caller will be busy while running that task and not able to
submit other tasks immediately. Therefore it provides a simple way to
throttle the incoming load while maintaining the limits of the thread
pool and queue. Typically this allows the executor to "catch up" on the
tasks it is handling and thereby frees up some capacity on the queue, in
the pool, or both. Any of these options can be chosen from an
enumeration of values available for the 'rejection-policy' attribute on
the 'executor' element.</para>
<programlisting language="xml">&lt;task:executor id="executorWithCallerRunsPolicy"
pool-size="5-25"
queue-capacity="100"
rejection-policy="CALLER_RUNS"/&gt;</programlisting>
</section>
<section id="scheduling-task-namespace-scheduled-tasks">
<title>The 'scheduled-tasks' element</title>
<para>The most powerful feature of Spring's task namespace is the
support for configuring tasks to be scheduled within a Spring
Application Context. This follows an approach similar to other
"method-invokers" in Spring, such as that provided by the JMS namespace
for configuring Message-driven POJOs. Basically a "ref" attribute can
point to any Spring-managed object, and the "method" attribute provides
the name of a method to be invoked on that object. Here is a simple
example.</para>
<programlisting language="xml">&lt;task:scheduled-tasks scheduler="myScheduler"&gt;
&lt;task:scheduled ref="beanA" method="methodA" fixed-delay="5000"/&gt;
&lt;/task:scheduled-tasks&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;</programlisting>
<para>As you can see, the scheduler is referenced by the outer element,
and each individual task includes the configuration of its trigger
metadata. In the preceding example, that metadata defines a periodic
trigger with a fixed delay indicating the number of milliseconds to wait
after each task execution has completed. Another option is 'fixed-rate',
indicating how often the method should be executed regardless of how long
any previous execution takes. Additionally, for both fixed-delay and
fixed-rate tasks an 'initial-delay' parameter may be specified indicating
the number of milliseconds to wait before the first execution of the
method. For more control, a "cron" attribute may be provided instead.
Here is an example demonstrating these other options.</para>
<programlisting language="xml">&lt;task:scheduled-tasks scheduler="myScheduler"&gt;
&lt;task:scheduled ref="beanA" method="methodA" fixed-delay="5000" initial-delay="1000"/&gt;
&lt;task:scheduled ref="beanB" method="methodB" fixed-rate="5000"/&gt;
&lt;task:scheduled ref="beanC" method="methodC" cron="*/5 * * * * MON-FRI"/&gt;
&lt;/task:scheduled-tasks&gt;
&lt;task:scheduler id="myScheduler" pool-size="10"/&gt;</programlisting>
</section>
</section>
<section id="scheduling-quartz">
<title>Using the Quartz Scheduler</title>

46
src/reference/docbook/transaction.xml
View File

@ -689,7 +689,7 @@ would be rolled back, not necessarily following the EJB rules-->
<para>It is not sufficient to tell you simply to annotate your classes
with the <interfacename>@Transactional</interfacename> annotation, add
the line (<literal>&lt;tx:annotation-driven/&gt;</literal>) to your
<interfacename>@EnableTransactionManagement</interfacename> to your
configuration, and then expect you to understand how it all works. This
section explains the inner workings of the Spring Framework's
declarative transaction infrastructure in the event of
@ -1396,6 +1396,14 @@ public class DefaultFooService implements FooService {
explicitly, as in the preceding example.</para>
</tip>
<note>
<para>The <interfacename>@EnableTransactionManagement</interfacename>
annotation provides equivalent support if you are using Java based
configuration. Simply add the annotation to a
<interfacename>@Configuration</interfacename> class. See Javadoc
for full details.</para>
</note>
<sidebar>
<title>Method visibility and
<interfacename>@Transactional</interfacename></title>
@ -1460,13 +1468,14 @@ public class DefaultFooService implements FooService {
behavior on any kind of method.</para>
<para><table id="tx-annotation-driven-settings">
<title><literal>&lt;tx:annotation-driven/&gt;</literal>
settings</title>
<title>Annotation driven transaction settings</title>
<tgroup cols="3">
<tgroup cols="4">
<thead>
<row>
<entry>Attribute</entry>
<entry>XML Attribute</entry>
<entry>Annotation Attribute</entry>
<entry>Default</entry>
@ -1478,6 +1487,10 @@ public class DefaultFooService implements FooService {
<row>
<entry><literal>transaction-manager</literal></entry>
<entry>N/A (See
<interfacename>TransactionManagementConfigurer</interfacename>
Javadoc)</entry>
<entry>transactionManager</entry>
<entry><para>Name of transaction manager to use. Only required
@ -1489,6 +1502,8 @@ public class DefaultFooService implements FooService {
<row>
<entry><literal>mode</literal></entry>
<entry><literal>mode</literal></entry>
<entry>proxy</entry>
<entry><para>The default mode "proxy" processes annotated
@ -1507,6 +1522,8 @@ public class DefaultFooService implements FooService {
<row>
<entry><literal>proxy-target-class</literal></entry>
<entry><literal>proxyTargetClass</literal></entry>
<entry>false</entry>
<entry><para>Applies to proxy mode only. Controls what type of
@ -1524,6 +1541,8 @@ public class DefaultFooService implements FooService {
<row>
<entry><literal>order</literal></entry>
<entry><literal>order</literal></entry>
<entry>Ordered.LOWEST_PRECEDENCE</entry>
<entry><para>Defines the order of the transaction advice that
@ -1539,11 +1558,10 @@ public class DefaultFooService implements FooService {
</table></para>
<note>
<para>The <literal>proxy-target-class</literal> attribute on the
<literal>&lt;tx:annotation-driven/&gt;</literal> element controls what
<para>The <literal>proxy-target-class</literal> attribute controls what
type of transactional proxies are created for classes annotated with
the <interfacename>@Transactional</interfacename> annotation. If
<literal>proxy-target-class</literal> attribute is set to
<literal>proxy-target-class</literal> is set to
<literal>true</literal>, class-based proxies are created. If
<literal>proxy-target-class</literal> is <literal>false</literal> or
if the attribute is omitted, standard JDK interface-based proxies are
@ -1552,20 +1570,20 @@ public class DefaultFooService implements FooService {
</note>
<note>
<para><literal>&lt;tx:annotation-driven/&gt;</literal> only looks for
<para><interfacename>@EnableTransactionManagement</interfacename> and
<literal>&lt;tx:annotation-driven/&gt;</literal> only looks for
<interfacename>@Transactional</interfacename> on beans in the same
application context it is defined in. This means that, if you put
<literal>&lt;tx:annotation-driven/&gt;</literal> in a
application context they are defined in. This means that, if you put
annotation driven configuration in a
<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.
TR: OK AS IS. "it" refers to <tx:annotation-driven/>-->See <xref
controllers, and not your services. 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? TR: OK AS IS. following sentence explains it-->In
transactional settings for a method. 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