Welcome to the Firefly Common Cache Library documentation! This directory contains comprehensive guides and references to help you use the library effectively.

• Quick Start Guide - Get up and running in minutes

  • Installation instructions
  • Basic configuration
  • First cache operations
  • Verification steps

• Auto-Configuration Guide - Spring Boot auto-configuration

  • How auto-configuration works
  • Configuration properties
  • Conditional beans
  • Customization options
  • Testing auto-configuration

• Architecture Guide - Understand how it works

  • Hexagonal architecture overview
  • Core components and their responsibilities
  • Design patterns used
  • Package structure
  • Extension points

• Configuration Reference - Complete configuration guide

  • Global configuration options
  • Caffeine cache configuration
  • Redis cache configuration
  • Multiple cache instances
  • Environment-specific settings
  • Best practices

• API Reference - Detailed API documentation

  • FireflyCacheManager API
  • CacheAdapter interface
  • Annotations (@Cacheable, @CacheEvict, @CachePut)
  • Configuration classes
  • Health and statistics APIs
  • Exception handling

• Examples - Real-world usage examples

  • Basic usage patterns
  • User service example
  • Product catalog caching
  • Session management
  • Rate limiting
  • Cache-aside pattern
  • Write-through pattern
  • Multi-level caching
  • Error handling

• Monitoring Guide - Observability and metrics

  • Health checks
  • Metrics collection
  • Statistics API
  • Spring Boot Actuator integration
  • Logging configuration
  • Alerting strategies
  • Dashboard examples

• Testing Guide - Testing strategies

  • Unit testing with mocks
  • Integration testing
  • Testing with Caffeine
  • Testing with Redis (TestContainers)
  • Mocking strategies
  • Test configuration
  • Best practices

Get started quickly → Quick Start Guide

Understand the architecture → Architecture Guide

Configure the cache → Configuration Reference

See code examples → Examples

Look up API details → API Reference

Set up monitoring → Monitoring Guide

Write tests → Testing Guide

1. Start with Quick Start Guide
2. Review Examples for common patterns
3. Read Configuration Reference for your use case

1. Study Architecture Guide to understand internals
2. Explore API Reference for detailed API information
3. Set up Monitoring for production readiness
4. Review Testing Guide for comprehensive testing

• Basic Configuration
• Caffeine Setup
• Redis Setup
• Multiple Caches

• Cache-Aside Pattern
• Write-Through Pattern
• Session Management
• Rate Limiting

• Health Checks
• Metrics Collection
• Statistics
• Logging

• Unit Tests
• Integration Tests
• Redis Tests with TestContainers
• Mocking Strategies

Clean separation between business logic and infrastructure. Learn more in Architecture Guide.

Support for Caffeine (in-memory), Redis (distributed), Hazelcast (distributed in-memory grid), and JCache (JSR‑107 providers like Ehcache/Infinispan). See Configuration Reference.

Non-blocking operations using Project Reactor. Examples in API Reference.

Built-in health checks, metrics, and statistics. Details in Monitoring Guide.

Designed for testability with mocking support. Guide in Testing Guide.

• Main README - Project overview
• GitHub Repository
• Caffeine Documentation
• Redis Documentation
• Spring Boot Documentation
• Project Reactor Documentation

All code examples are tested and reflect the actual API. They use:

• Java 25 syntax (Java 21+ compatible)
• Spring Boot 3.5+
• Reactive programming with Reactor
• Lombok for brevity

Configuration examples use YAML format (application.yml) but can be adapted to:

• Properties format (application.properties)
• Environment variables
• Programmatic configuration

• ${VARIABLE} - Environment variable
• PT1H - ISO-8601 duration (1 hour)
• localhost - Replace with actual host
• default - Default cache name

Found an error or want to improve the documentation?

1. Check the Contributing Guidelines
2. Submit an issue or pull request
3. Follow the documentation style guide

This documentation is part of the Firefly Common Cache Library and is licensed under the Apache License 2.0.

Need help? Check the Troubleshooting section in the main README or open an issue on GitHub.