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

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

@ -327,8 +327,32 @@
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>
<section id="aop-enable-aspectj-java">
<title>Enabling @AspectJ Support with Java configuration</title>
<para>To enable @AspectJ support with Java
<interfacename>@Configuration</interfacename> add the
<interfacename>@EnableAspectJAutoProxy</interfacename> annotation:</para>
<programlisting language="java">@Configuration
@EnableAspectJAutoProxy
public class AppConfig {
}</programlisting>
</section>
<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>
@ -342,12 +366,7 @@
context:</para>
<programlisting language="xml">&lt;bean class="org.springframework.aop.aspectj.annotation.AnnotationAwareAspectJAutoProxyCreator" /&gt;</programlisting>
<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>
</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>

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

@ -357,6 +357,206 @@ public class TaskExecutorExample {
</section>
</section>
<section id="scheduling-annotation-support">
<title>Annotation Support for Scheduling and Asynchronous
Execution</title>
<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>
<para>The @Scheduled annotation can be added to a method along with
trigger metadata. For example, the following method would be invoked
every 5 seconds with a fixed delay, meaning that the period will be
measured from the completion time of each preceding invocation.</para>
<programlisting language="java">@Scheduled(fixedDelay=5000)
public void doSomething() {
// something that should execute periodically
}</programlisting>
<para>If a fixed rate execution is desired, simply change the property
name specified within the annotation. The following would be executed
every 5 seconds measured between the successive start times of each
invocation.</para>
<programlisting language="java">@Scheduled(fixedRate=5000)
public void doSomething() {
// something that should execute periodically
}</programlisting>
<para>For fixed-delay and fixed-rate tasks, an initial delay may be
specified indicating the number of milliseconds to wait before the first
execution of the method.
</para>
<programlisting language="java">@Scheduled(initialDelay=1000, fixedRate=5000)
public void doSomething() {
// something that should execute periodically
}</programlisting>
<para>If simple periodic scheduling is not expressive enough, then a
cron expression may be provided. For example, the following will only
execute on weekdays.</para>
<programlisting language="java">@Scheduled(cron="*/5 * * * * MON-FRI")
public void doSomething() {
// something that should execute on weekdays only
}</programlisting>
<para>Notice that the methods to be scheduled must have void returns and
must not expect any arguments. If the method needs to interact with
other objects from the Application Context, then those would typically
have been provided through dependency injection.</para>
<note>
<para>Make sure that you are not initializing multiple instances of
the same @Scheduled annotation class at runtime, unless you do want to
schedule callbacks to each such instance. Related to this, make sure
that you do not use @Configurable on bean classes which are annotated
with @Scheduled and registered as regular Spring beans with the
container: You would get double initialization otherwise, once through
the container and once through the @Configurable aspect, with the
consequence of each @Scheduled method being invoked twice.</para>
</note>
</section>
<section id="scheduling-annotation-support-async">
<title>The @Async Annotation</title>
<para>The <interfacename>@Async</interfacename> annotation can be
provided on a method so that invocation of that method will occur
asynchronously. In other words, the caller will return immediately upon
invocation and the actual execution of the method will occur in a task
that has been submitted to a Spring
<interfacename>TaskExecutor</interfacename>. In the simplest case, the
annotation may be applied to a <literal>void</literal>-returning
method.</para>
<programlisting language="java">@Async
void doSomething() {
// this will be executed asynchronously
}</programlisting>
<para>Unlike the methods annotated with the
<interfacename>@Scheduled</interfacename> annotation, these methods can
expect arguments, because they will be invoked in the "normal" way by
callers at runtime rather than from a scheduled task being managed by
the container. For example, the following is a legitimate application of
the <interfacename>@Async</interfacename> annotation.</para>
<programlisting language="java">@Async
void doSomething(String s) {
// this will be executed asynchronously
}</programlisting>
<para>Even methods that return a value can be invoked asynchronously.
However, such methods are required to have a
<interfacename>Future</interfacename> typed return value. This still
provides the benefit of asynchronous execution so that the caller can
perform other tasks prior to calling <methodname>get()</methodname> on
that Future.</para>
<programlisting language="java">@Async
Future&lt;String&gt; returnSomething(int i) {
// this will be executed asynchronously
}</programlisting>
<para><interfacename>@Async</interfacename> can not be used in
conjunction with lifecycle callbacks such as
<interfacename>@PostConstruct</interfacename>. To asynchronously
initialize Spring beans you currently have to use a separate
initializing Spring bean that invokes the
<interfacename>@Async</interfacename> annotated method on the target
then.</para>
<programlisting language="java">public class SampleBeanImpl implements SampleBean {
@Async
void doSomething() { … }
}
public class SampleBeanInititalizer {
private final SampleBean bean;
public SampleBeanInitializer(SampleBean bean) {
this.bean = bean;
}
@PostConstruct
public void initialize() {
bean.doSomething();
}
}</programlisting>
</section>
<section id="scheduling-annotation-support-qualification">
<title>Executor qualification with @Async</title>
<para>By default when specifying <interfacename>@Async</interfacename> on
a method, the executor that will be used is the one supplied to the
'annotation-driven' element as described above. However, the
<literal>value</literal> attribute of the
<interfacename>@Async</interfacename> annotation can be used when needing
to indicate that an executor other than the default should be used when
executing a given method.</para>
<programlisting language="java">@Async("otherExecutor")
void doSomething(String s) {
// this will be executed asynchronously by "otherExecutor"
}</programlisting>
<para>In this case, "otherExecutor" may be the name of any
<interfacename>Executor</interfacename> bean in the Spring container, or
may be the name of a <emphasis>qualifier</emphasis> associated with any
<interfacename>Executor</interfacename>, e.g. as specified with the
<literal>&lt;qualifier&gt;</literal> element or Spring's
<interfacename>@Qualifier</interfacename> annotation.</para>
</section>
</section>
<section id="scheduling-task-namespace">
<title>The Task Namespace</title>
@ -499,186 +699,6 @@ public class TaskExecutorExample {
</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
asynchronous method execution.</para>
<section id="scheduling-annotation-support-scheduled">
<title>The @Scheduled Annotation</title>
<para>The @Scheduled annotation can be added to a method along with
trigger metadata. For example, the following method would be invoked
every 5 seconds with a fixed delay, meaning that the period will be
measured from the completion time of each preceding invocation.</para>
<programlisting language="java">@Scheduled(fixedDelay=5000)
public void doSomething() {
// something that should execute periodically
}</programlisting>
<para>If a fixed rate execution is desired, simply change the property
name specified within the annotation. The following would be executed
every 5 seconds measured between the successive start times of each
invocation.</para>
<programlisting language="java">@Scheduled(fixedRate=5000)
public void doSomething() {
// something that should execute periodically
}</programlisting>
<para>For fixed-delay and fixed-rate tasks, an initial delay may be
specified indicating the number of milliseconds to wait before the first
execution of the method.
</para>
<programlisting language="java">@Scheduled(initialDelay=1000, fixedRate=5000)
public void doSomething() {
// something that should execute periodically
}</programlisting>
<para>If simple periodic scheduling is not expressive enough, then a
cron expression may be provided. For example, the following will only
execute on weekdays.</para>
<programlisting language="java">@Scheduled(cron="*/5 * * * * MON-FRI")
public void doSomething() {
// something that should execute on weekdays only
}</programlisting>
<para>Notice that the methods to be scheduled must have void returns and
must not expect any arguments. If the method needs to interact with
other objects from the Application Context, then those would typically
have been provided through dependency injection.</para>
<note>
<para>Make sure that you are not initializing multiple instances of
the same @Scheduled annotation class at runtime, unless you do want to
schedule callbacks to each such instance. Related to this, make sure
that you do not use @Configurable on bean classes which are annotated
with @Scheduled and registered as regular Spring beans with the
container: You would get double initialization otherwise, once through
the container and once through the @Configurable aspect, with the
consequence of each @Scheduled method being invoked twice.</para>
</note>
</section>
<section id="scheduling-annotation-support-async">
<title>The @Async Annotation</title>
<para>The <interfacename>@Async</interfacename> annotation can be
provided on a method so that invocation of that method will occur
asynchronously. In other words, the caller will return immediately upon
invocation and the actual execution of the method will occur in a task
that has been submitted to a Spring
<interfacename>TaskExecutor</interfacename>. In the simplest case, the
annotation may be applied to a <literal>void</literal>-returning
method.</para>
<programlisting language="java">@Async
void doSomething() {
// this will be executed asynchronously
}</programlisting>
<para>Unlike the methods annotated with the
<interfacename>@Scheduled</interfacename> annotation, these methods can
expect arguments, because they will be invoked in the "normal" way by
callers at runtime rather than from a scheduled task being managed by
the container. For example, the following is a legitimate application of
the <interfacename>@Async</interfacename> annotation.</para>
<programlisting language="java">@Async
void doSomething(String s) {
// this will be executed asynchronously
}</programlisting>
<para>Even methods that return a value can be invoked asynchronously.
However, such methods are required to have a
<interfacename>Future</interfacename> typed return value. This still
provides the benefit of asynchronous execution so that the caller can
perform other tasks prior to calling <methodname>get()</methodname> on
that Future.</para>
<programlisting language="java">@Async
Future&lt;String&gt; returnSomething(int i) {
// this will be executed asynchronously
}</programlisting>
<para><interfacename>@Async</interfacename> can not be used in
conjunction with lifecycle callbacks such as
<interfacename>@PostConstruct</interfacename>. To asynchronously
initialize Spring beans you currently have to use a separate
initializing Spring bean that invokes the
<interfacename>@Async</interfacename> annotated method on the target
then.</para>
<programlisting language="java">public class SampleBeanImpl implements SampleBean {
@Async
void doSomething() { … }
}
public class SampleBeanInititalizer {
private final SampleBean bean;
public SampleBeanInitializer(SampleBean bean) {
this.bean = bean;
}
@PostConstruct
public void initialize() {
bean.doSomething();
}
}</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>
<para>By default when specifying <interfacename>@Async</interfacename> on
a method, the executor that will be used is the one supplied to the
'annotation-driven' element as described above. However, the
<literal>value</literal> attribute of the
<interfacename>@Async</interfacename> annotation can be used when needing
to indicate that an executor other than the default should be used when
executing a given method.</para>
<programlisting language="java">@Async("otherExecutor")
void doSomething(String s) {
// this will be executed asynchronously by "otherExecutor"
}</programlisting>
<para>In this case, "otherExecutor" may be the name of any
<interfacename>Executor</interfacename> bean in the Spring container, or
may be the name of a <emphasis>qualifier</emphasis> associated with any
<interfacename>Executor</interfacename>, e.g. as specified with the
<literal>&lt;qualifier&gt;</literal> element or Spring's
<interfacename>@Qualifier</interfacename> annotation.</para>
</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