# How to Customize CoCache Auto-Configuration Using CoCacheProperties

> Customize CoCache auto-configuration with CoCacheProperties. Disable CoCache entirely or add custom fields for advanced cache bean configuration. Learn more now.

- Repository: [Ahoo Wang/cocache](https://github.com/ahoo-wang/cocache)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Set `cocache.enabled=false` in your [`application.yaml`](https://github.com/ahoo-wang/cocache/blob/main/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`](https://github.com/ahoo-wang/cocache/blob/main/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`](https://github.com/ahoo-wang/cocache/blob/main/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`](https://github.com/ahoo-wang/cocache/blob/main/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.

```yaml

# 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`.

```kotlin
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:

```kotlin
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`](https://github.com/ahoo-wang/cocache/blob/main/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.