Clean • Professional
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.
Condition evaluation is the process where Spring Boot decides whether a bean or configuration should be loaded into the ApplicationContext.
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.
The base annotation used to mark beans or configuration classes conditionally.
@Conditional(OnMyCondition.class)
@Bean
public MyServicemyService() {
returnnewMyService();
}
Custom conditions implement the Condition interface:
publicclassOnMyConditionimplementsCondition {
@Override
publicbooleanmatches(ConditionContext context, AnnotatedTypeMetadata metadata) {
return context.getEnvironment().containsProperty("my.feature.enabled");
}
}
matches() method decides if a bean should be created.ConditionContext gives access to:
Environment → propertiesBeanDefinitionRegistry → other beansClassLoader → check classpathResourceLoader → resourcesSpring Boot maintains an internal report that tracks which conditions passed or failed:
spring.main.log-startup-info=true
Example snippet from the report:
ConditionalOnClass: DataSource.class found
ConditionalOnProperty: spring.datasource.urlnotset → bean skipped
| 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.
1. Bean Definition Loading
@Conditional are identified.2. Condition Evaluation
Condition.matches() for each conditional bean.3. Bean Loading Decision
4. Reporting
ConditionEvaluationReport for debugging.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.
Example 1 – Conditional Bean on Property
@Bean
@ConditionalOnProperty(name = "feature.email.enabled", havingValue = "true")
public EmailService emailService() {
return new EmailService();
}
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();
}
Example 3 – Conditional Missing Bean
@Bean
@ConditionalOnMissingBean(MyService.class)
public MyService defaultService() {
return new DefaultMyService();
}
MyService bean exists.Spring Boot evaluates conditions during the refreshContext() phase:
prepareEnvironment() → load configuration propertiescreateApplicationContext() → create contextload() → register bean definitions@Conditional rulesConditional evaluation ensures safe, context-aware auto-configuration and prevents unnecessary bean creation.
ConditionEvaluationReportEnable debug mode:
debug=true
Example log:
Auto-configuration'DataSourceAutoConfiguration' wasnot applied:
-@ConditionalOnClass foundno bean'javax.sql.DataSource'
refreshContext()@Conditional and its derivatives are the foundation of Spring Boot auto-configurationThe Condition Evaluation Mechanism is the backbone of Spring Boot’s auto-configuration magic.
It allows:
Understanding this mechanism is essential for building robust, flexible, and production-ready Spring Boot applications.