Skip to content

AGENTS.md

Latest commit

 

History

History
118 lines (87 loc) · 6.67 KB

AGENTS.md

File metadata and controls

118 lines (87 loc) · 6.67 KB
Raw

JetCache Agent Instructions

Project Overview

JetCache is a Java cache abstraction library (groupId com.alicp.jetcache) providing uniform API over Redis (Jedis/Lettuce/Spring Data/Redisson), Caffeine, and LinkedHashMap. Supports annotations (@Cached, @CacheUpdate, @CacheInvalidate) and programmatic Cache API with two-level caching, TTL, auto-refresh, and distributed lock.

  • Source/target: Java 17 (compiled with -parameters, enforcer requires JDK 17+)
  • CI JDK: 17 (Temurin)
  • Version: 2.8.x-SNAPSHOT

Module Structure

jetcache-anno-api/     Annotations and constants only (no dependencies)
jetcache-core/         Core Cache API, CacheManager, embedded/external cache implementations
jetcache-anno/         Spring AOP-based annotation processing (depends on core)
jetcache-support/      Redis driver adapters:
  jetcache-redis/            Jedis 7.x
  jetcache-redis-lettuce/    Lettuce
  jetcache-redis-springdata/ Spring Data Redis 4.x (uses Lettuce, not Jedis)
  jetcache-redisson/         Redisson 4.x
jetcache-starter/      Spring Boot autoconfigure and starters:
  jetcache-autoconfigure/         Pulls all support modules (optional)
  jetcache-starter-redis/         etc.
jetcache-test/         All tests live here (aggregates all modules); uses JaCoCo for coverage
jetcache-parent/       Shared build config, PMD (Alibaba p3c rules), surefire settings
jetcache-bom/          Bill of Materials, dependency version management
samples/               NOT part of root build (separate pom, different groupId)

Dependency chain: anno-api <- core <- anno <- autoconfigure, core <- support/* <- starter/*.

Build & Test Commands

# Full build (no tests)
mvn -DskipTests clean install

# Run all tests (requires Redis, see below)
mvn clean test

# Run a single test class
mvn -pl jetcache-test test -Dtest=CacheHandlerTest

# Run a single test method
mvn -pl jetcache-test test -Dtest=CacheHandlerTest#testExpressionEvaluator

Surefire includes: **/Test*.java, **/*Test.java, **/*Tests.java, **/*TestCase.java. Surefire excludes @Tag("slow") tests (currently none tagged).

macOS: Tests Needing Redis

The docker-compose.yml uses network_mode: "host", which does not work on macOS Docker. Redis cluster tests skip themselves on Mac/Windows (runtime check in RedisLettuceCacheTest.checkOS()). To run the full suite on macOS, use the Docker-in-Docker approach from Building.txt:

docker compose up -d   # Linux only
# macOS alternative:
docker run -it --rm --network host -v $HOME/.m2:/root/.m2 -v $(pwd):/usr/src/mymaven -w /usr/src/mymaven maven:3.9-eclipse-temurin-17 mvn clean test

Quick local Redis for partial testing (Windows/Mac)

docker run --rm -it -p 6379-6381:6379-6381 -p 26379-26381:26379-26381 areyouok/redis-sentinel

This gives standalone + sentinel but not cluster mode. Cluster tests will skip.

Verification

mvn clean test           # after `docker compose up` on Linux
mvn verify               # also runs PMD check (Alibaba p3c ruleset)

Conventions

  • JUnit Jupiter only (JUnit 4 removed; no vintage engine). JUnit BOM version: 6.x
  • Test dependencies: JUnit Jupiter 6.x, Mockito 5.x, Spring Test
  • PMD uses Alibaba p3c rules (p3c-pmd:1.3.6) during verify phase
  • The -parameters javac flag is required for SpEL annotation key expressions to work (also must be set in IDE settings, not just pom)
  • samples/ has its own build chain with its own version of jetcache; it is not a module of the main build

Test Caveats

  • Tests can be flaky on busy machines: many tests use short sleep() to verify TTL/expiry behavior, so GC pauses or high load can cause false failures
  • Full test suite takes a few minutes to run
  • Tests needing Redis (e.g. RedisCacheTest, RedisLettuceCacheTest, RedissonCacheTest, starter tests) will fail or skip without a running Redis
  • Redis cluster tests auto-skip on Mac/Windows via RedisLettuceCacheTest.checkOS() — only standalone and sentinel tests work there

Compatibility Notes (see docs/EN/Compatibility.md)

  • Spring/Spring Boot version support varies by jetcache version; current (2.8.0) BOM defaults to Spring Framework 7.0.7 / Spring Boot 4.0.6 / Spring Data Redis 4.0.5 / SLF4J 2.x, but Spring 6.x / Spring Boot 3.x (also Java 17+) is also supported by adjusting BOM properties
  • jetcache-redis (Jedis 7.x) and jetcache-redis-springdata (Lettuce) use different Redis clients; jetcache-redis uses Jedis 7.x which may conflict with other Jedis versions on classpath
  • Since 2.8.0: fastjson1 is removed; the FASTJSON keyConvertor now uses fastjson2 internally. Default keyConvertor is fastjson2
  • Since 2.8.0: kryo4 is dropped. Both KRYO and KRYO5 constants now use kryo5 implementation internally (com.esotericsoftware:kryo is 5.6.2, same as com.esotericsoftware.kryo:kryo5). Old kryo4 serialized data is not compatible with kryo5
  • Since 2.8.0: Spring XML namespace support (<jetcache:xxx>) is removed
  • Since 2.8.0: Deserialization filter is enabled by default — a breaking change. Cached values containing custom classes not in the default allow list will fail to deserialize. Add decodeFilterAllowPatterns (e.g. com.yourcompany.) or set decodeFilterEnabled: false to restore old behavior. See docs/EN/Config.md for default allow list
  • Since 2.8.0: JACKSON3 added as valueEncoder/valueDecoder and keyConvertor option (uses tools.jackson 3.x)
  • areaInCacheName default changed to false in 2.7 (was true in 2.6 and earlier); since 2.8.0 this is also false
  • JSON serializers (fastjson2/jackson/jackson3) are not registered by default as valueEncoder/valueDecoder due to type-safety concerns with Object fields. Only java and kryo/kryo5 are registered
  • @Cached uses Spring AOP (proxy-based); self-invocation within the same class bypasses the cache

Key Convertor / Value Encoder-Decoder Choices (2.8)

  • keyConvertor: fastjson2 (default) / fastjson (same as fastjson2) / jackson / jackson3 / none (local only)
  • valueEncoder/valueDecoder: java (default) / kryo (kryo5 impl) / kryo5 (kryo5 impl). fastjson2 / jackson / jackson3 available but not registered by default

Code Reading Guide (see docs/CN/DevNote.md)

Key Cache interface implementations:

  • RedisCache / RedisLettuceCache / RedisSpringDataCache / RedissonCache: external Redis backends
  • CaffeineCache / LinkedHashMapCache: in-memory
  • LoadingCache: decorator adding auto-load via CacheLoader
  • RefreshCache: decorator adding auto-refresh
  • MultiLevelCache: multi-level (supports N levels, annotation config only uses 2)

Annotation processing entry points: EnableMethodCache, EnableCreateCacheAnnotation (in jetcache-anno)