Feature Flags and Switches

Overview

This module provides an API to check flags and switches from Java code.

Feature flags and switches are used to control application behavior. They are extensive described in the Configuration Documentation.

Feature Flags

Feature flags are declared in C++ as a base::Feature. How to declare them is covered in Adding a new feature flag.

To check the flag state in native code, call FeatureList::IsEnabled(kMyFeature)).

To check the flag state in Java code, first export them to Java:

1. Put a pointer to the base::Feature into kFeaturesExposedToJava in chrome_feature_list.cc
2. Create a String constant in ChromeFeatureList.java with the the flag name (passed as parameter to the base::Feature constructor) as value.

Then, from the Java code, check the value of the flag by calling ChromeFeatureList.isEnabled(ChromeFeatureList.MY_FEATURE).

Note that this call requires native to be initialized. If native might not be initialized when the check is run, there are two ways of proceeding:

1. Declare a CachedFlag in ChromeFeatureList, which returns a value cached from the previous run, and add it to ChromeFeatureList.sFlagsCachedFullBrowser. Refer to the inline documentation of CachedFlag for more details and caveats with this approach.
2. Declare a MutableFlagWithSafeDefault in ChromeFeatureList, which returns a default value when native is not loaded.

Switches

A switch is just a string, unlike feature flags, which are a base::Feature objects. Switches are declared separately in native and in Java, though both base::CommandLine in native are CommandLine in Java return the same state.

To create a switch in Native, declare it as a const char kMySwitch = "my-switch" and call base::CommandLine::ForCurrentProcess()->HasSwitch(kMySwitch).

To create a switch in Java, add it to ChromeSwitches.java.tmpl. It will automatically be surfaced in the generated ChromeSwitches.java. Then, check it with CommandLine.getInstance().hasSwitch(ChromeSwitches.MY_SWITCH).

For switches used in both native and Java, simply declare them twice, separately, as per instructions above, with the same string.

Variations

Though feature flags are boolean, enabled feature flags can have multiple variations of the same feature. The code generates these variations by getting parameters from the field trial API.

In native, the field trial API can be accessed by the functions in field_trial_params.h, passing the base::feature. For example, GetFieldTrialParamByFeatureAsInt(kMyFeature, "MyParameter", 0) will return the value that should be used for the parameter "MyParameter" of kMyFeature. If not available the default value 0 is returned.

In Java, ChromeFeatureList offers the same API with ChromeFeatureList.getFieldTrialParamByFeatureAsInt(ChromeFeatureList.MY_FEATURE, "MyParameter", 0). As with isEnabled(), this call requires native to be started. If that is not guaranteed, options analogous to feature flags are available:

1. Declare an IntCachedFeatureParam in ChromeFeatureList, which returns a value cached from the previous run, and add it to ChromeFeatureList.sParamsCached.
2. Declare a MutableIntParamWithSafeDefault in ChromeFeatureList, which returns a default value when native is not loaded.

Int used as an example, but parameters can also be of the types String, Double and Boolean.