Android SDK reference

16 minute readReference

The following information is for the latest SDK version (6.x). The CloudBees platform requires that your installed SDK version be at least 6.x. Please install the latest SDK by following the instructions in the platform UI or in the SDK installation documentation.

Any updates to version 6.x are noted in the platform changelog.

Class Rox

package io.rollout.android;

class Rox
▼

The Rox class provides an interface for the CloudBees platform to manage feature flags that control the behavior of your application. This is the central repository for your application’s flags. This class handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values in the provided container are marked as feature flags and display in the UI once the application is run.

This class also allows you to manage custom properties. These can be static settings of type string, boolean, integer, or double, or you can use a generator class to provide a custom property that is dependent upon code state. These generated properties must derive from CustomPropertyGenerator, which is a template class.

You can also use a RoxOptions object to configure some aspects of this class. You can set the verbosity level, custom platform, global freeze level, impression handler, and fetch handler.

setup

static void setup(Application app)
static void setup(Application app, String appKey)
static void setup(Application app, RoxOptions options)
static void setup(Application application, String appKey, RoxOptions sdkOptions)
▼

Set up the SDK with the application key.

Configures the Rox object to work with the provided Android application. Using this method results in a default verbosity level of VERBOSE_LEVEL_SILENT. If provided, apply the provided RoxOptions object, which can be used to set an increased level of logging verbosity and a callback for the completion of each sync with the server.

Parameter Modifier and type

Description

app

Application

An Android application object representing the feature-controlled app to be managed.

options

A RoxOptions instance with the desired configuration for this application.

appKey

String

The application’s CloudBees platform SDK key.

register

Registers a feature flag container with the Rox client. The public member variables of this container become a flag in the UI and are named with the object name.

static void register(RoxContainer container)
static void register(String namespace, RoxContainer container)
▼
Parameter Modifier and type Description

namespace

String

The prefix namespace for all flags in this container. If no namespace is provided, the namespace defaults to an empty string.

container

Object

An object derived from RoxContainer that contains your application’s feature flags.

For example, assuming we have the following container:

package com.example.pacman;

public class MyContainer implements RoxContainer {
  public RoxString welcomeMessageText = new RoxString("Hello User");
  public RoxFlag enableLogin = new RoxFlag();
}
▼

and we register the container with the following code:

RoxContainer conf = new MyContainer();
Rox.register("Login", conf);
Rox.setup(this.getApplication());
▼

The flag in the UI has the names Login.welcomeMessageText and Login.enableLogin. This is useful for setting up groups of flags.

If you do not need a namespace, you can set the namespace to an empty string.

fetch

Creates a network request for the latest configuration.

static void fetch()
▼

setGlobalContext

Sets the global evaluation context. This context is merged with the local one when evaluating flag conditions. Values from local context have precedence over globally set values.

static void setGlobalContext(Context context)
▼

setUserspaceUnhandledErrorHandler

Sets the global handler for exceptions triggered by user-defined functions, such as configuration fetched handler, impression handler, dynamic property rule handler, or custom property generator.

static void setUserspaceUnhandledErrorHandler(UserSpaceExceptionHandler handler)
▼
void handleUserSpaceException(ExceptionTrigger source, Throwable exception);
▼
Exceptions triggered within the exception handler itself are logged, but not propagated.

unfreeze

static void unfreeze()
static void unfreeze(String namespace)
▼

Unfreezes all flags within the given namespace.

Table 1. Parameter information
Parameter Modifier and type Description

namespace

String

The flag namespace prefix. If no namespace is provided, the namespace defaults to an empty string.

getOverrides

static FlagOverrides getOverrides()
▼

Returns the current flag overrides.

setCustomComputedBooleanProperty

Sets a custom computed Boolean property on the Rox client. This is a computable Boolean with an object that generates the value for the property. The generator must be derived from the CustomPropertyGenerator template class in rox-java-core.

static void setCustomComputedBooleanProperty(String name, io.rollout.properties.CustomPropertyGenerator<Boolean> generator)
static void setCustomComputedBooleanProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Boolean> generator)
▼
Parameter Modifier and type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the Boolean property’s generator class.

setCustomComputedDoubleProperty

Sets a custom computed double property on the Rox client. This is a computable double, with an object that generates the value for the property. The generator must be derived from the CustomPropertyGenerator template class in rox-java-core.

static void setCustomComputedDoubleProperty(String name, io.rollout.properties.CustomPropertyGenerator<Double> generator)
static void setCustomComputedDoubleProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Double> generator)
▼
Table 2. Parameter information
Parameter Modifier and type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the double property’s generator class.

