Caching with @Cacheable, @CachePut and @CacheEvict

Spring's cache abstraction is declarative. Enable it with @EnableCaching, annotate methods, and a proxy around the bean consults a cache before or after the call:

@Service
class ProductService {
    @Cacheable(cacheNames = "products", unless = "#result == null")
    public Product find(long id) { return repository.findById(id).orElse(null); }

    @CachePut(cacheNames = "products", key = "#product.id")
    public Product update(Product product) { return repository.save(product); }

    @CacheEvict(cacheNames = "products", key = "#id")
    public void delete(long id) { repository.deleteById(id); }
}

• @Cacheable — look the key up first. On a hit the method body does not run at all; on a miss it runs and its result is stored.
• @CachePut — the method always runs, and its result replaces the cached entry. Use it to keep the cache current on writes.
• @CacheEvict — remove one entry (or allEntries = true for the whole cache), by default after the method returns.

condition is evaluated before the call and decides whether the cache is used at all; unless is evaluated after, against #result, and vetoes storing it. Without unless = "#result == null", a null result is cached like any other value, so "not found" is remembered too.

The default key

Without a key attribute, SimpleKeyGenerator builds the key from the arguments only: no arguments gives an empty key, one argument is the key, several are wrapped together. The method name is not part of it. Two methods that share a cache name and take the same argument therefore read and write the same entry.

The model below builds the proxy with java.lang.reflect.Proxy, the JDK mechanism Spring can use for an interface-based bean: a handler reads a stand-in annotation for the cache name, uses the single argument as the key, and calls the real bean only on a miss. One version of the interface puts both methods in one cache, the other gives each its own:

1import java.lang.annotation.*;2import java.lang.reflect.*;3import java.util.*;4 5public class Solution {6    // A stand-in for @Cacheable: the proxy reads it at call time.7    @Retention(RetentionPolicy.RUNTIME) @Target(ElementType.METHOD)8    @interface Cached { String value(); }9 10    interface Shared {11        @Cached("catalog") String title(long isbn);12        @Cached("catalog") Integer copiesInStock(long isbn);13    }14    interface Separate {15        @Cached("titles") String title(long isbn);16        @Cached("stock") Integer copiesInStock(long isbn);17    }18 19    // The real bean: these bodies are what a cache hit skips.20    static class Books implements Shared, Separate {21        public String title(long isbn) { return "Dune (" + isbn + ")"; }22        public Integer copiesInStock(long isbn) { return 3; }23    }24 25    // Default key for a one-argument method: the argument itself.26    static <T> T cachingProxy(Class<T> type, Object target, List<String> bodyRuns) {27        Map<String, Map<Object, Object>> caches = new HashMap<>();28        InvocationHandler handler = (proxy, method, args) -> {29            String cacheName = method.getAnnotation(Cached.class).value();30            Map<Object, Object> cache = caches.computeIfAbsent(cacheName, n -> new HashMap<>());31            Object key = args[0];32            if (cache.containsKey(key)) return cache.get(key);33            bodyRuns.add(method.getName());34            Object result = method.invoke(target, args);35            cache.put(key, result);36            return result;37        };38        return type.cast(Proxy.newProxyInstance(type.getClassLoader(), new Class<?>[] { type }, handler));39    }40 41    static String attempt(java.util.function.Supplier<Object> call) {42        try {43            return String.valueOf(call.get());44        } catch (ClassCastException e) {45            return "ClassCastException";46        }47    }48 49    public static List<String> run() {50        List<String> sharedRuns = new ArrayList<>();51        Shared shared = cachingProxy(Shared.class, new Books(), sharedRuns);52        String s1 = attempt(() -> shared.title(42L));53        String s2 = attempt(() -> shared.title(42L));54        String s3 = attempt(() -> shared.copiesInStock(42L));55 56        List<String> separateRuns = new ArrayList<>();57        Separate separate = cachingProxy(Separate.class, new Books(), separateRuns);58        String p1 = attempt(() -> separate.title(42L));59        String p2 = attempt(() -> separate.copiesInStock(42L));60 61        return List.of(62            "one cache: title=" + s1 + ", title=" + s2 + ", stock=" + s3 + ", bodies run " + sharedRuns,63            "two caches: title=" + p1 + ", stock=" + p2 + ", bodies run " + separateRuns);64    }65}

When the two methods return different types, the collision does not even produce a plausible wrong value: the cached String comes back where an Integer is declared, and the caller gets a ClassCastException. Give each kind of data its own cache name, or write the key explicitly.

Where the entries live

Spring Boot picks a CacheManager from what is on the classpath — Caffeine, Redis, JCache and others — and falls back to a simple ConcurrentHashMap-based one. The fallback has no expiry and no size limit: fine for a demo, a memory leak in production. With Caffeine you set spring.cache.caffeine.spec=maximumSize=10000,expireAfterWrite=10m. The two expiry styles differ in what restarts the clock: expireAfterWrite counts from when the value was stored, so even a hot entry is reloaded regularly; expireAfterAccess counts from the last read or write, so an entry read often enough never expires and can stay stale indefinitely.

A local cache is per instance. With three instances behind a load balancer, an eviction on one leaves the other two serving the old value until their entries expire. Either accept bounded staleness with a short expiry, or use a shared cache such as Redis.

Because caching is done by a proxy, everything from the @Transactional lesson applies: a cached method called through this is not cached. And @Cacheable(sync = true) makes concurrent misses for the same key wait for one computation instead of all hitting the database (provider permitting).

Common mistakes

• Two methods caching into the same cache with the same argument, as in the example: one returns the other's value, or fails with a when their return types differ.