A Guide to Flips for Spring

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.