Java API

Reference

Class Rox

package io.rollout.rox.server;

class Rox

The Rox class provides your application its primary interface with feature flags in the {PRODUCT} system. This is the central repository for your application’s flags, it handles communications with the server to obtain the latest values. It provides a mechanism through which you can use the feature flags to control your application’s behavior. It works with a RoxContainer-derived object, which holds your application’s feature flags. The values contained in the provided RoxContainer will be marked as feature flags and will appear in your application’s {PRODUCT} dashboard 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 Future<CoreState> setup(String rolloutKey)
static Future<CoreState> setup(String rolloutKey, RoxOptions options)

Setup the SDK with the rollout key.

ParameterModifier and TypeDescription

rolloutKey

String

The application’s {PRODUCT} key.

options

RoxOptions

A RoxOptions instance with the desired configuration for this application.

Returns Future<CoreState> that completes when the SDK has retrieved data from {PRODUCT} servers.

If setup was successful, the returned future will return CoreState.Set.If the returned state is CoreState.Corrupted then it’s recommended to analyze logging output to identify the reason of the failure.

Note: further Rox.setup calls, after Rox was set, will be ignored, unless the last setup failed, or Rox.shutdown has been invoked.

register

static void register(RoxContainer container)
static void register(String namespace, RoxContainer container)

Registers a feature flag container with the Rox client. The public member variables of this container will become flags in your dashboard and will be named with the object name.

ParameterModifier and TypeDescription

namespace

String

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

container

RoxContainer

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(rolloutKey);

The flag in the dashboard will have the names Login.welcomeMessageText and Login.enableLogin.This is very handy if you want to have groups of flags.

fetch

static void fetch()

Creates a network request for the latest configuration.

setGlobalContext

static void setGlobalContext(Context context)

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

setUserspaceUnhandledErrorHandler

static void setUserspaceUnhandledErrorHandler(UserSpaceExceptionHandler handler)

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

void handleUserSpaceException(ExceptionTrigger source, Throwable exception);

Note: exceptions triggered within the exception handler itself aren’t propagated, but just logged.

setCustomComputedBooleanProperty

static void setCustomComputedBooleanProperty(String name, io.rollout.properties.CustomPropertyGenerator<Boolean> generator)
static void setCustomComputedBooleanProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Boolean> generator)

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

ParameterModifier and TypeDescription

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the boolean property’s generator class.

setCustomComputedDoubleProperty

static void setCustomComputedDoubleProperty(String name, io.rollout.properties.CustomPropertyGenerator<Double> generator)
static void setCustomComputedDoubleProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Double> generator)

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 should be derived from the`CustomPropertyGenerator` template class in rox-java-core.

ParameterModifier and TypeDescription

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the double property’s generator class.

setCustomComputedIntegerProperty

static void setCustomComputedIntegerProperty(String name, io.rollout.properties.CustomPropertyGenerator<Integer> generator)
static void setCustomComputedIntegerProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<Integer> generator)

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 should be derived from the`CustomPropertyGenerator` template class in rox-java-core.

ParameterModifier and TypeDescription

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the integer property’s generator class.

setCustomComputedSemverProperty

static void setCustomComputedSemverProperty(String name, io.rollout.properties.CustomPropertyGenerator<String> generator)
static void setCustomComputedSemverProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<String> generator)

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 should be derived from the CustomPropertyGenerator template class in`rox-java-core`.

ParameterModifier and TypeDescription

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the string property’s generator class.

setCustomComputedStringProperty

static void setCustomComputedStringProperty(String name, io.rollout.properties.CustomPropertyGenerator<String> generator)
static void setCustomComputedStringProperty(String name, io.rollout.properties.CustomPropertyGeneratorWithContext<String> generator)

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 should be derived from the`CustomPropertyGenerator` template class in rox-java-core.

ParameterModifier and TypeDescription

name

String

The name of the property to create.

generator

CustomPropertyGenerator

An instance of the string property’s generator class.

setCustomBooleanProperty

static void setCustomBooleanProperty(String name, boolean value)

Sets a custom property representing a boolean value.

ParameterModifier and TypeDescription

name

String

The name of the custom property.

value

boolean

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

setCustomDoubleProperty

static void setCustomDoubleProperty(String name,double value)

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

ParameterModifier and TypeDescription

name

String

The name of the property.

value

double

The value of the property.

setCustomIntegerProperty

static void setCustomIntegerProperty(String name,int value)

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

ParameterModifier and TypeDescription

name

String

The name of the property.

value

int

The value of the property.

setCustomSemverProperty

static void setCustomSemverProperty(String name,String value)

