10/11/2020 Cacheable (Spring Framework 5.2.9.

RELEASE API)
Spring Framework
OVERVIEW PACKAGE CLASS USE TREE DEPRECATED INDEX HELP

PREV CLASS NEXT CLASS FRAMES NO FRAMES ALL CLASSES

org.springframework.cache.annotation

Annotation Type Cacheable

@Target(value={TYPE,METHOD})
@Retention(value=RUNTIME)
@Inherited
@Documented
public @interface Cacheable

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 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
stored in the associated cache. Note that Java8's Optional return types are automatically handled and its
content is stored in the cache if present.

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

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

Optional Element Summary

Optional Elements

Modifier and Type Optional Element and Description

String cacheManager
The bean name of the custom CacheManager to use to create a default
CacheResolver if none is set already.

String[] cacheNames
Names of the caches in which method invocation results are stored.

https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/Cacheable.html 1/6
10/11/2020 Cacheable (Spring Framework 5.2.9.RELEASE API)

String cacheResolver
The bean name of the custom CacheResolver to use.

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

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

String keyGenerator
The bean name of the custom KeyGenerator to use.

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

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

String[] value
Alias for cacheNames().

Element Detail

value

@AliasFor(value="cacheNames")
public abstract String[] value

Alias for cacheNames().

Default:
{}

cacheNames

@AliasFor(value="value")
public abstract String[] cacheNames

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

Names may be used to determine the target cache (or caches), matching the qualifier value or bean name
of a specific bean definition.

Since:
4.2

https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/Cacheable.html 2/6
10/11/2020 Cacheable (Spring Framework 5.2.9.RELEASE API)

See Also:
value(), CacheConfig.cacheNames()

Default:
{}

key

public abstract 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.

Default:
""

keyGenerator

public abstract String keyGenerator

The bean name of the custom KeyGenerator to use.

Mutually exclusive with the key() attribute.

See Also:
CacheConfig.keyGenerator()

Default:
""

cacheManager

https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/Cacheable.html 3/6
10/11/2020 Cacheable (Spring Framework 5.2.9.RELEASE API)

public abstract String cacheManager

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

Mutually exclusive with the cacheResolver() attribute.

See Also:
SimpleCacheResolver, CacheConfig.cacheManager()

Default:
""

cacheResolver

public abstract String cacheResolver

The bean name of the custom CacheResolver to use.

See Also:
CacheConfig.cacheResolver()

Default:
""

condition

public abstract String condition

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

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.

Default:
""

https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/Cacheable.html 4/6
10/11/2020 Cacheable (Spring Framework 5.2.9.RELEASE API)

unless

public abstract String unless

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

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

Default:
""

sync

public abstract 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 actual cache provider that you are using may not support it in a
synchronized fashion. Check your provider documentation for more details on the actual semantics.

Since:
4.3
See Also:
Cache.get(Object, Callable)

Default:
false

https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/Cacheable.html 5/6
10/11/2020 Cacheable (Spring Framework 5.2.9.RELEASE API)

Spring Framework
OVERVIEW PACKAGE CLASS USE TREE DEPRECATED INDEX HELP

PREV CLASS NEXT CLASS FRAMES NO FRAMES ALL CLASSES

https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/cache/annotation/Cacheable.html 6/6