Mastering Spring @Conditional: 13 Conditional Annotations Explained

When building a Spring application, you may want to load a bean only if certain conditions are satisfied. In Spring 4 you could achieve this with the @Conditional annotation.

The @Conditional annotation accepts a class that implements the Condition interface; you simply implement the matches method to define the boolean logic.

Spring Boot refines @Conditional by providing a set of predefined annotations under the org.springframework.boot.autoconfigure.condition package, allowing you to avoid writing custom Condition classes.

Annotation Details

The 13 built‑in annotations share the same meta‑annotation @Conditional and can be applied to TYPE (e.g., @Configuration, @Component, @Service, @Repository, @Controller) as well as to @Bean methods. @ConditionalOnProperty: loads a bean when a property (e.g., mybean.enable=true) is present; matchIfMissing defaults to false. @ConditionalOnBean and @ConditionalOnMissingBean: load a bean only if another bean is present or absent, respectively. @ConditionalOnClass and @ConditionalOnMissingClass: check for the presence or absence of a class on the classpath. @ConditionalOnExpression: evaluate a SpEL expression; the bean loads only when the expression evaluates to true. @ConditionalOnSingleCandidate: matches when a single candidate bean of a type exists (or a primary bean is designated). @ConditionalOnResource: loads a bean only if a specific resource exists on the classpath. @ConditionalOnJndi: loads a bean only after a JNDI resource can be located. @ConditionalOnJava: matches when the application runs on a specific Java version. @ConditionalOnWebApplication and @ConditionalOnNotWebApplication: load beans only in web or non‑web environments. @ConditionalOnCloudPlatform: loads a bean only when running on a particular cloud platform (enum defined in org.springframework.boot.cloud).

Combined Conditions

Multiple conditions can be combined using logical AND by simply placing several @ConditionalOnXxx annotations on a class or by extending AllNestedConditions. For OR logic, extend AnyNestedCondition. For NOT logic, extend NoneNestedConditions.

Custom Annotations

To create your own conditional annotation, implement a class that implements Condition and annotate your custom annotation with @Conditional. Then apply it wherever needed.

Summary

These annotations essentially provide if‑then‑else behavior for bean registration, giving you fine‑grained control over Spring’s application context.