Sets a custom property that uses a Semantic Version as its value. See https://semver.org/ for more information on Semantic Versioning.

ParameterModifier and TypeDescription

name

String

The name of the property to create.

value

String

The property value, formatted using the rules defined at semver.org.

setCustomStringProperty

static void setCustomStringProperty(String name,String value)

Sets a custom string property for the Rox client.

ParameterModifier and TypeDescription

name

String

The name of the property to create.

value

String

The property’s value.

shutdown

static void shutdown()

This function unregisters all flags and custom properties that were registered before it and resets ROX state to CoreState.Initial.

dynamicAPI

static DynamicAPI dynamicAPI()

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

Interface DynamicAPI

package io.rollout.client;

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.

Example

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

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

isEnabled (dynamic api)

boolean isEnabled(String flagName, boolean defaultValue)
boolean isEnabled(String flagName, Context context, boolean defaultValue)

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

ParameterModifier and TypeDescription

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

boolean

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

value (dynamic api)

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)

Returns string flag value for the flag flagName.

ParameterModifier and TypeDescription

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

String

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

variations

String[]

Flag values that will be available for selection in the dashboard once the flag is created.

getInt (dynamic api)

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)

Returns integer flag value for the flag flagName.

ParameterModifier and TypeDescription

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 will be available for selection in the dashboard once the flag is created.

getDouble (dynamic api)

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)

Returns double flag value for the flag flagName.

ParameterModifier and TypeDescription

flagName

String

Flag name to evaluate.

context

Context

The context to be used when evaluating the flag.

defaultValue

double

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

variations

double[]

Flag values that will be available for selection in the dashboard once the flag is created.

Class RoxOptions

package io.rollout.rox.server;

class RoxOptions

RoxOptions covers configuration options for the Rox client. This includes settings like a configuration fetched handler and the verbosity of the logging. Instances of this class should be created using RoxOptions.Builder.

Example

Here is an example of setting up a new RoxOptions object. This options object sets the verbosity level to "Debug", providing an impression handler, fetch handler, and more.

 RoxOptions options = new RoxOptions.Builder()
    .withFetchIntervalInSeconds(50)
    .withVerboseLevel(RoxOptions.VerboseLevel.VERBOSE_LEVEL_DEBUG)
  .withVersion(appVersion)
    .withLogger(logger)
    .withConfigurationFetchedHandler(fetchHandler)
    .withImpressionHandler(impressionHandler)
    .withDynamicPropertyRule(dynamicPropertyRule)
    .build();
Rox.setup(this, options);

Class RoxOptions.Builder

package io.rollout.rox.server;

static class RoxOptions.Builder

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

build

RoxOptions build()

Builds the RoxOptions object, with the configured options.

Returns

A RoxOptions object containing the specified option values.

withVerboseLevel

RoxOptions.Builder withVerboseLevel(RoxOptions.VerboseLevel verboseLevel)

Configures the RoxOptions Builder object with the specified VerboseLevel set.

ParameterModifier and TypeDescription

verboseLevel

RoxOptions.VerboseLevel

the verbosity level.

Returns

The builder instance.

withConfigurationFetchedHandler

RoxOptions.Builder withConfigurationFetchedHandler(ConfigurationFetchedHandler configurationFetchedHandler)

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 cache, embedded experiments or Network.

ParameterModifier and TypeDescription

configurationFetchedHandler

ConfigurationFetchedHandler

a Functor instance to be evaluated when configuration is fetched.

Returns

The builder instance.

withLogger

RoxOptions.Builder withLogger(Logger logger)

Configures the RoxOptions.Builder object with a custom Logger, overrides the default SLF4J logger.

ParameterModifier and TypeDescription

logger

Logger

a custom logger instance.

Returns

The builder instance.

withVersion

RoxOptions.Builder withVersion(String version)

Configures the RoxOptions.Builder object with the app version. This version can be used in the {PRODUCT} dashboard for targeting.

ParameterModifier and TypeDescription

version

String

the app version.

Returns

The builder instance.

withImpressionHandler

RoxOptions.Builder withImpressionHandler(ImpressionHandler impressionHandler)

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

ParameterModifier and TypeDescription

impressionHandler

ImpressionHandler

a Functor instance to be evaluated when flag is evaluated.

Returns

The builder instance.

withFetchIntervalInSeconds

RoxOptions.Builder withFetchIntervalInSeconds(long intervalInSeconds)

Configures the RoxOptions Builder object with the specified number of seconds indicating the intervals between fetch configuration requests.

ParameterModifier and TypeDescription

intervalInSeconds

long

seconds between fetch requests default: 60 minimum: 30.

Returns

The builder instance.

