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
<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
@@ -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>
@ -273,8 +273,17 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
@@ -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>
<programlistinglanguage="java">@Configuration
@EnableCaching
public class AppConfig {
}</programlisting>
<para>Alternatively for XML configuration use the <literal>cache:annotation-driven</literal> element:</para>
@ -283,18 +292,20 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
@@ -283,18 +292,20 @@ public Book importBooks(String deposit, Date date)]]></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><ulinkurl="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 <linklinkend="tx-annotation-driven-settings"><interfacename>@Transactional</interfacename></link>:
@ -305,6 +316,7 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
@@ -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>
@@ -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>
@@ -334,6 +347,7 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
@ -351,6 +365,7 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
@@ -351,6 +365,7 @@ public Book importBooks(String deposit, Date date)]]></programlisting>
@ -433,7 +433,6 @@ public class JmxTestBean implements IJmxTestBean {
@@ -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 {
@@ -1076,21 +1075,31 @@ public class AnnotationTestBean implements IJmxTestBean {
<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 {
@@ -1100,7 +1109,13 @@ public class AnnotationTestBean implements IJmxTestBean {
@ -4560,8 +4560,8 @@ public class MyWebApplicationInitializer implements WebApplicationInitializer {
@@ -4560,8 +4560,8 @@ public class MyWebApplicationInitializer implements WebApplicationInitializer {
<interfacename>@EnableWebMvc</interfacename> to one of your
@ -4702,8 +4702,8 @@ public class WebConfig {
@@ -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>
<programlistinglanguage="java">@EnableWebMvc
@Configuration
<programlistinglanguage="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4753,8 +4753,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
@@ -4753,8 +4753,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
<para>An example of registering interceptors in Java:</para>
<programlistinglanguage="java">@EnableWebMvc
@Configuration
<programlistinglanguage="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4799,8 +4799,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
@@ -4799,8 +4799,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
<para>An example of customizing content negotiation in Java:</para>
<programlistinglanguage="java">@EnableWebMvc
@Configuration
<programlistinglanguage="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4839,8 +4839,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
@@ -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>
<programlistinglanguage="java">@EnableWebMvc
@Configuration
<programlistinglanguage="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4875,8 +4875,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
@@ -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>
<programlistinglanguage="java">@EnableWebMvc
@Configuration
<programlistinglanguage="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4894,8 +4894,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
@@ -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>
<programlistinglanguage="java">@EnableWebMvc
@Configuration
<programlistinglanguage="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -4972,8 +4972,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
@@ -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>
public class WebConfig extends WebMvcConfigurerAdapter {
@ -5020,8 +5020,8 @@ 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>
<programlistinglanguage="java">@EnableWebMvc
@Configuration
<programlistinglanguage="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@Override
@ -5047,8 +5047,8 @@ public class WebConfig extends WebMvcConfigurerAdapter {
@@ -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>
<programlistinglanguage="java">@EnableWebMvc
@Configuration
<programlistinglanguage="java">@Configuration
@EnableWebMvc
public class WebConfig extends WebMvcConfigurerAdapter {
@ -1474,7 +1474,7 @@ TR: OK AS IS. The requirement is to provide the classloader for the runtime envi
@@ -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>
@ -689,7 +689,7 @@ would be rolled back, not necessarily following the EJB rules-->
@@ -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><tx:annotation-driven/></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 {
@@ -1396,6 +1396,14 @@ public class DefaultFooService implements FooService {
@ -1460,13 +1468,14 @@ public class DefaultFooService implements FooService {
@@ -1460,13 +1468,14 @@ public class DefaultFooService implements FooService {
@ -1478,6 +1487,10 @@ public class DefaultFooService implements FooService {
@@ -1478,6 +1487,10 @@ public class DefaultFooService implements FooService {
<entry><para>Name of transaction manager to use. Only required
@ -1489,6 +1502,8 @@ public class DefaultFooService implements FooService {
@@ -1489,6 +1502,8 @@ public class DefaultFooService implements FooService {
@ -1507,6 +1522,8 @@ public class DefaultFooService implements FooService {
@@ -1507,6 +1522,8 @@ public class DefaultFooService implements FooService {
<entry><para>Applies to proxy mode only. Controls what type of
@ -1524,6 +1541,8 @@ public class DefaultFooService implements FooService {
@@ -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 {
@@ -1539,11 +1558,10 @@ public class DefaultFooService implements FooService {
</table></para>
<note>
<para>The <literal>proxy-target-class</literal> attribute on the
<literal><tx:annotation-driven/></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 {
@@ -1552,20 +1570,20 @@ public class DefaultFooService implements FooService {
</note>
<note>
<para><literal><tx:annotation-driven/></literal> only looks for
<para><interfacename>@EnableTransactionManagement</interfacename> and
<literal><tx:annotation-driven/></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><tx:annotation-driven/></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
Phillip Webb
13 years ago