(camel) 01/01: CAMEL-11114: Add Cache Invalidation section to Cache EIP docs

[gn...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

gnodet pushed a commit to branch CAMEL-11114-cache-eip
in repository https://gitbox.apache.org/repos/asf/camel.git

commit 2dfbb8f6d0cd6210cb7b9a5085fa866b7e26b552
Author: Guillaume Nodet <gn...@gmail.com>
AuthorDate: Wed Aug 26 10:04:59 2026 +0200

    CAMEL-11114: Add Cache Invalidation section to Cache EIP docs
    
    Document how to programmatically invalidate cache entries by key using
    the underlying KeyValueRepository.delete(key) method, covering the
    use case of reacting to external change events from foreign systems.
    
    Co-Authored-By: Claude Opus 4.6 <no...@anthropic.com>
---
 .../main/docs/modules/eips/pages/cache-eip.adoc    | 74 ++++++++++++++++++++++
 1 file changed, 74 insertions(+)

diff --git a/core/camel-core-engine/src/main/docs/modules/eips/pages/cache-eip.adoc b/core/camel-core-engine/src/main/docs/modules/eips/pages/cache-eip.adoc
index 0b795de8a63d..cbfe4f2a9a46 100644
--- a/core/camel-core-engine/src/main/docs/modules/eips/pages/cache-eip.adoc
+++ b/core/camel-core-engine/src/main/docs/modules/eips/pages/cache-eip.adoc
@@ -158,3 +158,77 @@ from("direct:start")
 ----
 
 If a single `KeyValueRepository` bean exists in the registry, it is auto-discovered — no explicit reference needed.
+
+== Cache Invalidation
+
+The Cache EIP uses TTL-based expiration by default — entries expire automatically after the configured `ttl`.
+For scenarios where you need to invalidate a specific cache entry on demand (e.g. when a foreign system notifies you
+that data has changed), you can call `delete(key)` on the underlying `KeyValueRepository` directly.
+
+=== Invalidating from Another Route
+
+Register a named `KeyValueRepository` and share it between the caching route and an invalidation route:
+
+[source,java]
+----
+// Shared cache store
+@BindToRegistry("productCache")
+public KeyValueRepository productCache() {
+    return new MemoryKeyValueRepository();
+}
+----
+
+[source,java]
+----
+// Route that caches product lookups
+from("direct:getProduct")
+    .cache(simple("${header.productId}"))
+        .keyValueRepository("productCache")
+        .ttl("30m")
+        .to("http://product-service/api/product")
+    .end();
+
+// Route that invalidates on external change events
+from("jms:topic:product.changes")
+    .process(exchange -> {
+        String productId = exchange.getIn().getHeader("productId", String.class);
+        KeyValueRepository cache = exchange.getContext().getRegistry()
+            .lookupByNameAndType("productCache", KeyValueRepository.class);
+        cache.delete(productId);
+    })
+    .log("Invalidated cache for product ${header.productId}");
+----
+
+=== XML DSL
+
+[source,xml]
+----
+<route>
+  <from uri="direct:getProduct"/>
+  <cache keyValueRepository="productCache" ttl="30m">
+    <simple>${header.productId}</simple>
+    <to uri="http://product-service/api/product"/>
+  </cache>
+</route>
+
+<!-- Invalidation route -->
+<route>
+  <from uri="jms:topic:product.changes"/>
+  <bean ref="productCache" method="delete(${header.productId})"/>
+  <log message="Invalidated cache for product ${header.productId}"/>
+</route>
+----
+
+=== Clearing the Entire Cache
+
+To clear all entries from a `KeyValueRepository`, call `clear()`:
+
+[source,java]
+----
+from("direct:clearAll")
+    .process(exchange -> {
+        KeyValueRepository cache = exchange.getContext().getRegistry()
+            .lookupByNameAndType("productCache", KeyValueRepository.class);
+        cache.clear();
+    });
+----