withDynamicPropertyRule

RoxOptions.Builder withDynamicPropertyRule(DynamicPropertyRule dynamicPropertyRule)

Configures the RoxOptions Builder object with the function that is called every time a condition with property is evaluated and was not configured with any of the setCustomProperty functions

dynamicPropertyRule

DynamicPropertyRule

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

Returns

The builder instance.

withCustomStorageImplementation

RoxOptions.Builder withCustomStorageImplementation(io.rollout.io.StorageEntryFactory storageEntryFactory)

Allows to provide the custom storage implementation used for caching etc.

Returns

The builder instance.

Interface RoxContainer

package io.rollout.configuration;

interface RoxContainer

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

Example

Below is a quick example of how to use this container class:

// File MyContainer.java
   public class MyContainer implements RoxContainer {
     // This will become 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 {PRODUCT}, creating relevant flags in {PRODUCT}'s system
   Rox.register(conf);
   // Performs final setup of the Rox application.
   Rox.setup(rolloutKey);

Class RoxEnumFlag

package io.rollout.flags;

class RoxEnumFlag<T extends Enum<T>>

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 Rox Dashboard will also display 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.

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

String getName()

Gets the name of this feature flag.

Returns

The feature flag’s name.

getRawFlag

RoxString getRawFlag()

Returns the current RoxString object that represents the flag’s value.

Returns

A RoxString object representing the current flag value.

getValue

T 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. Note: a valid value is defined as a value that is a valid member of the enumeration type this flag is based on.

Returns

The current value of this flag.

Class RoxFlag

package io.rollout.flags;

class RoxFlag implements BooleanFeatureFlag

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 for chaining the calls together:

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

enabled

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

Executes the provided action if the flag is enabled (i.e. the flag value is true), and otherwise does nothing. Actions using this mechanism need to be derived from the flaggable interface.

enabledAction - 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

disabled

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

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

disabledAction - 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.

isEnabled

boolean isEnabled()
boolean isEnabled(Context context)

Returns true if the flag is enabled for context, else return defaultValue.

Returns

boolean

getName

String getName()

Returns the name of this flag.

Returns

String name of this RoxFlag.

Class RoxString

package io.rollout.flags;

class RoxString implements StringFeatureFlag

RoxString is a feature flag object with a value of string type. RoxString accepts a list of possible values for the feature flag and a default value. This list of values will be used when selecting new values for the feature and will be available for override via the dashboard. This is similar to the capabilities offered by RoxEnumFlag, with a focus on string enumerations only.

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()

Gets the name of this feature flag.

Returns

The feature flag’s name.

getValue

String getValue()
String getValue(Context context)

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

Class RoxInt

package io.rollout.flags;

class RoxInt implements IntFeatureFlag

RoxInt is a feature flag object with a value of integer type.

Example

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

getName

String getName()

Gets the name of this feature flag.

Returns

The feature flag’s name.

getValue

int getValue()
int getValue(Context context)

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

Class RoxDouble

package io.rollout.flags;

class RoxDouble implements DoubleFeatureFlag

RoxDouble is a feature flag object with a value of double precision type.

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()

Gets the name of this feature flag.

Returns

The feature flag’s name.

getValue

double getValue()
double getValue(Context context)

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

interface Context

package io.rollout.context;

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.

You can create a context using the context’s Builder and sending a Map in the following format:

Context from(Map<String, Object> map)

Example

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

get

Object get(String key)

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

Interface ConfigurationFetchedHandler

package io.rollout.client;

interface ConfigurationFetchedHandler
void onConfigurationFetched(FetcherResults results)

where FetcherResults contains the following information:

MethodDescription
FetcherStatus getFetcherStatus()

Fetch status. Can be one of the following: AppliedFromEmbedded - embedded configuration applied; AppliedFromLocalStorage - cached configuration applied; AppliedFromNetwork - remote configuration applied; ErrorFetchedFailed - failed 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 will return error details. Otherwise it will return null.

For an example, see Configuration fetched handler.

Interface ImpressionHandler

package io.rollout.client;

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

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

MethodDescription
String getName()

Impression’s flag name.

String getValue()

Impression value.

boolean isTargeting()

Indicates whether the flag is active or killed.

Context getContext()

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

For an example, see Impression handler.

DynamicPropertyRule

package io.rollout.properties;

interface DynamicPropertyRule

The functional interface containing the following method:

Object invoke(String propName, Context context)

This method is invoked every time when a condition with an unknown property is being evaluated.

ParameterModifier and TypeDescription

propName

String

Property name being evaluated.

context

Context

Context being used for evaluation. Can be null.

Returns

Property evaluation result.

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;
  }
};