setCustomComputedIntegerProperty

Sets a custom computed integer property on the Rox client. This is a computable integer, with an object that generates the value for the property. The generator must be derived from the`CustomPropertyGenerator` template class in rox-java-core.

static void setCustomComputedIntegerProperty(String name, io.rollout.properties.CustomPropertyGenerator<Integer> generator)
static void setCustomComputedIntegerProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Integer> generator)
▼
Table 3. Parameter information
Parameter Modifier and type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the integer property’s generator class.

setCustomComputedSemverProperty

Sets a custom computed semantic-versioned string property on the Rox client. This is a computable semantically-versioned string, with an object that generates the value for the property. The generator must be derived from the CustomPropertyGenerator template class in rox-java-core.

static void setCustomComputedSemverProperty(String name, io.rollout.properties.CustomPropertyGenerator<String> generator)
static void setCustomComputedSemverProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<String> generator)
▼
Table 4. Parameter information
Parameter Modifier and type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the string property’s generator class.

setCustomComputedStringProperty

Sets a custom computed string property on the Rox client. This is a computable string, with an object that generates the value for the property. The generator must be derived from the CustomPropertyGenerator template class in rox-java-core.

static void setCustomComputedStringProperty(String name, io.rollout.properties.CustomPropertyGenerator<String> generator)
static void setCustomComputedStringProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<String> generator)
▼
Table 5. Parameter information
Parameter Modifier and type Description

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the string property’s generator class.

setCustomBooleanProperty

Sets a custom property representing a Boolean value.

static void setCustomBooleanProperty(String name, Boolean value)
▼
Parameter Modifier and type Description

name

String

The name of the custom property.

value

boolean

The value for the custom property, as a Boolean true or false.

setCustomDoubleProperty

Sets a custom property that can store a specified double value.

static void setCustomDoubleProperty(String name,double value)
▼
Parameter Modifier and type Description

name

String

The name of the property.

value

Double

The value of the property.

setCustomIntegerProperty

Sets a custom property that can store a specified integer value.

static void setCustomIntegerProperty(String name,int value)
▼
Parameter Modifier and type Description

name

String

The name of the property.

value

int

The value of the property.

setCustomSemverProperty

Sets a custom property that uses a Semantic Version as its value. For more information, refer to the Semantic Versioning documentation.

static void setCustomSemverProperty(String name,String value)
▼
Parameter Modifier and type Description

name

String

The name of the property to create.

value

String

The property value, formatted using the rules defined in the Semantic Versioning documentation.

setCustomStringProperty

Sets a custom string property for the Rox client.

static void setCustomStringProperty(String name,String value)
▼
Parameter Modifier and type Description

name

String

The name of the property to create.

value

String

The property’s value.

shutdown

void shutdown()
▼

This function unregisters all flags and custom properties that were registered before the call to shutdown.

dynamicAPI

Retrieves a dynamic API instance that can be used to get flag values (and create flags) from flag names.

static DynamicAPI dynamicAPI()
▼

Interface DynamicAPI

DynamicAPI is a facade for a dynamic API that enables creating and getting flag values by their name. The instance is retrieved by calling dynamicAPI function on Rox.

In this example, DynamicAPI is used to get the flag value by passing in context and defaultValue.

package io.rollout.client;

interface DynamicAPI
▼
Context context = new RoxContext.Builder().from(
  ImmutableMap.of("someKey", "someValue")
);
DynamicAPI dynamic = Rox.dynamicAPI();
boolean flagAEnabled = dynamic.isEnabled("flagA", context, false);
▼

isEnabled (Dynamic API)

Returns true if the flagName is enabled for context, else returns defaultValue.

boolean isEnabled(String flagName, Boolean defaultValue)
boolean isEnabled(String flagName, Context context, Boolean defaultValue)
▼
Parameter Modifier and type Description

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

boolean

If a value is not set for this flag, returns the default value.

value (Dynamic API)

Returns a string flag value for the flag flagName.

String value(String name, String defaultValue)
String value(String name, String defaultValue, Context context)
String value(String name, String defaultValue, String[] variations)
String value(String name, String defaultValue, String[] variations, Context context)
▼
Parameter Modifier and type Description

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

String

If value is not set for this flag, return the default value.

variations

String[]

Flag values that are available for selection in the UI once the flag is created.

getInt (Dynamic API)

Returns an integer flag value for the flag flagName.

