Configuration

This chapter will guide you through the Togglz configuration for web applications. As web applications are a very common environment for Togglz, the configuration has been designed to be very easy there.

If you want to use Togglz in a different environment or if you want to share the Togglz configuration between different application modules, have a look at the Advanced Configuration chapter.

The configuration of Togglz is done using pure Java code. So you won't have to edit any XML files or something like that.

Feature definition

Configuring Togglz requires you to implement two classes. The first class is the feature enum which declares the features you want to manage with Togglz. This enum is a standard Java enum which implements the Feature interface.

The following example shows a typical feature enum: 

import org.togglz.core.Feature;
import org.togglz.core.annotation.EnabledByDefault;
import org.togglz.core.annotation.Label;
import org.togglz.core.context.FeatureContext;

public enum MyFeatures implements Feature {

    @EnabledByDefault
    @Label("First Feature")
    FEATURE_ONE,
    
    @Label("Second Feature")
    FEATURE_TWO;
    
    public boolean isActive() {
        return FeatureContext.getFeatureManager().isActive(this);
    }
    
}

This example shows a feature enum declaring the features FEATURE_ONE and FEATURE_TWO. Both enum values have been enriched with some metadata using Java annotations. Togglz offers the following annotations for your feature declarations:

  • @Label: This annotation can be used to specify a human readable label for the feature. This label will for example be used in the Togglz Admin Console.
  • @EnabledByDefault: Typically a feature will be disabled per default if no other feature state has been persisted before. If you annotate a feature with this annotation, the feature will be enabled instead.
  • @DefaultActivationStrategy: When initializing the toggle, the default strategy to use for this toggle. It takes the ID of the strategy as an argument. It supports an optional array of child @ActivationParameter to define the key and value to use for activation of this property.

Besides the feature declaration a feature enum typically also declares a single public method called isActive(). This allows to check whether a feature is active or not simply by calling this method on the enum. You should typically add this method exactly as shown here to your feature enum.

Implementing TogglzConfig

The next step is to configure the FeatureManager which is the central Togglz component that manages the state of your features. To do so, you have to create a class implementing the TogglzConfig.

The following example shows a typical FeatureManager configuration: 

import java.io.File;

import org.togglz.core.Feature;
import org.togglz.core.manager.TogglzConfig;
import org.togglz.core.repository.StateRepository;
import org.togglz.core.repository.file.FileBasedStateRepository;
import org.togglz.core.user.FeatureUser;
import org.togglz.core.user.UserProvider;
import org.togglz.servlet.user.ServletUserProvider


public class MyTogglzConfiguration implements TogglzConfig {

    public Class<? extends Feature> getFeatureClass() {
        return MyFeatures.class;
    }

    public StateRepository getStateRepository() {
        return new FileBasedStateRepository(new File("/tmp/features.properties"));
    }

    public UserProvider getUserProvider() {
        return new ServletUserProvider();
    }

}

Implementing the TogglzConfig interface requires you to implement three methods. The following sections will describe each of the methods in detail.

getFeatureClass()

This method is the easiest to implement. It is used to tell Togglz about the feature enum class you want to use. You simply return the Class object of your feature enum here.

getStateRepository()

This method allows you to select the feature state repository you would like to use. The feature state repository is responsible to persist the current state of your features. It knows which features are enabled/disabled, the activation strategies selected for them and their parameters. Have a look at the Activation Strategies chapter to learn more about activation strategies.

Togglz ships with a number of default implementations. Please refer to State Repositories for details.

The example shows how to configure a feature state repository that reads the current feature state from an external file.

getUserProvider()

This method returns an implementation of the UserProvider interface which is responsible to tell the FeatureManager who is the current user. Knowing about the current user is essential for Togglz to implement access control for the admin console and for the activation strategy that allows to enable features only for specific users.

This example uses the ServletUserProvider as the feature user provider. This implementation uses the HttpServletRequest.getUserPrincipal() to obtain the current user. Other strategies for user authorization will be described in a later chapter.

Tell Togglz about your configuration class

After implementing the TogglzConfig interface you need to tell Togglz about your implementation class. How to do this highly depends on your environment and the integration modules you selected.

CDI

If you are using CDI and included the Togglz CDI integration module in your application, you won't have to do anything. Togglz will automatically search for implementations of TogglzConfig managed by the CDI container. As your implementation will typically have an empty default constructor, CDI will pick it up as a managed bean and Togglz will find it automatically.

Spring

Togglz offers a special integration module for Spring. This module will automatically search for implementations of the TogglzConfig in Spring's ApplicationContext. Therefore you just have to declare your implementation as a class managed by Spring. If you are using the Spring annotation support you can just add a @Component annotation to your class: 

@Component
public class MyTogglzConfiguration implements TogglzConfig {
  // code
}

Servlet Environments

If you don't use Spring or CDI, you will have to add a context parameter to your web.xml to tell Togglz about your TogglzConfig implementation. For the example in this chapter you would have to add this entry: 

<context-param>
  <param-name>org.togglz.core.manager.TogglzConfig</param-name>
  <param-value>com.example.myapp.MyTogglzConfiguration</param-value>
</context-param>