Condition Evaluation Mechanism

Spring Boot’s auto-configuration is one of its most powerful features. Behind the scenes, it uses conditions to decide which beans or configurations should be applied. This is called the Condition Evaluation Mechanism.

What Are Conditions?

Condition evaluation is the process where Spring Boot decides whether a bean or configuration should be loaded into the ApplicationContext.

• If conditions are met → bean is created.
• If conditions fail → bean is skipped.

This mechanism allows Spring Boot to dynamically enable or disable features based on the environment, classpath, or other dependencies.

Spring Boot uses the @Conditional annotation as a base, along with many specialized annotations like @ConditionalOnProperty, @ConditionalOnClass, and @ConditionalOnMissingBean.

Key Components of Condition Evaluation

@Conditional

The base annotation used to mark beans or configuration classes conditionally.

@Conditional(OnMyCondition.class)
@Bean
public MyServicemyService() {
returnnewMyService();
}

• Takes a Condition class that contains the logic for bean creation.

Condition Interface

Custom conditions implement the Condition interface:

publicclassOnMyConditionimplementsCondition {
@Override
publicbooleanmatches(ConditionContext context, AnnotatedTypeMetadata metadata) {
return context.getEnvironment().containsProperty("my.feature.enabled");
    }
}

• The matches() method decides if a bean should be created.
• ConditionContext gives access to:
  • Environment → properties
  • BeanDefinitionRegistry → other beans
  • ClassLoader → check classpath
  • ResourceLoader → resources

ConditionEvaluationReport

Spring Boot maintains an internal report that tracks which conditions passed or failed:

• Helps debug auto-configuration issues.
• Can be viewed by enabling:

spring.main.log-startup-info=true

Example snippet from the report:

ConditionalOnClass: DataSource.class found
ConditionalOnProperty: spring.datasource.urlnotset → bean skipped

Common Conditional Annotations in Spring Boot

These annotations make Spring Boot auto-configuration flexible and adaptive.

How Conditions Are Evaluated Internally

1. Bean Definition Loading

• Spring scans all bean definitions.
• Beans annotated with @Conditional are identified.

2. Condition Evaluation

• Spring invokes Condition.matches() for each conditional bean.
• Checks environment, classpath, bean registry, and resources.

3. Bean Loading Decision

• Passed conditions → bean registered and instantiated.
• Failed conditions → bean skipped.

4. Reporting

• Result stored in ConditionEvaluationReport for debugging.

Condition Evaluation Order

Spring Boot evaluates conditions in a specific order:

1. Configuration Class Level Conditions

e.g., @ConditionalOnClass, @ConditionalOnProperty on @Configuration classes.

2. Bean Method Level Conditions

e.g., @ConditionalOnMissingBean, @ConditionalOnProperty on @Bean methods.

3. Global Context Conditions

e.g., @ConditionalOnWebApplication at the application context level.

Practical Examples

Example 1 – Conditional Bean on Property

@Bean
@ConditionalOnProperty(name = "feature.email.enabled", havingValue = "true")
public EmailService emailService() {
    return new EmailService();
}

• Bean is created only if feature.email.enabled=true in application.properties.

Example 2 – Conditional Bean on Classpath

@Bean
@ConditionalOnClass(name = "com.fasterxml.jackson.databind.ObjectMapper")
public JsonService jsonService() {
    return new JsonService();
}

• Bean is created only if Jackson library is on the classpath.

Example 3 – Conditional Missing Bean

@Bean
@ConditionalOnMissingBean(MyService.class)
public MyService defaultService() {
    return new DefaultMyService();
}

• Bean is created only if no other MyService bean exists.

How It Fits in Spring Boot Startup

Spring Boot evaluates conditions during the refreshContext() phase:

1. prepareEnvironment() → load configuration properties
2. createApplicationContext() → create context
3. load() → register bean definitions
4. Condition Evaluation → check all @Conditional rules
5. Beans are either instantiated or skipped

Conditional evaluation ensures safe, context-aware auto-configuration and prevents unnecessary bean creation.

Benefits of Condition Evaluation

• Enables smart, adaptive auto-configuration
• Prevents bean conflicts and redundant bean creation
• Makes applications modular and environment-aware
• Helps developers debug missing beans using ConditionEvaluationReport

Debugging Conditional Beans

Enable debug mode:

debug=true

Example log:

Auto-configuration'DataSourceAutoConfiguration' wasnot applied:
   -@ConditionalOnClass foundno bean'javax.sql.DataSource'

• Explains why a bean was not loaded.
• Saves hours of debugging in complex projects.

Key Takeaways

• Conditional beans control auto-configuration dynamically
• Spring evaluates conditions before bean instantiation during refreshContext()
• @Conditional and its derivatives are the foundation of Spring Boot auto-configuration
• ConditionEvaluationReport helps debug why beans were skipped
• Makes Spring Boot applications flexible, adaptive, and production-ready

Conclusion

The Condition Evaluation Mechanism is the backbone of Spring Boot’s auto-configuration magic.

It allows:

• Environment-specific bean creation
• Classpath-aware auto-configuration
• Safe, modular, and overridable applications

Understanding this mechanism is essential for building robust, flexible, and production-ready Spring Boot applications.