Kora Aop Caching

Kora AOP Caching

Kora sub-skill — obey the kora-v2 meta rules on every task: R0 ground the workspace on Kora 2.0 refs before starting (framework source at tag 2.0.0.RC1 + kora-examples at migration/2.0; kora-docs is 1.x only) · R1 read this sub-skill before writing code · R2 Kora 2.0 APIs only — no Spring/Micronaut/Quarkus, no Kora 1.x APIs, no invented annotations or config keys · R3 journal any incorrect Kora usage. Add comments/Javadoc only if asked.

Read this skill when you are:

• adding @Cacheable / @CachePut / @CacheInvalidate / @CacheInvalidateAll to a service method
• declaring a typed @Cache interface and its config section
• choosing Caffeine (in-process) vs Redis (shared) or stacking both as L1/L2
• deriving a cache key with CacheKeyMapper and @Mapping
• porting Kora 1.x cache code (parameters =, invalidateAll = true, cache-redis)

1. What changed from Kora 1.x

A blind parameters → args search-and-replace is unsafe: HOCON and YAML files legitimately contain parameters = keys. Change only the cache annotations.

2. Quick start

2.1 Dependencies

koraVersion=2.0.0.RC1 from plain mavenCentral(); the BOM is io.koraframework:kora-bom. Never pin a version on an individual io.koraframework:* artifact.

dependencies {
    koraBom platform("io.koraframework:kora-bom:$koraVersion")
    annotationProcessor "io.koraframework:annotation-processors"   // mandatory

    implementation "io.koraframework:cache-caffeine"               // in-process
    // implementation "io.koraframework:cache-redis-lettuce"       // distributed
    // implementation "io.koraframework:json-common"               // only for @Json Redis values
}

Kotlin (build.gradle.kts):

dependencies {
    implementation(platform("io.koraframework:kora-bom:${property("koraVersion")}"))
    ksp("io.koraframework:symbol-processors:${property("koraVersion")}")
    implementation("io.koraframework:cache-caffeine")
}

Without the processor no $XxxCache_Impl, no $XxxCache_Module and no aspect is generated, and the graph fails with No component found for dependency: XxxCache (no tags).

2.2 Connect the module

@KoraApp
public interface Application extends HoconConfigModule, LogbackModule, CaffeineCacheModule {

    static void main(String[] args) {
        KoraApplication.run(ApplicationGraph::graph);
    }
}

Only the backend module goes on @KoraApp. The per-cache module $OrderCache_Module generated from your @Cache interface is discovered automatically — do not extend it.

2.3 Declare the typed cache

@Cache("orders.cache")
public interface OrderCache extends CaffeineCache<UUID, OrderDto> {}

@Cache targets an interface that extends exactly one of CaffeineCache<K, V> or RedisCache<K, V>; its value is the config path.

2.4 Annotate the methods

@Component
public class OrderService {                      // must not be final

    @Cacheable(OrderCache.class)
    public OrderDto get(UUID id) {
        return repository.find(id);
    }

    @CachePut(value = OrderCache.class, args = "id")
    public OrderDto update(UUID id, OrderRequest request) {
        return repository.save(id, request);
    }

    @CacheInvalidate(OrderCache.class)
    public void delete(UUID id) {
        repository.delete(id);
    }

    @CacheInvalidateAll(OrderCache.class)
    public void deleteAll() {
        repository.deleteAll();
    }
}

Kotlin: the class and every annotated function must be open.

@Component
open class OrderService(private val repository: OrderRepository) {

    @Cacheable(OrderCache::class)
    open fun get(id: UUID): OrderDto = repository.find(id)

    @CachePut(value = OrderCache::class, args = ["id"])
    open fun update(id: UUID, request: OrderRequest): OrderDto = repository.save(id, request)

    @CacheInvalidateAll(OrderCache::class)
    open fun deleteAll() = repository.deleteAll()
}

2.5 Configure

orders.cache {
  maximumSize = 10000
  expireAfterWrite = "10m"
}

3. The four operation annotations

All four take Class<? extends Cache<?, ?>> value(), and all are repeatable.

