Spring Boot Starter since 2.3.0
Getting Started
For Spring Boot 2.x support, add the Togglz Spring Boot Starter dependency to your project:
<dependency> <groupId>org.togglz</groupId> <artifactId>togglz-spring-boot-starter</artifactId> <version>3.1.2</version> </dependency>
Or when using Gradle you can simply add to your build.gradle file:
implementation("org.togglz:togglz-spring-boot-starter:3.1.2")
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 configuration.
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>3.1.2</version> </dependency> <!-- Togglz Spring Security (optional) --> <dependency> <groupId>org.togglz</groupId> <artifactId>togglz-spring-security</artifactId> <version>3.1.2</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:
implementation("org.togglz:togglz-console:3.1.2")
implementation("org.togglz:togglz-spring-security:3.1.2")
implementation("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 inject the FeatureManager into your application code (using constructor injection), and then use it to check if a feature is enabled, e.g.
@Controller
public class MyClass {
private FeatureManager manager;
public static final Feature HELLO_WORLD = new NamedFeature("HELLO_WORLD");
public MyClass(FeatureManager manager) {
this.manager = manager;
}
@RequestMapping("/")
public ResponseEntity<?> index() {
if (manager.isActive(HELLO_WORLD)) {
...
}
}
}
(Note, that since Spring Framework 4.3, implicit constructor injection is possible, so you don't need to annotate your constructor explicitly with @Autowired.)
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 context 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.
The Actuator Endpoint
By default the togglz-spring-boot starter exposes the togglz endpoint as an actuator one.
This allows you to get an overview of all available toggles and also enable and disable features as in the console.
By default the endpoint is available via: curl -GET http://localhost:8080/actuator/togglz or even via copy pasting this url in your browser.
The response will be similar to this example: {"name":"HELLO_WORLD","enabled":true,"strategy":null,"params":{}},{"name":"REVERSE_GREETING","enabled":false,"strategy":null,"params":{}}
The names of your features will probably be different, but the reponse will be similar. If you want to enable or disable a specific feature toggle
you can also use curl (this time with HTTP POST instead of GET) to change the state like this:
curl -d '{"name":"REVERSE_GREETING", "enabled":"true"}' -H "Content-Type: application/json" -POST http://localhost:8080/actuator/togglz/GREETING.
This request changes the status of the REVERSE_GREETING toggle from false to true which will disable the code inside of this feature.
In case you want a user interface you can add the togglz-console dependency instead of using the actuator endpoint.
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: # Only for Spring Boot 1.x (for Spring Boot 2.x see https://docs.spring.io/spring-boot/docs/current/reference/html/production-ready-endpoints.html)
id: togglz # The endpoint identifier.
enabled: true # Enable actuator endpoint.
sensitive: true # Indicates if the endpoint exposes sensitive information.