Spring Conditional Annotations

1. Introduction

In this tutorial, we’ll take a look at the @Conditional annotation. It’s used to indicate whether a given component is eligible for registration based on a defined condition.

We’ll learn how to use predefined conditional annotations, combine them with different conditions, and create our own custom, condition-based annotations.

2. Declaring Conditions

Before we move into the implementation, let’s see in which situations we could make use of conditional annotations.

The most common usage would be to include or exclude the whole configuration class:

@Configuration
@Conditional(IsDevEnvCondition.class)
class DevEnvLoggingConfiguration {
    // ...
}

Or just a single bean:

@Configuration
class DevEnvLoggingConfiguration {
    
    @Bean
    @Conditional(IsDevEnvCondition.class)
    LoggingService loggingService() {
        return new LoggingService();
    }
}

By doing so, we can base the behavior of our application on given conditions, such as the type of environment, or specific needs of our clients. In the above example, we initialized additional logging services only for the development environment.

Another way of making the component conditional would be to place the condition directly on the component class:

@Service
@Conditional(IsDevEnvCondition.class)
class LoggingService {
    // ...
}

We can apply the above example to any bean declared with the @Component, @Service, @Repository, or @Controller annotations.

3. Predefined Conditional Annotations

Spring comes with a set of predefined conditional annotations. Let’s go through some of the most popular ones.

First, let’s see how we can base a component on a configuration property value:

@Service
@ConditionalOnProperty(
  value="logging.enabled", 
  havingValue = "true", 
  matchIfMissing = true)
class LoggingService {
    // ...
}

The first attribute, value, tells us what configuration property we’ll be looking at. The second one, havingValue, defines a value that’s required for this condition. And lastly, the matchIfMissing attribute tells Spring whether the condition should be matched if the parameter is missing.

Similarly, we can base the condition on an expression:

@Service
@ConditionalOnExpression(
  "${logging.enabled:true} and '${logging.level}'.equals('DEBUG')"
)
class LoggingService {
    // ...
}

Now Spring will create the LoggingService only when both the logging.enabled configuration property is set to true, and the logging.level is set to DEBUG.

Another condition we can apply is to check whether a given class exists on the classpath:

@Service
@ConditionalOnClass(CustomLogger.class)
class LoggingService {
    // ...
}

We can achieve the opposite behavior by applying the @ConditionalOnMissingBean or @ConditionalOnMissingClass annotations.

In addition, we can make our components depend on a given Java version:

@Service
@ConditionalOnJava(JavaVersion.EIGHT)
class LoggingService {
    // ...
}

In the above example, the LoggingService will be created only when the runtime environment is Java 8.

We can also use the @ConditionalOnWarDeployment annotation to enable bean only in war packaging:

@Configuration
@ConditionalOnWarDeployment
class AdditionalWebConfiguration {
    // ...
}

Note that for applications with embedded servers, this condition will return false.

Additionally, Spring Boot offers the @ConditionalOnBean annotation. Unlike other @ConditionalOn* annotations we’ve seen so far, @ConditionalOnBean can only match the bean definitions that have been processed by the application context. Therefore, we should only use it for auto-configuration classes. Speaking of Spring Boot auto-configurations, we have a dedicated article to explain how to create custom auto-configurations.

4. Defining Custom Conditions

Spring allows us to customize the behavior of the @Conditional annotation by creating our custom condition templates. To create one, we simply need to implement the Condition interface:

class Java8Condition implements Condition {
    @Override
    public boolean matches(ConditionContext context, AnnotatedTypeMetadata metadata) {
        return JavaVersion.getJavaVersion().equals(JavaVersion.EIGHT);
    }
}

The matches method tells Spring whether the condition has passed or not. It has two arguments that give us information about the context where the bean will initialize, and the metadata of the used @Conditional annotation.

As we can see in our example, we just check if the Java version is 8.

After that, we should place our new condition as an attribute in the @Conditional annotation:

@Service
@Conditional(Java8Condition.class)
public class Java8DependedService {
    // ...
}

This way, the Java8DependentService will be created only where the condition from Java8Condition class is matched.

5. Combining Conditions

For more complex solutions, we can group conditional annotations with OR or AND logical operators.

To apply the OR operator, we need to create a custom condition extending the AnyNestedCondition class. Inside it, we need to create an empty static class for each condition, and annotate it with a proper @Conditional implementation.

For example, let’s create a condition that requires either Java 8 or Java 9:

class Java8OrJava9 extends AnyNestedCondition {
    
    Java8OrJava9() {
        super(ConfigurationPhase.REGISTER_BEAN);
    }
    
    @Conditional(Java8Condition.class)
    static class Java8 { }
    
    @Conditional(Java9Condition.class)
    static class Java9 { }
    
}

The AND operator, on the other hand, is much simpler. We can simply group the conditions:

@Service
@Conditional({IsWindowsCondition.class, Java8Condition.class})
@ConditionalOnJava(JavaVersion.EIGHT)
public class LoggingService {
    // ...
}

In the above example, the LoggingService will be created only when the IsWindowsCondition and Java8Condition are matched.

6. Summary