int getInt(String name, int defaultValue)
int getInt(String name, int defaultValue, Context context)
int getInt(String name, int defaultValue, int[] variations)
int getInt(String name, int defaultValue, int[] variations, Context context)
▼
Parameter Modifier and type Description

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

int

If experiment is not set for this flag, return the default value.

variations

int[]

Flag values that are available for selection in the UI once the flag is created.

getDouble (Dynamic API)

Returns a double flag value for the flag flagName.

double getDouble(String name, double defaultValue)
double getDouble(String name, double defaultValue, Context context)
double getDouble(String name, double defaultValue, double[] variations)
double getDouble(String name, double defaultValue, double[] variations, Context context)
▼
Parameter Modifier and type Description

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

double

If a value is not set for this flag, return the default value.

variations

double[]

Flag values that are available for selection in the UI once the flag is created.

Class RoxOptions

package io.rollout.client;

class RoxOptions
▼

RoxOptions covers configuration options for the Rox client, including settings such as the verbosity of the logging. Instances of this class should be created using RoxOptions.Builder.

An example of setting up a new RoxOptions object follows. It sets a debugging verbosity level and provides options such as an impression handler and a fetch handler.

 RoxOptions options = new RoxOptions.Builder()
    .withVerboseLevel(RoxOptions.VerboseLevel.VERBOSE_LEVEL_DEBUG)
    .withPlatform("FireTv")
    .withLogger(logger)
    .withConfigurationFetchedHandler(fetchHandler)
    .withImpressionHandler(impressionHandler)
    .withDynamicPropertyRule(dynamicPropertyRule)
    .withFreeze(Freeze.UntilLaunch)
    .withHosting("eu")
    .withProxy(new ProxyConfig("http://proxy.example.com", "sdkuser", "sdkpassword"))
    .build();
Rox.setup(this, options);
▼

Class RoxOptions.Builder

This Builder class is used to create a new RoxOptions instance.

package io.rollout.rox.server;

static class RoxOptions.Builder
▼

build

Builds the RoxOptions object, with the configured options. Returns a RoxOptions object containing the specified option values.

RoxOptions build()
▼

withVerboseLevel

Configures the RoxOptions Builder object with the specified VerboseLevel set. Returns the builder instance.

RoxOptions.Builder withVerboseLevel(RoxOptions.VerboseLevel verboseLevel)
▼
Parameter Modifier and type Description

verboseLevel

RoxOptions.VerboseLevel

The verbosity level.

withConfigurationFetchedHandler

Configures the RoxOptions.Builder object with the specified Functor that is called every time the configuration is applied on the client. The configuration can be retrieved from the cache, embedded flags, or the network. Returns the builder instance.

RoxOptions.Builder withConfigurationFetchedHandler(ConfigurationFetchedHandler configurationFetchedHandler)
▼
Parameter Modifier and type Description

configurationFetchedHandler

ConfigurationFetchedHandler

A Functor instance to be evaluated when the configuration is fetched.

withLogger

RoxOptions.Builder withLogger(Logger logger)
▼

Configures the RoxOptions Builder object with a custom Logger, and overrides the default logger logcat. Returns the builder instance.

Parameter Modifier and type Description

logger

Logger

A custom logger instance.

withFreeze

RoxOptions.Builder withFreeze(Freeze freeze)
▼

Configures the RoxOptions Builder object with the default freeze behavior. Returns the builder instance.

Parameter Modifier and type Description

freeze

Freeze

the default flag freeze level to set unless it was overridden on the flag constructor.

withImpressionHandler

RoxOptions.Builder withImpressionHandler(ImpressionHandler impressionHandler)
▼

Configures the RoxOptions.Builder object with the specified Functor that is called every time a flag value gets computed and evaluated on the client. Returns the builder instance.

Parameter Modifier and type Description

impressionHandler

ImpressionHandler

a Functor instance to be evaluated when the flag is evaluated.

withPlatform

RoxOptions.Builder withPlatform(String platform)
▼

Configures the RoxOptions Builder object with a custom platform. Any String is applicable here. A custom platform allows for easier separation of values to be sent to the client (such as Android Tv, Android Tablet, Tizen). Returns the builder instance.

Parameter Modifier and type Description

platform

String

A custom platform, such as Android Tv, Android Tablet, or Tizen.

withDynamicPropertyRule

Configures the RoxOptions Builder object with a function called every time a condition with property is evaluated, and not previously configured with any of the setCustomProperty functions. Returns the builder instance.

