Spring Boot Configuration: @ConditionalOnProperty

Hi everyone! Have you ever wondered how Spring Boot dynamically enables or disables components based on properties (e.g. application.properties)? Imagine a scenario where you want to load some beans only when a specific feature is turned on in your application. Actually, to load beans only when a specific property has a specific value.

There is one simple, Spring Boot's solution:?@ConditionalOnProperty and it’s here to save the day! ?? This powerful annotation makes your application more?flexible,?customizable, and?environment-friendly?by conditionally enabling beans or configurations.

In this article, I'll break down how the?@ConditionalOnProperty?works and show you how to use it effectively in your Spring Boot projects. So let’s start!

What is?@ConditionalOnProperty?

@ConditionalOnProperty?is a Spring Boot annotation used to conditionally include beans or configurations based on the presence (or absence) of a specific property in your application’s configuration files (application.yml?or application.properties).

It's a handy tool for feature toggling, environment-based configurations, and fine-grained control over application behavior.

Key attributes of?@ConditionalOnProperty

Here are the most commonly used attributes of?@ConditionalOnProperty:

• prefix:?The prefix of the property (e.g.,?feature.toggle from application.property file).
• name:?The specific property name (e.g.,?enabled).
• havingValue:?The value required for the condition to match (e.g.,?"true").
• matchIfMissing:?Whether the condition should match if the property is missing (default:?false).

One basic example of @ConditionalOnProperty

Let’s start with one basic example to better understand how this annotation works ?? I have created one Spring Boot App. The only dependency that I need is: spring-boot-starter-web (https://mvnrepository.com/artifact/org.springframework.boot/spring-boot-starter-web/3.4.0)

Of course, as always you can use https://start.spring.io/ ?to initialize an empty project with dependencies that you want to start with.

In this example, we’ll implement a?feature toggle*. Specifically, I’ll demonstrate how to manage two beans based on a single property. If the property has a specific value, Spring Boot will create the beans and enable the corresponding feature. Otherwise, the feature will remain disabled, and the beans will not be instantiated.

For this example, I’ll use a?Notification feature. The Notification feature will consist of:

• Controller?(NotificationApi.java) with a single method:?GET /notification.
• Service?(NotificationService.java) with a single method:?getNotification(), which returns the string:?"Hello from Notification Service".

Here’s the project structure:

“feature toggle*.” - A?feature toggle?(also known as a feature flag) is a software development technique that allows you to enable or disable specific features in your application without deploying new code. Instead of removing or adding code during deployment, the feature's availability is controlled through a configurable property or condition.

So first, I will define a property in?application.properties, which will be used to toggle our Notification feature. The property will have the initial value “false”.

Next, I will create a?@Service?class:?NotificationService.java. This class will act as a Spring Bean because I’m using the?@Service?annotation. Inside this class, I’ll create a method that returns a string. Now, our annotation?@ConditionalOnProperty can be used here. This annotation has two key attributes:

1. name: Specifies the name of the property in?application.properties?(in this case,?enable.notification).
2. havingValue: Defines the expected value for the condition to be true.

When the property has the specified value, the condition will evaluate to true, and Spring will create the?NotificationService?bean and inject it where needed.

I use the?NotificationService?bean in the?NotificationApi?class (controller class). This class is a?@RestController?and exposes one API endpoint:?GET /notification. The method in this controller calls the service and returns the string result. I also use the?@ConditionalOnProperty?annotation on this controller to ensure that if the Notification feature is disabled, Spring skips creating both the NotificationService and NotificationApi beans. This means that users will not be able to call?GET /notification?when the property has the value "false".

Testing time!

This is a straightforward example of how you can control the creation of Spring Beans using the?@ConditionalOnProperty?annotation.

Now you can try to start your spring boot app with the property:

And try to call your end-point:

GET https://localhost:8080/notification

The API call is run successful, and we are receiving the string response.

Then change it to a false value

And call the same end-point again.

We can see that our endpoint does not exist anymore, which means that the beans for service and controller are not even created.

Now it's the perfect time to see some key benefits of using it.

Why Use?@ConditionalOnProperty?

Here are the key benefits of using?@ConditionalOnProperty:

1. Feature Toggling:?Easily enable or disable features without code changes.
2. Environment-Specific Behavior:?Load beans or configurations based on environments (dev, test, prod).
3. Clean and Modular Code:?Reduces clutter by avoiding hardcoding conditional logic inside beans.
4. Improved Performance:?Beans that aren’t required won’t be loaded, reducing memory footprint.

Of course, there are always challenges when using this kind of technology and approach, so you need to be particularly careful of the following common mistakes.

Common mistakes:

1. Property Mismatch:?Ensure the property name and prefix exactly match the configuration file.
2. matchIfMissing Misuse:?Use?matchIfMissing = true?cautiously - it can lead to unexpected behavior if the property is missing.
3. Overuse of Conditional Beans:?Don’t go overboard with conditional annotations; they can make debugging more difficult if overused.

To wrap things up:

@ConditionalOnProperty?is a powerful and versatile tool for building dynamic and environment-sensitive applications in Spring Boot. It simplifies feature toggling, keeps your code modular, and ensures your application adapts seamlessly to different configurations.

So, next time you’re working on a Spring Boot project, give?@ConditionalOnProperty?a try and make your application smarter!

What about you? Write me in the comments if you used?@ConditionalOnProperty?in your projects? Share your thoughts, examples, and experiences in the comments below! ??

Until next time! Be curious, keep learning, and stay inspired.