/java-cache

name: java-cache
description: Use when the user asks to add caching, configure Redis or Caffeine cache, use @Cacheable/@CacheEvict/@CachePut, optimize repeated database or API calls, or review existing Spring Boot cache configuration.
version: 1.0.0
authors: [java-plugins contributors]
tags: [java, spring-boot, cache, redis, caffeine, spring-cache]
allowed-tools: [Read, Glob, Grep, Edit, Write]

Spring Cache Skill

Detect the cache provider in use, then apply the correct patterns.

Step 1 — Detect setup

Check `pom.xml` or `build.gradle`:

• `spring-boot-starter-data-redis` → Redis (Lettuce client by default)
• `spring-boot-starter-cache` + `caffeine` → Caffeine (in-process)
• `spring-boot-starter-cache` only → Simple (ConcurrentHashMap, dev only)
• None present → offer to add (recommend Caffeine for single-instance, Redis for multi-instance/distributed)

Check Spring Boot version:

• Boot 3.x → Lettuce 6.x, Caffeine 3.x
• Boot 2.x → Lettuce 5.x, Caffeine 2.x/3.x

---

Mode: `review`

User asks to review existing cache configuration. Check for:

• [ ] `@EnableCaching` present on a `@Configuration` class — missing it silently disables all cache annotations
• [ ] Cache names declared in `application.yml` with explicit TTL — no unnamed or unbounded caches
• [ ] `@Cacheable` methods are on Spring-managed beans (not `private`, not called within the same class — proxy bypass)
• [ ] Cache keys are deterministic — `@Cacheable(key = "#id")` not `#root.methodName` unless intentional
• [ ] `@CacheEvict` present wherever data is mutated — missing eviction causes stale cache
• [ ] `@CachePut` used to update cache on write — not a `@CacheEvict` + re-fetch pattern
• [ ] Redis serialization configured — default JDK serialization is not readable/portable; use `GenericJackson2JsonRedisSerializer`
• [ ] Redis TTL set — without `time-to-live`, entries never expire
• [ ] Caffeine `maximumSize` set — without it, cache grows unbounded and causes OOM
• [ ] Null values handled — `@Cacheable(unless = "#result == null")` to avoid caching nulls
• [ ] Cache metrics exposed: `management.metrics.cache.instrument=true`

---

Mode: `setup`

User asks to add caching from scratch.

Caffeine (recommended for single-instance apps)

1. Add `spring-boot-starter-cache` + `com.github.ben-manes.caffeine:caffeine` 2. Add `@EnableCaching` to a `@Configuration` class 3. Configure cache specs in `application.yml` — set `maximum-size` and `expire-after-write` 4. Annotate service methods with `@Cacheable`, `@CacheEvict`, `@CachePut`

Redis (recommended for multi-instance / distributed)

1. Add `spring-boot-starter-data-redis` 2. Configure `spring.data.redis.host/port` (Boot 3.x) or `spring.redis.host/port` (Boot 2.x) 3. Configure `RedisCacheConfiguration` bean — set TTL and use `GenericJackson2JsonRedisSerializer` 4. Add `@EnableCaching` and annotate service methods

See `references/patterns.md` for full configuration examples.

---

Mode: `cacheable`

User asks to cache the result of a method.

1. Place `@Cacheable(cacheNames = "products", key = "#id")` on the service method 2. The method must be on a Spring-managed bean and not `private` 3. The method must not call itself (proxy bypass) — extract to a separate bean if needed 4. Add `unless = "#result == null"` to avoid caching null results 5. Ensure the return type is `Serializable` (Redis) or any object (Caffeine) 6. Add a corresponding `@CacheEvict` on the update/delete method

---

Mode: `evict`

User asks to invalidate/evict cache entries on data changes.

• `@CacheEvict(cacheNames = "products", key = "#id")` — evict a single entry on update/delete
• `@CacheEvict(cacheNames = "products", allEntries = true)` — evict all entries (use sparingly)
• `@CacheEvict(beforeInvocation = true)` — evict before method runs (use when method may throw)
• For multi-cache eviction: `@Caching(evict = { @CacheEvict("products"), @CacheEvict("productList") })`

---

Mode: `redis`

User asks specifically for Redis cache configuration.

1. Add `spring-boot-starter-data-redis` 2. Configure connection: `spring.data.redis.host`, `spring.data.redis.port`, `spring.data.redis.password` 3. Define `RedisCacheManager` bean with:

• `GenericJackson2JsonRedisSerializer` for values (human-readable, portable)
• `StringRedisSerializer` for keys
• Default TTL + per-cache TTL overrides

4. Enable `@EnableCaching` 5. For Redis Cluster: set `spring.data.redis.cluster.nodes` 6. For Redis Sentinel: set `spring.data.redis.sentinel.master` and `nodes`

---

Output format

For **review mode**: list findings as `[CRITICAL] / [HIGH] / [MEDIUM] / [LOW]` with file:line references.

For **implementation modes**: show exact Maven/Gradle dependency, full `application.yml` block, and complete Java configuration + annotated example. State minimum Spring Boot version where it differs.