Initial commit

skills/spring-boot-cache/references/spring-framework-cache-docs.md

@@ -0,0 +1,116 @@
+# Spring Framework Cache Reference (Official)
+
+Curated excerpts from the official Spring Framework reference documentation
+covering caching fundamentals and annotation usage. Source pages are from the
+[Spring Framework Reference Guide 6.2](https://docs.spring.io/spring-framework/reference/6.2/-SNAPSHOT/integration/cache/).
+
+## Cache Abstraction Overview
+
+- **Purpose**: Transparently wrap expensive service methods and reuse results
+  resolved from configured cache managers.
+- **Enablement**:
+
+  ```java
+  @Configuration
+  @EnableCaching
+  public class CacheConfig {
+      @Bean
+      public CacheManager cacheManager() {
+          return new ConcurrentMapCacheManager("books");
+      }
+  }
+  ```
+
+  Source: [/integration/cache/annotations](https://docs.spring.io/spring-framework/reference/6.2/-SNAPSHOT/integration/cache/annotations)
+
+- **Supported return types**: `CompletableFuture`, Reactor `Mono`/`Flux`,
+  blocking objects, and collections are all cacheable. For async/reactive types,
+  Spring stores the resolved value and rehydrates it on retrieval.
+
+## Core Annotations
+
+### `@Cacheable`
+
+- Cache the method invocation result using the provided cache name and key.
+- Supports conditional caching with `condition` (pre-invocation) and `unless`
+  (post-invocation, access `#result`).
+
+```java
+@Cacheable(cacheNames = "book", condition = "#isbn.length() == 13", unless = "#result.hardback")
+public Book findBook(String isbn) { ... }
+```
+
+Source: [/integration/cache/annotations](https://docs.spring.io/spring-framework/reference/6.2/-SNAPSHOT/integration/cache/annotations)
+
+### `@CachePut` and `@CacheEvict`
+
+- `@CachePut`: Always run the method and update cache entry with fresh result.
+- `@CacheEvict`: Remove entries; use `allEntries = true` or `beforeInvocation`
+  for pre-call eviction.
+
+```java
+@CacheEvict(cacheNames = "books", key = "#isbn", beforeInvocation = true)
+public void reset(String isbn) { ... }
+```
+
+Source: [/integration/cache/annotations](https://docs.spring.io/spring-framework/reference/6.2/-SNAPSHOT/integration/cache/annotations)
+
+### `@Caching`
+
+- Bundle multiple cache operations on a single method:
+
+```java
+@Caching(evict = {
+    @CacheEvict("primary"),
+    @CacheEvict(cacheNames = "secondary", key = "#isbn")
+})
+public Book importBooks(String isbn) { ... }
+```
+
+Source: [/integration/cache/annotations](https://docs.spring.io/spring-framework/reference/6.2/-SNAPSHOT/integration/cache/annotations)
+
+## Store Configuration Highlights
+
+- **Caffeine**: Configure `CaffeineCacheManager` to create caches on demand.
+
+  ```java
+  @Bean
+  CacheManager cacheManager() {
+      return new CaffeineCacheManager();
+  }
+  ```
+
+  Source: [/integration/cache/store-configuration](https://docs.spring.io/spring-framework/reference/6.2/-SNAPSHOT/integration/cache/store-configuration)
+
+- **XML alternative**: Use `<cache:annotation-driven cache-manager="..."/>`
+  when annotation configuration is not feasible.
+
+  ```xml
+  <cache:annotation-driven cache-manager="cacheManager"/>
+  <bean id="cacheManager" class="org.springframework.cache.caffeine.CaffeineCacheManager"/>
+  ```
+
+  Source: [/integration/cache/declarative-xml](https://docs.spring.io/spring-framework/reference/6.2/-SNAPSHOT/integration/cache/declarative-xml)
+
+## Reactive and Async Support
+
+- `@Cacheable` works with asynchronous signatures:
+
+  ```java
+  @Cacheable("books")
+  public Mono<Book> findBook(ISBN isbn) { ... }
+  ```
+
+  ```java
+  @Cacheable(cacheNames = "foos", sync = true)
+  public CompletableFuture<Foo> executeExpensiveOperation(String id) { ... }
+  ```
+
+  Source: [/integration/cache/annotations](https://docs.spring.io/spring-framework/reference/6.2/-SNAPSHOT/integration/cache/annotations)
+
+## Additional Resources
+
+- [`spring-cache-doc-snippet.md`](spring-cache-doc-snippet.md): Excerpt of the
+  narrative caching overview from the Spring documentation.
+- Refer to [`cache-core-reference.md`](cache-core-reference.md) for expanded
+  API reference material and `cache-examples.md` for progressive examples.