Mastering Spring Boot’s @ConditionalOnProperty: Controlling Auto‑Configuration

What Is @ConditionalOnProperty?

The @ConditionalOnProperty annotation is a meta‑annotation used in Spring Boot’s auto‑configuration classes to decide whether a particular configuration should be applied based on the presence and value of a property in the environment.

Typical Usage in Spring Boot

Many core auto‑configuration classes employ this annotation. Two representative examples are shown below.

@Configuration(proxyBeanMethods = false)
@EnableConfigurationProperties(HttpProperties.class)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
@ConditionalOnClass(CharacterEncodingFilter.class)
@ConditionalOnProperty(prefix = "spring.http.encoding", value = "enabled", matchIfMissing = true)
public class HttpEncodingAutoConfiguration {
    // ... omitted internal code ...
}

In this class the property spring.http.encoding.enabled (prefix spring.http.encoding plus value enabled) determines whether the HTTP encoding auto‑configuration is activated.

@Configuration(proxyBeanMethods = false)
@ConditionalOnClass(org.apache.tomcat.jdbc.pool.DataSource.class)
@ConditionalOnMissingBean(DataSource.class)
@ConditionalOnProperty(name = "spring.datasource.type", havingValue = "org.apache.tomcat.jdbc.pool.DataSource",
    matchIfMissing = true)
static class Tomcat {
    // ... omitted internal code ...
}

Here the property spring.datasource.type must equal org.apache.tomcat.jdbc.pool.DataSource for the Tomcat‑specific data source configuration to take effect.

Source Code of @ConditionalOnProperty

@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.TYPE, ElementType.METHOD })
@Documented
@Conditional(OnPropertyCondition.class)
public @interface ConditionalOnProperty {

    // Array of property names; cannot be used together with <code>name</code>
    String[] value() default {};

    // Prefix for the property, e.g., "spring.http.encoding"
    String prefix() default "";

    // Full or partial property names; can be combined with <code>prefix</code>
    String[] name() default {};

    // Value to compare against; the condition matches only if the property value equals this
    String havingValue() default "";

    // If true, the condition matches even when the property is missing
    boolean matchIfMissing default false;
}

Earlier versions also contained a relaxedNames attribute for loose matching, which has been removed in recent releases:

// Whether relaxed matching is allowed
boolean relaxedNames() default true;

How the Attributes Work

matchIfMissing : When false (the default), the auto‑configuration is disabled if the property is absent. Setting it to true makes the configuration apply even without an explicit property.

name (or value when using a prefix): The property key read from application.properties or other property sources. For the Tomcat example the key is spring.datasource.type.

havingValue : The expected value of the property. If omitted, the condition matches when the property resolves to true.

prefix + value: An alternative way to specify the full property name. In HttpEncodingAutoConfiguration the prefix is spring.http.encoding and the value is enabled, forming spring.http.encoding.enabled.

If the property is missing and matchIfMissing is false, the condition returns false and the related auto‑configuration class is not loaded.

Practical Example

To enable HTTP encoding auto‑configuration, add the following line to application.properties:

spring.http.encoding.enabled=true

Because matchIfMissing is true in this case, the configuration would also be applied when the property is omitted.

Understanding these attributes allows developers to fine‑tune Spring Boot’s auto‑configuration behavior, turning features on or off precisely through external configuration.