Configuration Classes

Analogy categoryAnalogies

@Configuration and @Bean Methods

A class annotated with @Configuration declares a source of bean definitions using plain Java rather than annotations or XML: each method annotated with @Bean is invoked once by the container, and its return value is registered as a bean, named by default after the method name. Unlike a plain @Component, a full @Configuration class is CGLIB-proxied by default, which means that if one @Bean method calls another @Bean method directly within the same class, Spring intercepts that call and returns the already-created singleton instance rather than invoking the method body again — preserving singleton semantics even with plain Java method calls.

🏏

Cricket analogy: A franchise's team manual explicitly lists, in writing, exactly which player fills which role for the season, rather than leaving it to informal scouting, similar to how @Bean methods explicitly declare each bean rather than relying on classpath scanning.

java

@Configuration
public class DataSourceConfig {

    @Bean
    public HikariConfig hikariConfig() {
        HikariConfig config = new HikariConfig();
        config.setJdbcUrl("jdbc:postgresql://localhost:5432/orders");
        config.setMaximumPoolSize(10);
        return config;
    }

    @Bean
    public DataSource dataSource() {
        // Calling hikariConfig() here returns the same singleton instance,
        // not a freshly built HikariConfig, thanks to CGLIB proxying
        return new HikariDataSource(hikariConfig());
    }

    @Bean
    public JdbcTemplate jdbcTemplate(DataSource dataSource) {
        return new JdbcTemplate(dataSource);
    }
}

Importing and Composing Configuration

Large applications split configuration across multiple @Configuration classes for readability — for example, separating DataSourceConfig, SecurityConfig, and WebMvcConfig — and use @Import to explicitly pull one configuration class into another, or rely on component scanning to discover them all automatically if they carry @Configuration within the scanned package tree. @Import is particularly useful for composing configuration from external libraries or auto-configuration modules that live outside the application's own base package and therefore wouldn't be picked up by @ComponentScan.

🏏

Cricket analogy: A national team's coaching setup splits into a batting coach, bowling coach, and fielding coach, each responsible for one area, then the head coach explicitly assembles them into one staff, mirroring how @Import composes separate @Configuration classes.

Conditional Configuration

Spring Boot's auto-configuration mechanism, and custom configuration you write yourself, can use conditional annotations to activate beans only when certain criteria are met: @ConditionalOnProperty activates a bean only if a specified property has a specific (or any non-'false') value, @ConditionalOnClass activates a bean only if a given class is present on the classpath, and @ConditionalOnMissingBean activates a bean only if no other bean of that type has already been registered, which is how Spring Boot lets you override an auto-configured bean simply by defining your own — yours wins because the auto-configuration's @ConditionalOnMissingBean check finds your bean already present and backs off.

🏏

Cricket analogy: A stadium's roof only closes automatically if the weather sensor reports rain above a threshold, an environment-driven activation rule similar to @ConditionalOnProperty enabling a bean only when a property meets a specific value.

This is exactly the mechanism that lets you override a Spring Boot auto-configured bean, such as a default ObjectMapper, simply by declaring your own @Bean of the same type in your own @Configuration class — no need to exclude the auto-configuration explicitly, because it's written with @ConditionalOnMissingBean and will detect your bean and step aside.

@Configuration classes declare beans explicitly in Java using @Bean-annotated factory methods, giving full programmatic control.
@Configuration classes are CGLIB-proxied so that inter-bean method calls within the class return the same singleton instance rather than creating duplicates.
@Import explicitly composes separate configuration classes together, especially useful for classes outside the component-scanned package tree.
@ConditionalOnProperty, @ConditionalOnClass, and @ConditionalOnMissingBean control whether a bean is registered based on runtime conditions.
@ConditionalOnMissingBean is the mechanism that lets a user-defined bean silently override a Spring Boot auto-configured default.
Splitting configuration into focused classes (DataSourceConfig, SecurityConfig, etc.) improves readability in large applications.