Spring Boot Starter since 2.3.0

Getting Started

Add the Togglz Spring Boot Starter dependency to your project:

<dependency>
  <groupId>org.togglz</groupId>
  <artifactId>togglz-spring-boot-starter</artifactId>
  <version>2.4.1.Final</version>
</dependency>

Or when using Gradle simply:

compile("org.togglz:togglz-spring-boot-starter:2.4.1.Final")

The starter will not only add the togglz-core and togglz-spring-core modules to your project, it will also enable the auto configuration of the Togglz configration.

Optionally add the togglz-console, togglz-spring-security and thymeleaf-extras-togglz modules:

<!-- Togglz Admin Console (optional) -->
<dependency>
  <groupId>org.togglz</groupId>
  <artifactId>togglz-console</artifactId>
  <version>2.4.1.Final</version>
</dependency>

<!-- Togglz Spring Security (optional) -->
<dependency>
  <groupId>org.togglz</groupId>
  <artifactId>togglz-spring-security</artifactId>
  <version>2.4.1.Final</version>
</dependency>

<!-- Thymeleaf Togglz Dialect (optional) -->
<dependency>
  <groupId>com.github.heneke.thymeleaf</groupId>
  <artifactId>thymeleaf-extras-togglz</artifactId>
  <version>1.0.1.RELEASE</version>
</dependency>

Or when using Gradle:

compile("org.togglz:togglz-console:2.4.1.Final")
compile("org.togglz:togglz-spring-security:2.4.1.Final")
compile("com.github.heneke.thymeleaf:thymeleaf-extras-togglz:1.0.1.RELEASE")

Auto Configuration

The togglz-spring-boot-starter will automatically trigger the Togglz Spring Boot auto configuration. It will create all necessary beans and in particular the Togglz FeatureManager. You can @Autowired the FeatureManager into your application code, and then use it to check if a feature is enabled, e.g.

@Autowired
private FeatureManager manager;

@RequestMapping("/")
public ResponseEntity<?> index() {
    if (manager.isActive(HELLO_WORLD)) {
         ...
    }
}

The only thing that needs to be provided is configuration for the features you want to create. You can use Spring environment properties to create, enable and configure features. E.g. in application.properties:

togglz.features.FOO.enabled=true
togglz.features.BAR.enabled=false

or application.yml:

togglz:
  features:
    FOO
      enabled:true
    BAR:
      enabled: false

Features can also be grouped using togglz.features.{FEATURE}.groups, assigned an activation strategy by togglz.features.{FEATURE}.strategy, and the activation can be passed parameters using togglz.features.{FEATURE}.param.*.

Alternatively, or additionally, the togglz.feature-enums application property can be provided to create features from one or more enum classes. You can also provide features through an explicit FeaturesProvider e.g.:

public enum MyFeatures implements Feature {

    @EnabledByDefault
    @Label("First Feature")
    FEATURE_ONE,

    @Label("Second Feature")
    FEATURE_TWO;
}

@Bean
public FeatureProvider featureProvider() {
    return new EnumBasedFeatureProvider(MyFeatures.class);
}

By default the auto configuration will use a NoOpUserProvider and when Spring Security is used a SpringSecurityUserProvider.

If the togglz-console module is added then the TogglzConsoleServlet is registered using a ServletRegistrationBean.

Also any beans of type ActivationStrategy found in the application content will be added to the FeatureManager automatically.

If you define a UserProvider, StateRepository, ActivationStrategyProvider or even a FeatureManager manually the auto configuration will not create these beans and will use the ones already available in the application context.

The auto configuration supports providing feature state inside your application.properties/application.yml. See an example below of the application.yml. Note this is a Spring Boot in-memory implementation of a StateRepository which does not persist edited features. If persistence is needed a FileBasedStateRepository, JDBCStateRepository or any other applicable StateRepository must be added to the application context manually. When you want to use a FileBasedStateRepository you can also use this by providing a togglz.features-file application property. If the togglz.features-file is provided this will take precedence over features provided via application properties and effectively ignoring togglz.features. The togglz.features-file property is processed by getResource() so in most cases you should provide a file url for this property. To get a file in the local working directory you may use something like togglz.features-file = file:./togglz.properties.

Admin Console Security

By default the Togglz admin console is secured using the UserProvider bean. Which UserProvider bean the auto configuration configures depends on the availability of the Spring Security dependency. If Spring Security is on the classpath a SpringSecurityUserProvider is configured. In this case it will check if the user has the authority as provided by the togglz.console.feature-admin-authority application property. If Spring Security is not on the classpath a NoOpUserProvider is configured which provides a null user to the admin console servlet. This also means the admin console will not be accessible. For quick testing the togglz.console.secured application property can be set to false. This will bypass security completely for the admin console. Be careful in production with this setting as it will give everybody access to the admin console. Setting togglz.console.secured to false is also useful when you want to protect the admin console independently from the UserProvider.

Note that by default the Admin Console runs on the management port (if configured). If the management port (management.port) is not configured it will run on the application port. Setting togglz.console.use-management-port to false will always run the Admin Console on the application port.

Application Properties

The following properties can be specified inside your application.properties/application.yml file or as command line switches:

togglz:
  enabled: true # Enable Togglz for the application.
  feature-enums: # Comma-separated list of fully-qualified feature enum class names.
  feature-manager-name: # The name of the feature manager.
  features: # The feature states. Only needed if feature states are stored in application properties.
    HELLO_WORLD:
      enabled: true
    REVERSE_GREETING:
      enabled: true
      strategy: username
      param:
        users: user2, user3
  features-file: # The path to the features file that contains the feature states. Only needed if feature states are stored in external properties file.
  features-file-min-check-interval: # The minimum amount of time in milliseconds to wait between checks of the file's modification date.
  cache:
    enabled: false # Enable feature state caching.
    time-to-live: 0 # The time after which a cache entry will expire.
    time-unit: milliseconds # The time unit as java.util.concurrent.TimeUnit enum name (one of "nanoseconds", "microseconds", "milliseconds", "seconds", "minutes", "hours", "days").
  console:
    enabled: true # Enable admin console.
    path: /togglz-console # The path of the admin console when enabled.
    feature-admin-authority: ROLE_ADMIN # The name of the authority that is allowed to access the admin console.
    secured: true # Indicates if the admin console runs in secured mode. If false the application itself should take care of securing the admin console.
    use-management-port: true # Indicates if the admin console runs on the management port. If no management port is configured it will run on the application port. If set to true the console path will also be prefixed with the management.context-path.
  endpoint:
    id: togglz # The endpoint identifier.
    enabled: true # Enable actuator endpoint.
    sensitive: true # Indicates if the endpoint exposes sensitive information.