/*
* Copyright 2002-2018 the original author or authors.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.springframework.cache.annotation;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;
import org.springframework.context.annotation.AdviceMode;
import org.springframework.context.annotation.Import;
import org.springframework.core.Ordered;
Enables Spring's annotation-driven cache management capability, similar to the support found in Spring's <cache:*> XML namespace. To be used together with @Configuration classes as follows: @Configuration
@EnableCaching
public class AppConfig {
@Bean
public MyService myService() {
// configure and return a class having @Cacheable methods
return new MyService();
}
@Bean
public CacheManager cacheManager() {
// configure and return an implementation of Spring's CacheManager SPI
SimpleCacheManager cacheManager = new SimpleCacheManager();
cacheManager.setCaches(Arrays.asList(new ConcurrentMapCache("default")));
return cacheManager;
}
}
For reference, the example above can be compared to the following Spring XML
configuration:
<beans>
<cache:annotation-driven/>
<bean id="myService" class="com.foo.MyService"/>
<bean id="cacheManager" class="org.springframework.cache.support.SimpleCacheManager">
<property name="caches">
<set>
<bean class="org.springframework.cache.concurrent.ConcurrentMapCacheFactoryBean">
<property name="name" value="default"/>
</bean>
</set>
</property>
</bean>
</beans>
In both of the scenarios above, @EnableCaching and
<cache:annotation-driven/> are responsible for registering the necessary Spring components that power annotation-driven cache management, such as the CacheInterceptor and the proxy- or AspectJ-based advice that weaves the interceptor into the call stack when @Cacheable methods are invoked. If the JSR-107 API and Spring's JCache implementation are present, the necessary components to manage standard cache annotations are also registered. This creates the proxy- or AspectJ-based advice that weaves the interceptor into the call stack when methods annotated with CacheResult, CachePut, CacheRemove or CacheRemoveAll are invoked.
A bean of type CacheManager must be registered, as there is no reasonable default that the framework can use as a convention. And whereas the <cache:annotation-driven> element assumes a bean named "cacheManager", @EnableCaching searches for a cache manager bean by type. Therefore, naming of the cache manager bean method is
not significant.
For those that wish to establish a more direct relationship between @EnableCaching and the exact cache manager bean to be used, the CachingConfigurer callback interface may be implemented. Notice the @Override-annotated methods below:
@Configuration
@EnableCaching
public class AppConfig extends CachingConfigurerSupport {
@Bean
public MyService myService() {
// configure and return a class having @Cacheable methods
return new MyService();
}
@Bean
@Override
public CacheManager cacheManager() {
// configure and return an implementation of Spring's CacheManager SPI
SimpleCacheManager cacheManager = new SimpleCacheManager();
cacheManager.setCaches(Arrays.asList(new ConcurrentMapCache("default")));
return cacheManager;
}
@Bean
@Override
public KeyGenerator keyGenerator() {
// configure and return an implementation of Spring's KeyGenerator SPI
return new MyKeyGenerator();
}
} This approach may be desirable simply because it is more explicit, or it may be necessary in order to distinguish between two CacheManager beans present in the same container. Notice also the keyGenerator method in the example above. This allows for customizing the strategy for cache key generation, per Spring's KeyGenerator SPI. Normally, @EnableCaching will configure Spring's SimpleKeyGenerator for this purpose, but when implementing CachingConfigurer, a key generator must be provided explicitly. Return null or new SimpleKeyGenerator() from this method if no customization is necessary.
CachingConfigurer offers additional customization options: it is recommended to extend from
CachingConfigurerSupport that provides a default implementation for all methods which can be useful if you do not need to customize everything. See CachingConfigurer Javadoc for further details.
The mode attribute controls how advice is applied: If the mode is AdviceMode.PROXY (the default), then the other attributes control the behavior of the proxying. Please note that proxy mode allows for interception of calls through the proxy only; local calls within the same class cannot get intercepted that way.
Note that if the mode is set to AdviceMode.ASPECTJ, then the value of the proxyTargetClass attribute will be ignored. Note also that in this case the spring-aspects module JAR must be present on the classpath, with compile-time weaving or load-time weaving applying the aspect to the affected classes. There is no proxy involved in such a scenario; local calls will be intercepted as well.
Author: Chris Beams, Juergen Hoeller See Also: - CachingConfigurer
- CachingConfigurationSelector
- ProxyCachingConfiguration
- AspectJCachingConfiguration
Since: 3.1
/**
* Enables Spring's annotation-driven cache management capability, similar to the
* support found in Spring's {@code <cache:*>} XML namespace. To be used together
* with @{@link org.springframework.context.annotation.Configuration Configuration}
* classes as follows:
*
* <pre class="code">
* @Configuration
* @EnableCaching
* public class AppConfig {
*
* @Bean
* public MyService myService() {
* // configure and return a class having @Cacheable methods
* return new MyService();
* }
*
* @Bean
* public CacheManager cacheManager() {
* // configure and return an implementation of Spring's CacheManager SPI
* SimpleCacheManager cacheManager = new SimpleCacheManager();
* cacheManager.setCaches(Arrays.asList(new ConcurrentMapCache("default")));
* return cacheManager;
* }
* }</pre>
*
* <p>For reference, the example above can be compared to the following Spring XML
* configuration:
*
* <pre class="code">
* <beans>
*
* <cache:annotation-driven/>
*
* <bean id="myService" class="com.foo.MyService"/>
*
* <bean id="cacheManager" class="org.springframework.cache.support.SimpleCacheManager">
* <property name="caches">
* <set>
* <bean class="org.springframework.cache.concurrent.ConcurrentMapCacheFactoryBean">
* <property name="name" value="default"/>
* </bean>
* </set>
* </property>
* </bean>
*
* </beans>
* </pre>
*
* In both of the scenarios above, {@code @EnableCaching} and {@code
* <cache:annotation-driven/>} are responsible for registering the necessary Spring
* components that power annotation-driven cache management, such as the
* {@link org.springframework.cache.interceptor.CacheInterceptor CacheInterceptor} and the
* proxy- or AspectJ-based advice that weaves the interceptor into the call stack when
* {@link org.springframework.cache.annotation.Cacheable @Cacheable} methods are invoked.
*
* <p>If the JSR-107 API and Spring's JCache implementation are present, the necessary
* components to manage standard cache annotations are also registered. This creates the
* proxy- or AspectJ-based advice that weaves the interceptor into the call stack when
* methods annotated with {@code CacheResult}, {@code CachePut}, {@code CacheRemove} or
* {@code CacheRemoveAll} are invoked.
*
* <p><strong>A bean of type {@link org.springframework.cache.CacheManager CacheManager}
* must be registered</strong>, as there is no reasonable default that the framework can
* use as a convention. And whereas the {@code <cache:annotation-driven>} element assumes
* a bean <em>named</em> "cacheManager", {@code @EnableCaching} searches for a cache
* manager bean <em>by type</em>. Therefore, naming of the cache manager bean method is
* not significant.
*
* <p>For those that wish to establish a more direct relationship between
* {@code @EnableCaching} and the exact cache manager bean to be used,
* the {@link CachingConfigurer} callback interface may be implemented.
* Notice the {@code @Override}-annotated methods below:
*
* <pre class="code">
* @Configuration
* @EnableCaching
* public class AppConfig extends CachingConfigurerSupport {
*
* @Bean
* public MyService myService() {
* // configure and return a class having @Cacheable methods
* return new MyService();
* }
*
* @Bean
* @Override
* public CacheManager cacheManager() {
* // configure and return an implementation of Spring's CacheManager SPI
* SimpleCacheManager cacheManager = new SimpleCacheManager();
* cacheManager.setCaches(Arrays.asList(new ConcurrentMapCache("default")));
* return cacheManager;
* }
*
* @Bean
* @Override
* public KeyGenerator keyGenerator() {
* // configure and return an implementation of Spring's KeyGenerator SPI
* return new MyKeyGenerator();
* }
* }</pre>
*
* This approach may be desirable simply because it is more explicit, or it may be
* necessary in order to distinguish between two {@code CacheManager} beans present in the
* same container.
*
* <p>Notice also the {@code keyGenerator} method in the example above. This allows for
* customizing the strategy for cache key generation, per Spring's {@link
* org.springframework.cache.interceptor.KeyGenerator KeyGenerator} SPI. Normally,
* {@code @EnableCaching} will configure Spring's
* {@link org.springframework.cache.interceptor.SimpleKeyGenerator SimpleKeyGenerator}
* for this purpose, but when implementing {@code CachingConfigurer}, a key generator
* must be provided explicitly. Return {@code null} or {@code new SimpleKeyGenerator()}
* from this method if no customization is necessary.
*
* <p>{@link CachingConfigurer} offers additional customization options: it is recommended
* to extend from {@link org.springframework.cache.annotation.CachingConfigurerSupport
* CachingConfigurerSupport} that provides a default implementation for all methods which
* can be useful if you do not need to customize everything. See {@link CachingConfigurer}
* Javadoc for further details.
*
* <p>The {@link #mode} attribute controls how advice is applied: If the mode is
* {@link AdviceMode#PROXY} (the default), then the other attributes control the behavior
* of the proxying. Please note that proxy mode allows for interception of calls through
* the proxy only; local calls within the same class cannot get intercepted that way.
*
* <p>Note that if the {@linkplain #mode} is set to {@link AdviceMode#ASPECTJ}, then the
* value of the {@link #proxyTargetClass} attribute will be ignored. Note also that in
* this case the {@code spring-aspects} module JAR must be present on the classpath, with
* compile-time weaving or load-time weaving applying the aspect to the affected classes.
* There is no proxy involved in such a scenario; local calls will be intercepted as well.
*
* @author Chris Beams
* @author Juergen Hoeller
* @since 3.1
* @see CachingConfigurer
* @see CachingConfigurationSelector
* @see ProxyCachingConfiguration
* @see org.springframework.cache.aspectj.AspectJCachingConfiguration
*/
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Import(CachingConfigurationSelector.class)
public @interface EnableCaching {
Indicate whether subclass-based (CGLIB) proxies are to be created as opposed to standard Java interface-based proxies. The default is false. Applicable only if mode() is set to AdviceMode.PROXY.
Note that setting this attribute to true will affect all Spring-managed beans requiring proxying, not just those marked with @Cacheable. For example, other beans marked with Spring's @Transactional annotation will be upgraded to subclass proxying at the same time. This approach has no negative impact in practice unless one is explicitly expecting one type of proxy vs another, e.g. in tests.
/**
* Indicate whether subclass-based (CGLIB) proxies are to be created as opposed
* to standard Java interface-based proxies. The default is {@code false}. <strong>
* Applicable only if {@link #mode()} is set to {@link AdviceMode#PROXY}</strong>.
* <p>Note that setting this attribute to {@code true} will affect <em>all</em>
* Spring-managed beans requiring proxying, not just those marked with {@code @Cacheable}.
* For example, other beans marked with Spring's {@code @Transactional} annotation will
* be upgraded to subclass proxying at the same time. This approach has no negative
* impact in practice unless one is explicitly expecting one type of proxy vs another,
* e.g. in tests.
*/
boolean proxyTargetClass() default false;
Indicate how caching advice should be applied.
The default is AdviceMode.PROXY. Please note that proxy mode allows for interception of calls through the proxy only. Local calls within the same class cannot get intercepted that way; a caching annotation on such a method within a local call will be ignored since Spring's interceptor does not even kick in for such a runtime scenario. For a more advanced mode of interception, consider switching this to AdviceMode.ASPECTJ.
/**
* Indicate how caching advice should be applied.
* <p><b>The default is {@link AdviceMode#PROXY}.</b>
* Please note that proxy mode allows for interception of calls through the proxy
* only. Local calls within the same class cannot get intercepted that way;
* a caching annotation on such a method within a local call will be ignored
* since Spring's interceptor does not even kick in for such a runtime scenario.
* For a more advanced mode of interception, consider switching this to
* {@link AdviceMode#ASPECTJ}.
*/
AdviceMode mode() default AdviceMode.PROXY;
Indicate the ordering of the execution of the caching advisor
when multiple advices are applied at a specific joinpoint.
The default is Ordered.LOWEST_PRECEDENCE.
/**
* Indicate the ordering of the execution of the caching advisor
* when multiple advices are applied at a specific joinpoint.
* <p>The default is {@link Ordered#LOWEST_PRECEDENCE}.
*/
int order() default Ordered.LOWEST_PRECEDENCE;
}