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.