How to Customize CoCache Auto-Configuration Using CoCacheProperties

Set cocache.enabled=false in your application.yaml to disable CoCache entirely, or extend CoCacheProperties with custom fields to inject additional configuration into your cache beans.

CoCache, the high-performance caching framework from the ahoo-wang/cocache repository, integrates with Spring Boot through a centralized auto-configuration system. You can customize CoCache auto-configuration by manipulating the CoCacheProperties class, which binds configuration values under the cocache property prefix and controls whether the framework initializes at runtime.

Understanding CoCacheProperties Structure

The CoCacheProperties class serves as the primary configuration anchor for the Spring Boot starter. Located at cocache-spring-boot-starter/src/main/kotlin/me/ahoo/cache/spring/boot/starter/CoCacheProperties.kt, this class defines the enabled property that determines whether CoCache auto-configuration should execute.

The class is annotated with @ConfigurationProperties(prefix = CoCache.COCACHE), where the constant CoCache.COCACHE resolves to the string "cocache". This means all configuration values reside under the cocache namespace in your property files. By default, the enabled field is set to true, ensuring that CoCache initializes automatically when the starter is present on the classpath.

Disabling CoCache with the Enabled Flag

To conditionally disable the entire CoCache subsystem, set the cocache.enabled property to false. The framework uses the custom annotation @ConditionalOnCoCacheEnabled, defined in cocache-spring-boot-starter/src/main/kotlin/me/ahoo/cache/spring/boot/starter/ConditionalOnCoCacheEnabled.kt, to check this property before loading CoCacheAutoConfiguration.

When enabled is false, the auto-configuration class located at cocache-spring-boot-starter/src/main/kotlin/me/ahoo/cache/spring/boot/starter/CoCacheAutoConfiguration.kt does not register any beans, allowing you to run tests or specific profiles without cache infrastructure.

# application-test.yaml

cocache:
  enabled: false

This is particularly useful for integration tests where you want to avoid starting embedded Redis instances or cache managers.

Extending Configuration with Custom Properties

You can extend CoCacheProperties to introduce domain-specific configuration values such as custom TTL durations or serialization settings. Create a data class that includes the original enabled field plus your additional properties, then register it with @EnableConfigurationProperties.

import me.ahoo.cache.api.annotation.CoCache
import org.springframework.boot.context.properties.ConfigurationProperties
import org.springframework.boot.context.properties.EnableConfigurationProperties
import org.springframework.context.annotation.Configuration
import java.time.Duration

@ConfigurationProperties(prefix = CoCache.COCACHE)
data class ExtendedCoCacheProperties(
    val enabled: Boolean = true,
    val defaultTtl: Duration = Duration.ofMinutes(10),
    val maxEntries: Int = 1000
)

@Configuration
@EnableConfigurationProperties(ExtendedCoCacheProperties::class)
class CustomCoCacheConfiguration

Spring Boot binds any cocache.* properties to your extended class automatically, allowing you to inject ExtendedCoCacheProperties into custom bean definitions.

Overriding Default Beans Conditionally

The CoCacheAutoConfiguration class declares core infrastructure beans such as CoCacheManager, CacheFactory, and CacheEvictedEventBus using @ConditionalOnMissingBean. This design allows you to provide custom implementations that replace the defaults without disabling auto-configuration entirely.

For example, to replace the default CacheEvictedEventBus with a custom implementation while retaining other auto-configured components:

import me.ahoo.cache.spring.boot.starter.CoCacheAutoConfiguration
import org.springframework.context.annotation.Bean
import org.springframework.context.annotation.Configuration

@Configuration
class CustomCacheEvictedConfig {

    @Bean
    fun cacheEvictedEventBus(): CacheEvictedEventBus {
        return MyCustomCacheEvictedEventBus()
    }
}

Because CoCacheAutoConfiguration defines its cacheEvictedEventBus bean with @ConditionalOnMissingBean(CacheEvictedEventBus::class), Spring detects your custom bean and skips the default RedisCacheEvictedEventBus registration.

Summary

• CoCacheProperties controls whether CoCache initializes via the cocache.enabled property, which defaults to true.
• Set cocache.enabled=false to skip CoCacheAutoConfiguration entirely, useful for testing profiles.
• Extend CoCacheProperties with custom fields under the cocache prefix to expose additional configuration options.
• Override specific beans like CacheEvictedEventBus or CoCacheManager by defining your own @Bean; the auto-configuration respects @ConditionalOnMissingBean and backs off automatically.
• All configuration classes reside in cocache-spring-boot-starter/src/main/kotlin/me/ahoo/cache/spring/boot/starter/.

Frequently Asked Questions

How do I completely disable CoCache in Spring Boot?

Set the property cocache.enabled=false in your application.properties or application.yaml file. The @ConditionalOnCoCacheEnabled annotation checks this value, and when false, prevents CoCacheAutoConfiguration from loading any cache beans into the application context.

Can I add custom properties to CoCacheProperties?

Yes. Extend the CoCacheProperties class (or create a new @ConfigurationProperties class with prefix CoCache.COCACHE) and add your custom fields. Spring Boot binds all cocache.* properties to your class, allowing you to inject configuration values like custom TTLs or cache sizes into your bean definitions.

How does CoCacheAutoConfiguration handle bean overrides?

CoCacheAutoConfiguration uses @ConditionalOnMissingBean on all its bean definitions, including CoCacheManager and CacheEvictedEventBus. If you define a bean of the same type in your own configuration, Spring Boot detects it and excludes the auto-configured version, allowing seamless customization of specific components without rewriting the entire configuration.

What is the default property prefix for CoCache configuration?

The prefix is cocache, derived from the constant CoCache.COCACHE. All properties defined in CoCacheProperties and its subclasses bind under this namespace, so you configure the framework using keys like cocache.enabled or cocache.default-ttl in your YAML files.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}