• args is String[] — the method parameter names that make up the key. Empty (the default) means all parameters, in declaration order. A single name may be written unbraced: args = "id".
• mode is CacheMode.SYNC (default) or CacheMode.ASYNC. See §6.
• @Cacheable and @CachePut reject void/Unit returns; all four reject Publisher and Future returns.
• One method carries one operation kind. Mixing kinds is a compile error.

Details, generated shapes and the exact diagnostics: cacheable-reference.md.

4. Cache keys

@Cache("orders.cache")
public interface OrderCache extends CaffeineCache<OrderCache.Key, OrderDto> {
    record Key(UUID tenantId, UUID orderId) {}
}

@Cacheable(OrderCache.class)
public OrderDto get(UUID tenantId, UUID orderId) { … }          // key = new Key(tenantId, orderId)

@Cacheable(value = OrderCache.class, args = { "orderId", "tenantId" })
public OrderDto find(UUID tenantId, String trace, UUID orderId) { … }  // key = new Key(orderId, tenantId)

Every class named in @Mapping must be a @Component — nested classes included. The cache processor always injects the mapper; unlike HTTP mappers it never constructs a dependency-free one itself, so a mapper without @Component fails with No component found for dependency.

See cache-key-mapper-reference.md.

5. Caffeine vs Redis

@Cache("orders.redis")
public interface OrderRedisCache extends RedisCache<UUID, @Json OrderDto> {}

The @Json on the value type argument is what selects the JSON RedisCacheValueMapper; the DTO itself also needs @Json so a JsonReader/JsonWriter is generated.

cache-caffeine-reference.md · cache-redis-reference.md

6. CacheMode

public enum CacheMode { SYNC, ASYNC }

SYNC (the default) performs the cache write or eviction on the calling thread. ASYNC hands the put / invalidate / invalidateAll to an Executor published by CacheCommonModule under @Tag(CacheMode.class); the default implementation starts one virtual thread named kora-cache-N per operation and logs failures as Cache asynchronous operation failed on thread {}.

• The cache read is never asynchronous; only the write side moves off-thread.
• ASYNC on a CaffeineCache is ignored, with the compile warning Cache async mode is ignored for CaffeineCache <fqn>.
• Use it for a Redis L2 whose write latency you do not want on the request path; accept that a failed write is only logged.
• Override the executor with your own @Component @Tag(CacheMode.class) Executor.

7. Multi-level (L1 Caffeine + L2 Redis)

Stack the annotations — first listed is checked first, and a deeper hit back-fills every shallower level.

@Cacheable(UserCaffeineCache.class)   // L1
@Cacheable(UserRedisCache.class)      // L2
public Optional<UserResponse> getUser(String id) {
    return userRepository.findById(id);
}

Repeated annotations on one method must use the same args list. See multi-level-cache-reference.md.

8. Imperative use

Cache<K, V> is injectable on its own — get, get(Collection), put, put(Map), computeIfAbsent, invalidate, invalidate(Collection), invalidateAll, plus asLoadableSimple(loader) / asLoadable(bulkLoader) for a LoadableCache.

@Component
public class OrderService {

    private final OrderCache cache;

    public OrderService(OrderCache cache) { this.cache = cache; }

    public OrderDto getOrLoad(UUID id) {
        return cache.computeIfAbsent(id, repository::find);
    }
}

See imperative-cache-reference.md.

9. Testing

@KoraAppTest(Application.class)
class OrderServiceTests {

    @TestComponent
    private OrderService service;
    @TestComponent
    private OrderCache cache;

    @BeforeEach
    void cleanup() {
        cache.invalidateAll();
    }

    @Test
    void servesSecondCallFromCache() {
        var id = UUID.randomUUID();
        assertEquals(service.get(id), service.get(id));
    }
}

@KoraAppTest / @TestComponent come from io.koraframework:test-junit5 (io.koraframework.test.extension.junit5). Field injection is done by the extension — do not add @Inject. Setting <cache-path>.maximumSize = 0 in a test config is the cheap way to disable a Caffeine cache for a test. See kora-testing-junit-java / kora-testing-junit-kotlin.

10. Pitfalls

11. Reference documents

12. Assets