Top Description Methods
org.springframework.cache.annotation

public @Interface Cacheable

extends Annotation
Annotations
@Target:TYPE, METHOD
@Retention:RUNTIME
@Inherited
@Documented
@Reflective
Imports
java.lang.annotation.Documented, .ElementType, .Inherited, .Retention, .RetentionPolicy, .Target, java.util.concurrent.Callable, org.springframework.aot.hint.annotation.Reflective, org.springframework.core.annotation.AliasFor
Annotation indicating that the result of invoking a method (or all methods in a class) can be cached.

Each time an advised method is invoked, caching behavior will be applied, checking whether the method has been already invoked for the given arguments. A sensible default simply uses the method parameters to compute the key, but a SpEL expression can be provided via the key attribute, or a custom org.springframework.cache.interceptor.KeyGenerator implementation can replace the default one (see keyGenerator).

If no value is found in the cache for the computed key, the target method will be invoked and the returned value will be stored in the associated cache. Note that java.util.Optional return types are unwrapped automatically. If an Optional value is present, it will be stored in the associated cache. If an Optional value is not present, null will be stored in the associated cache.

This annotation may be used as a meta-annotation to create custom composed annotations with attribute overrides.

Authors
Costin Leau, Phillip Webb, Stephane Nicoll, Sam Brannen
Since
3.1
See Also
CacheConfig

Method Summary

Modifier and TypeMethod and Description
public String
cacheManager()

The bean name of the custom org.springframework.cache.CacheManager to use to create a default org.springframework.cache.interceptor.CacheResolver if none is set already.

public String[]
cacheNames()

Names of the caches in which method invocation results are stored.

public String
cacheResolver()

The bean name of the custom org.springframework.cache.interceptor.CacheResolver to use.

public String
condition()

Spring Expression Language (SpEL) expression used for making the method caching conditional.

public String
key()

Spring Expression Language (SpEL) expression for computing the key dynamically.

public String
keyGenerator()

The bean name of the custom org.springframework.cache.interceptor.KeyGenerator to use.

public boolean
sync()

Synchronize the invocation of the underlying method if several threads are attempting to load a value for the same key.

public String
unless()

Spring Expression Language (SpEL) expression used to veto method caching.

public String[]
value()

Alias for cacheNames.

Inherited from java.lang.annotation.Annotation:
annotationTypeequalshashCodetoString

Method Detail

cacheManagerback to summary
public String cacheManager()

The bean name of the custom org.springframework.cache.CacheManager to use to create a default org.springframework.cache.interceptor.CacheResolver if none is set already.

Mutually exclusive with the cacheResolver attribute.

See Also
org.springframework.cache.interceptor.SimpleCacheResolver, CacheConfig#cacheManager
cacheNamesback to summary
public String[] cacheNames()

Names of the caches in which method invocation results are stored.

Names may be used to determine the target cache(s), to be resolved via the configured cacheResolver() which typically delegates to org.springframework.cache.CacheManager#getCache.

This will usually be a single cache name. If multiple names are specified, they will be consulted for a cache hit in the order of definition, and they will all receive a put/evict request for the same newly cached value.

Note that asynchronous/reactive cache access may not fully consult all specified caches, depending on the target cache. In the case of late-determined cache misses (e.g. with Redis), further caches will not get consulted anymore. As a consequence, specifying multiple cache names in an async cache mode setup only makes sense with early-determined cache misses (e.g. with Caffeine).

Annotations
@AliasFor:value
Since
4.2
See Also
value, CacheConfig#cacheNames
cacheResolverback to summary
public String cacheResolver()

The bean name of the custom org.springframework.cache.interceptor.CacheResolver to use.

See Also
CacheConfig#cacheResolver
conditionback to summary
public String condition()

Spring Expression Language (SpEL) expression used for making the method caching conditional. Cache the result if the condition evaluates to true.

Default is "", meaning the method result is always cached.

The SpEL expression evaluates against a dedicated context that provides the following meta-data:

  • #root.method, #root.target, and #root.caches for references to the method, target object, and affected cache(s) respectively.
  • Shortcuts for the method name (#root.methodName) and target class (#root.targetClass) are also available.
  • Method arguments can be accessed by index. For instance the second argument can be accessed via #root.args[1], #p1 or #a1. Arguments can also be accessed by name if that information is available.
keyback to summary
public String key()

Spring Expression Language (SpEL) expression for computing the key dynamically.

Default is "", meaning all method parameters are considered as a key, unless a custom keyGenerator has been configured.

The SpEL expression evaluates against a dedicated context that provides the following meta-data:

  • #root.method, #root.target, and #root.caches for references to the method, target object, and affected cache(s) respectively.
  • Shortcuts for the method name (#root.methodName) and target class (#root.targetClass) are also available.
  • Method arguments can be accessed by index. For instance the second argument can be accessed via #root.args[1], #p1 or #a1. Arguments can also be accessed by name if that information is available.
keyGeneratorback to summary
public String keyGenerator()

The bean name of the custom org.springframework.cache.interceptor.KeyGenerator to use.

Mutually exclusive with the key attribute.

See Also
CacheConfig#keyGenerator
syncback to summary
public boolean sync()

Synchronize the invocation of the underlying method if several threads are attempting to load a value for the same key. The synchronization leads to a couple of limitations:

  1. unless() is not supported
  2. Only one cache may be specified
  3. No other cache-related operation can be combined
This is effectively a hint and the chosen cache provider might not actually support it in a synchronized fashion. Check your provider documentation for more details on the actual semantics.
Since
4.3
See Also
org.springframework.cache.Cache#get(Object, Callable)
unlessback to summary
public String unless()

Spring Expression Language (SpEL) expression used to veto method caching. Veto caching the result if the condition evaluates to true.

Unlike condition, this expression is evaluated after the method has been called and can therefore refer to the result.

Default is "", meaning that caching is never vetoed.

The SpEL expression evaluates against a dedicated context that provides the following meta-data:

  • #result for a reference to the result of the method invocation. For supported wrappers such as Optional, #result refers to the actual object, not the wrapper
  • #root.method, #root.target, and #root.caches for references to the method, target object, and affected cache(s) respectively.
  • Shortcuts for the method name (#root.methodName) and target class (#root.targetClass) are also available.
  • Method arguments can be accessed by index. For instance the second argument can be accessed via #root.args[1], #p1 or #a1. Arguments can also be accessed by name if that information is available.
Since
3.2
valueback to summary
public String[] value()

Alias for cacheNames.

Annotations
@AliasFor:cacheNames