RoxOptions.Builder withDynamicPropertyRule(DynamicPropertyRule dynamicPropertyRule)
▼
Parameter Modifier and type Description

dynamicPropertyRule

DynamicPropertyRule

A function instance to be invoked when a condition with an unknown property is being evaluated.

withHosting

Configures the RoxOptions Builder object with a geographic region of your choice. Returns the builder instance.

RoxOptions.Builder withHosting(String region)
▼
Parameter Modifier and type Description

region

String

The region to use.

Interface RoxContainer

The RoxContainer is an abstract class describing a feature flag container for a CloudBees platform-enabled application. The RoxContainer child class for your application contains all the feature flags for the features in your application. These feature flags are converted into CloudBees feature flags when the container is registered with Rox using Rox.register(). Feature flag names are derived from the provided flag variable names.

package io.rollout.configuration;

interface RoxContainer
▼

The following is an example of how to use this container class:

// File MyContainer.java
class MyContainer implements RoxContainer {
 // For a feature flag named "welcomeMessageText"
 public RoxString welcomeMessageText = new RoxString("DefaultValue");
}

// Include this code as early as possible in your program's initialization code
RoxContainer conf = new MyContainer();
// Registers the container with CloudBees, creating relevant flags in the platform
Rox.register(conf);
// Performs the final setup of the Rox application.
Rox.setup(this.getApplication());
▼

Class RoxEnumFlag

package io.rollout.flags;

class RoxEnumFlag<T extends Enum<T>> implements ClientFlag

public RoxEnumFlag(T defaultValue)
public RoxEnumFlag(T defaultValue, Freeze freeze)
▼

Type parameters

T - the enumeration to use as the basis for this feature flag.

RoxEnumFlag allows you to define feature flags with multiple options, as opposed to standard RoxFlag objects which can only represent a Boolean value. These values are provided in an enumerable way, which allows you to easily use the RoxEnumFlag object in switch statements and other control-flow mechanisms. The platform UI also displays these enumerable values, providing a user-friendly way to debug your application’s settings. Provide the enumerable object as the template parameter, and the default value as the constructor parameter.

Use as in the following example:

// Define a color enumeration
enum Colors {
  Red, Blue, Green
}
// Create a color feature flag with a default value of Blue
public RoxEnumFlag<Colors> colorFeature = new RoxEnumFlag<>(Colors.Blue);
▼

getName

Returns the name of the feature flag.

String getName()
▼

getRawFlag

Returns a RoxString object representing the current flag value.

RoxString getRawFlag()
▼

getValue

Returns the current value of this flag. If the value of the flag has been overwritten with a valid value, then the overwritten value is returned. Otherwise, the flag’s default value is returned.

T getValue()
▼
A valid value is defined as a value that is a valid member of the enumeration type this flag is based on.

unfreeze

Unlocks the flag value changes from the last time it was frozen.

void unfreeze(Freeze freeze);
▼

peekCurrentValue

Retrieves the current flag value without a freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekCurrentValue()
▼

peekOriginalValue

Retrieves the original value with no overrides, no freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekOriginalValue()
▼

Class RoxFlag

package io.rollout.flags;

class RoxFlag implements BooleanFeatureFlag, ClientFlag

public RoxFlag()
public RoxFlag(boolean defaultValue)
public RoxFlag(boolean defaultValue, Freeze freeze)
▼

RoxFlag is a Boolean feature flag. It can be either true or false.

Working with enabled() and disabled()

The .enabled() and .disabled() methods can be used to define behaviors for each of the possible states of a RoxFlag. For example, you can use the following code to create a RoxFlag with a disabled handler for showing onboarding flows.

roxContainer.myFlag.disabled(() -> {
    // run this code if the feature is disabled
});
▼

The above code defines Java lambda with an anonymous flaggable object with a single method - execute - that runs when the flag is false. This returns the instance of the flag, allowing you to chain the calls together:

roxContainer.myFlag.enabled(() -> {
    // run this code if the feature is enabled
}).disabled(() -> {
    // run this code if the feature is disabled
});
▼

enabled

Executes the provided action if the flag is enabled (the flag value is true), but otherwise does nothing. Actions using this mechanism must be derived from the flaggable interface.

enabledAction is a flaggable action to execute if the RoxFlag for the feature is enabled.

Returns the relevant instance of RoxFlag (this), allowing for chaining of handlers.

RoxFlag enabled(io.rollout.flags.Flaggable enabledAction)
RoxFlag enabled(io.rollout.flags.Flaggable enabledAction, Context context)
▼

