Package org.springframework.cache.annotation

# Annotation Interface Cacheable

@Target({TYPE,METHOD}) @Retention(RUNTIME) @Inherited @Documented @Reflective 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 will be stored in the associated cache. Note that `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.

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
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.
`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 Details

### value

@AliasFor("cacheNames") String[] value
Alias for `cacheNames()`.

Default:
  {}

### cacheNames

@AliasFor("value") 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 `CacheManager.getCache(java.lang.String)`.

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 (for example, 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 (for example, with Caffeine).

Since:
  4.2
See Also:
  - `value()`
  - `CacheConfig.cacheNames()`

Default:
  {}

### key

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

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

Mutually exclusive with the `key()` attribute.

See Also:
  - `CacheConfig.keyGenerator()`

Default:
  ""

### cacheManager

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

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

See Also:
  - `CacheConfig.cacheResolver()`

Default:
  ""

### condition

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.

Default:
  ""

### unless

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

Default:
  ""

### sync

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:
  - `Cache.get(Object, Callable)`

Default:
  false