Understanding Spring Cache’s @Cacheable Annotation

About Spring Cache

Since Spring 3.1, a new feature allows caching to be implemented via annotations. It provides an abstraction over concrete cache implementations, enabling developers to add caching with minimal code.

Explanation of @Cacheable

The @Cacheable annotation is placed on a method to indicate that its return value should be stored in a cache. Subsequent calls with the same parameters will first check the cache and skip method execution if a cached entry exists.

“Same parameters” means that each distinct combination of method arguments generates a separate cache key.

Below are the meanings of each attribute:

value / cacheNames

Specifies the name of the cache to use; both attributes are equivalent. Example:

@Cacheable(cacheNames = "busroute")
@Override
public List<buslineresp> findAllBusLines() throws ParamException {
    return null;
}

This means that when the method is invoked, Spring checks the “busroute” cache; if a hit occurs the method is not executed, otherwise the result is stored in that cache.

key / keyGenerator

When a method has parameters, Spring needs a way to distinguish cache entries. The key attribute lets you define a SpEL expression that builds a unique key from method arguments. Example:

@Cacheable(cacheNames = "busroute", key = "#root.methodName+'('+#lineId+')'", unless = "#result == null")
@Override
public List<buslinestationresp> findBusLineStations(String lineId) throws ParamException {
    return null;
}

Here the key combines the method name with the value of #lineId, so the cache entry is identified by both the cache name “busroute” and the specific line ID.

unless

The unless attribute provides a condition, expressed in SpEL, that determines whether the result should be cached. If the expression evaluates to true, the result is not stored. A common usage is to avoid caching null results:

@Cacheable(cacheNames = "busroute", key = "#root.methodName+'('+#lineId+')'", unless = "#result == null")

When the method returns null, the entry is not cached.

These are the most frequently used parameters of @Cacheable. Readers are encouraged to experiment and provide feedback.