disabled

Executes the provided action if the flag is disabled, but otherwise does nothing. Actions using this mechanism must be derived from the flaggable interface.

disabledAction is a flaggable action to execute if the RoxFlag for the feature is disabled.

Returns the relevant instance of RoxFlag (this), allowing for chaining of handlers.

RoxFlag disabled(io.rollout.flags.Flaggable disabledAction)
RoxFlag disabled(io.rollout.flags.Flaggable disabledAction, Context context)
▼

isEnabled

Returns true if the flag is enabled for context, otherwise it returns the default Boolean value.

boolean isEnabled()
boolean isEnabled(Context context)
▼

getName

Returns the string name of this RoxFlag.

String getName()
▼

unfreeze

Unlocks the flag value changes from the last time it was frozen.

void unfreeze(Freeze freeze);
▼

peekCurrentValue

Retrieves the current flag value without a freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekCurrentValue()
▼

peekOriginalValue

Retrieves the original value with no overrides, no freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekOriginalValue()
▼

Class RoxString

package io.rollout.flags;

class RoxString implements StringFeatureFlag, ClientFlag

public RoxString(String defaultValue)
public RoxString(String defaultValue, Freeze freeze)
public RoxString(String defaultValue, String[] options)
public RoxString(String defaultValue, String[] options, Freeze freeze)
▼

RoxString is a feature flag object that accepts a list of possible string values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI. RoxEnumFlag provides a similar function, except with string enumerations.

Use as in the following example:

String[] titleColorsOptions = new String[] {"Black", "Blue", "Green"};
RoxString titleColorsVariant = new RoxString("Black", titleColorsOptions);
if (titleColorsVariant.getValue().equals("Black")) {
    // set title color to black
} else if (titleColorsVariant.getValue().equals("Green")) {
    // set title color to green
}
▼

getName

String getName()
▼

Returns the feature flag’s name.

getValue

String getValue()
String getValue(Context context)
▼

Returns the current value of the feature flag as a String.

unfreeze

Unlocks the flag value changes from the last time it was frozen.

void unfreeze(Freeze freeze);
▼

peekCurrentValue

Retrieves the current flag value without a freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekCurrentValue()
▼

peekOriginalValue

Retrieves the original value with no overrides, no freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekOriginalValue()
▼

Class RoxInt

package io.rollout.flags;

class RoxInt implements IntFeatureFlag, ClientFlag

public RoxInt(int defaultValue)
public RoxInt(int defaultValue, Freeze freeze)
public RoxInt(int defaultValue, int[] variations)
public RoxInt(int defaultValue, int[] variations, Freeze freeze)
▼

RoxInt is a feature flag object that accepts a list of possible integer values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

Use as in the following example:

RoxInt ageVariant = new RoxInt(25, new int[]{ 20, 25, 30, 35, 40, 45, 55, 65 });
if (ageVariant.getValue() == 25) {
    // action...
}
▼

getName

String getName()
▼

Returns the feature flag’s name.

getValue

int getValue()
int getValue(Context context)
▼

Returns the current value of the feature flag as an integer.

unfreeze

Unlocks the flag value changes from the last time it was frozen.

void unfreeze(Freeze freeze);
▼

peekCurrentValue

Retrieves the current flag value without a freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekCurrentValue()
▼

peekOriginalValue

Retrieves the original value with no overrides, no freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekOriginalValue()
▼

Class RoxDouble

package io.rollout.flags;

class RoxDouble implements DoubleFeatureFlag, ClientFlag

public RoxDouble(double defaultValue)
public RoxDouble(double defaultValue, Freeze freeze)
public RoxDouble(double defaultValue, double[] variations)
public RoxDouble(double defaultValue, double[] variations, Freeze freeze)
▼

RoxDouble is a feature flag object that accepts a list of possible double values, and a default value. These values are used to select new values for the feature, and they can be overridden via the UI.

Use as in the following example:

RoxDouble doubleVariant = new RoxDouble(1.1, new int[]{ 1.1, 2.2, 3.3 });
if (Double.compare(doubleVariant.getValue(), 2.0) >= 0) {
    // action...
}
▼

getName

String getName()
▼

Returns the name of the feature flag.

getValue

double getValue()
double getValue(Context context)
▼

Returns the current value of the feature flag as a double.

unfreeze

Unlocks the flag value changes from the last time it was frozen.

void unfreeze(Freeze freeze);
▼

peekCurrentValue

