1. Overview
In this tutorial, we’ll have a look at Flips, a library that implements feature flags in the form of powerful annotations for Spring Core, Spring MVC, and Spring Boot applications.
Feature flags (or toggles) are a pattern for delivering new features quickly and safely. These toggles allow us to modify application behavior without changing or deploying new code. Martin Fowler’s blog has a very informative article about feature flags here.
2. Maven Dependency
Before we get started, we need to add the Flips library to our pom.xml:
<dependency> <groupId>com.github.feature-flip</groupId> <artifactId>flips-core</artifactId> <version>1.0.1</version> </dependency>
Maven Central has the latest version of the library, and the Github project is here.
Of course, we also need to include a Spring:
<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> <version>1.5.10.RELEASE</version> </dependency>
Since Flips isn’t yet compatible with Spring version 5.x, we’re going to use the latest version of Spring Boot in the 4.x branch.
3. A Simple REST Service for Flips
Let’s put together a simple Spring Boot project for adding and toggling new features and flags.
Our REST application will provide access to Foo resources:
public class Foo { private String name; private int id; }
We’ll simply create a Service that maintains a list of Foos:
@Service public class FlipService { private List<Foo> foos; public List<Foo> getAllFoos() { return foos; } public Foo getNewFoo() { return new Foo("New Foo!", 99); } }
We’ll refer to additional service methods as we go, but this snippet should be enough to illustrate what FlipService does in the system.
And of course, we need to create a Controller:
@RestController public class FlipController { private FlipService flipService; // constructors @GetMapping("/foos") public List<Foo> getAllFoos() { return flipService.getAllFoos(); } }
4. Control Features Based on Configuration
The most basic use of Flips is to enable or disable a feature based on configuration. Flips has several annotations for this.
4.1. Environment Property
Let’s imagine we added a new capability to FlipService; retrieving Foos by their id.
Let’s add the new request to the controller:
@GetMapping("/foos/{id}") @FlipOnEnvironmentProperty( property = "feature.foo.by.id", expectedValue = "Y") public Foo getFooById(@PathVariable int id) { return flipService.getFooById(id) .orElse(new Foo("Not Found", -1)); }
The @FlipOnEnvironmentProperty controls whether or not this API is available.
Simply put, when feature.foo.by.id is Y, we can make requests by Id. If it isn’t (or not defined at all) Flips will disable the API method.
If a feature isn’t enabled, Flips will throw FeatureNotEnabledException and Spring will return “Not Implemented” to the REST client.
When we call the API with the property set to N, this is what we see:
Status = 501 Headers = {Content-Type=[application/json;charset=UTF-8]} Content type = application/json;charset=UTF-8 Body = { "errorMessage": "Feature not enabled, identified by method public com.baeldung.flips.model.Foo com.baeldung.flips.controller.FlipController.getFooById(int)", "className":"com.baeldung.flips.controller.FlipController", "featureName":"getFooById" }
As expected, Spring catches the FeatureNotEnabledException and returns status 501 to the client.
4.2. Active Profile
Spring has long given us the ability to map beans to different profiles, such as dev, test, or prod. Expanding on this capability to mapping feature flags to the active profile makes intuitive sense.
Let’s see how features are enabled or disabled based on the active Spring Profile:
@RequestMapping(value = "/foos", method = RequestMethod.GET) @FlipOnProfiles(activeProfiles = "dev") public List getAllFoos() { return flipService.getAllFoos(); }
The @FlipOnProfiles annotation accepts a list of profile names. If the active profile is in the list, the API is accessible.
4.3. Spring Expressions
Spring’s Expression Language (SpEL) is the powerful mechanism for manipulating the runtime environment. Flips has us a way to toggle features with it as well.
@FlipOnSpringExpression toggles a method based on a SpEL expression that returns a boolean.
Let’s use a simple expression to control a new feature:
@FlipOnSpringExpression(expression = "(2 + 2) == 4") @GetMapping("/foo/new") public Foo getNewFoo() { return flipService.getNewFoo(); }
4.4. Disable
To disable a feature completely, use @FlipOff:
@GetMapping("/foo/first") @FlipOff public Foo getFirstFoo() { return flipService.getLastFoo(); }
In this example, getFirstFoo() is completely inaccessible.
As we’ll see below, we can combine Flips annotations, making it possible to use @FlipOff to disable a feature based on the environment or other criteria.
5. Control Features with Date/Time
Flips can toggle a feature based on a date/time or the day of the week. Tying the availability of a new feature to the day or date has obvious advantages.
5.1. Date and Time
@FlipOnDateTime accepts the name of a property that is formatted in ISO 8601 format.
So let’s set a property indicating a new feature that will be active on March 1st:
first.active.after=2018-03-01T00:00:00Z
Then we’ll write an API for retrieving the first Foo:
@GetMapping("/foo/first") @FlipOnDateTime(cutoffDateTimeProperty = "first.active.after") public Foo getFirstFoo() { return flipService.getLastFoo(); }
Flips will check the named property. If the property exists and the specified date/time have passed, the feature is enabled.
5.2. Day of Week
The library provides @FlipOnDaysOfWeek, which is useful for operations such as A/B testing:
@GetMapping("/foo/{id}") @FlipOnDaysOfWeek(daysOfWeek={DayOfWeek.MONDAY, DayOfWeek.WEDNESDAY}) public Foo getFooByNewId(@PathVariable int id) { return flipService.getFooById(id).orElse(new Foo("Not Found", -1)); }
getFooByNewId() is only available on Mondays and Wednesdays.
6. Replace a Bean
Switching methods on and off is useful, but we may want to introduce new behavior via new objects. @FlipBean directs Flips to call a method in a new bean.
A Flips annotation can work on any Spring @Component. So far, we’ve only modified our @RestController, let’s try modifying our Service.
We’ll create a new service with different behavior from FlipService:
@Service public class NewFlipService { public Foo getNewFoo() { return new Foo("Shiny New Foo!", 100); } }
We will replace the old service’s getNewFoo() with the new version:
@FlipBean(with = NewFlipService.class) public Foo getNewFoo() { return new Foo("New Foo!", 99); }
Flips will direct calls to getNewThing() to NewFlipService. @FlipBean is another toggle that is most useful when combined with others. Let’s look at that now.
7. Combining Toggles
We combine toggles by specifying more than one. Flips evaluates these in sequence, with implicit “AND” logic. Therefore all of them must be true to toggle the feature on.
Let’s combine two of our previous examples:
@FlipBean( with = NewFlipService.class) @FlipOnEnvironmentProperty( property = "feature.foo.by.id", expectedValue = "Y") public Foo getNewFoo() { return new Foo("New Foo!", 99); }
We’ve made use of the new service configurable.
8. Conclusion
In this brief guide, we created a simple Spring Boot service and toggled APIs on and off using Flips annotations. We saw how features are toggled using configuration information and date/time, and also how features can be toggled by swapping beans at runtime.
Code samples, as always, can be found over on GitHub.