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

Annotation	Purpose
@ConditionalOnProperty	Load bean if a property exists or matches a value
@ConditionalOnClass	Load bean if a specific class is on the classpath
@ConditionalOnMissingBean	Load bean if no bean of the given type exists
@ConditionalOnBean	Load bean only if a specific bean exists
@ConditionalOnExpression	Load bean if a SpEL expression evaluates to true
@ConditionalOnResource	Load bean if a resource exists
@ConditionalOnWebApplication	Load bean only in a web context
@ConditionalOnNotWebApplication	Load bean only in a non-web context

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.