Retrieves the current flag value without a freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekCurrentValue()
▼

peekOriginalValue

Retrieves the original value with no overrides, no freeze, and without invoking an impression. Intended to be used for development only — avoid using in a production environment.

String peekOriginalValue()
▼

Class FlagOverrides

Use Class FlagOverrides to override a flag value locally. Do not use this class in production builds.

When you override an existing flag value using the setOverride method, the SDK disregards any existing configuration coming from the UI and serializes the override on disk. This value is loaded and overrides the flag right after Rox.setup is called. To clear the override from the cache, call the clearOverrides method.

hasOverride

boolean hasOverride(String flagName)
▼

Returns true if a flag has an override.

Parameter Modifier and type Description

flagName

String

Full flag name including namespace, for example, default.flagName.

setOverride

void setOverride(String flagName, String value)
▼

Sets an override value on a specific flag. This function accepts two parameters: flag name (full flag name including namespace), and desired value (from type String).

This function also saves the override value on the local device disk, so the value can be recalled for the next time the SDK is loaded to production.

Parameter Modifier and type Description

flagName

String

Full flag name including namespace, for example, default.flagName.

value

String

The value of a flag. If this is a Boolean flag, the value must be "true" or "false".

getOverride

String getOverride(String flagName)
▼

Retrieves the overridden value for the flag, if it exists. Otherwise, returns null.

Parameter Modifier and type Description

flagName

String

Full flag name including namespace, e.g., default.flagName.

clearOverride

void clearOverride(String flagName)
▼

Clears the override value from the flag and storage.

Parameter Modifier and type Description

flagName

String

Full flag name including namespace, for example, default.flagName.

clearOverrides

void clearOverrides()
▼

Clears all override values and empties the override storage.

interface Context

The context interface is used to pass data to the flag when checking if the current flag is enabled or disabled. This object is used by the registered custom properties to evaluate the experiment expression and return the flag value.

package io.rollout.context;

interface Context
▼

Use the Builder to create a context, and send a Map in the following format:

Context from(Map<String, Object> map)
▼

Use as in the following example:

Context context = new RoxContext.Builder().from(
  ImmutableMap.of("someKey", "someValue")
);
▼

get

This get function is used to retrieve data from the context.

Object get(String key)
▼

Interface ConfigurationFetchedHandler

Use as follows:

package io.rollout.client;

interface ConfigurationFetchedHandler
▼
void onConfigurationFetched(FetcherResults results)
▼

where FetcherResults contains the following information:

Method Description

FetcherStatus getFetcherStatus()

Fetch status; is one of the following:

  • AppliedFromEmbedded: Embedded configuration applied.

  • AppliedFromLocalStorage: Cached configuration applied.

  • AppliedFromNetwork: Remote configuration applied.

  • ErrorFetchedFailed: Failure to apply remote configuration.

boolean hasChanges()

Whether the configuration has changes compared to the previous fetch result.

Date getCreationDate()

Configuration date.

FetcherError getErrorDetails()

If status is ErrorFetchedFailed, this method returns error details. Otherwise, it returns null.

Interface ImpressionHandler

Use as follows:

package io.rollout.client;

interface ImpressionHandler
▼
void onImpression(io.rollout.flags.ImpressionEvent)
▼

where ImpressionEvent provides the flag name, value, and other impression information:

Method Description

String getName()

Impression’s flag name.

String getValue()

Impression value.

boolean isTargeting()

Indicates whether the flag is active.

Context getContext()

The context in which the impression is called. This is a merged context, containing both the global context and the call’s context.

DynamicPropertyRule

The functional interface is as follows:

package io.rollout.properties;

interface DynamicPropertyRule
▼

It contains the following method:

Object invoke(String propName, Context context)
▼

This method is invoked whenever a condition with an unknown property is evaluated.

Parameter Modifier and type Description

propName

String

Property name being evaluated.

context

Context

Context used for evaluation. Can be null.

Returns the property evaluation result.

Use as in the following example:

DynamicPropertyRule rule = new DynamicPropertyRule() {
  @Override
  public Object invoke(String propName, Context context) {
    return ((Map<String, String>) context.get("user")).get(propName);
  }
};
▼

Default dynamic property rule

By default, a dynamic property rule is used that retrieves the property value from the evaluation context:

DynamicPropertyRule DEFAULT = new DynamicPropertyRule() {
  @Override
  public Object invoke(String propName, Context context) {
    return context != null ? context.get(propName) : null;
  }
};
▼
C Client