Java API

13 minute readReference

The following information is for the latest version of the Java server SDK. If you are running an older version, please check the CloudBees Feature Management - Java server changelog for any differences.

Class Rox

package io.rollout.rox.server;

class Rox
▼

The Rox class provides an interface for CloudBees Feature Management 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 CloudBees Feature Management 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 Future<CoreState> setup(String rolloutKey)
static Future<CoreState> setup(String rolloutKey, RoxOptions options)
▼

Setup the SDK with the rollout key.

Parameter Modifier and Type Description

rolloutKey

String

The application’s CloudBees Feature Management 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 CloudBees Feature Management 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.

Parameter Modifier and Type Description

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.

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

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.

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

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.

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

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

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

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.

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

static void setCustomBooleanProperty(String name, boolean value)
▼

Sets a custom property representing a 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

static void setCustomDoubleProperty(String name,double value)
▼

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

Parameter Modifier and Type Description

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.

Parameter Modifier and Type Description

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.

Parameter Modifier and Type Description

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.

Parameter Modifier and Type Description

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.

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

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

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

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 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, 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 is below. It sets the verbosity level to "Debug", provides an impression handler, a fetch handler, and more.

To use with a proxy server, refer to Using a proxy for more information.

 RoxOptions options = new RoxOptions.Builder()
    .withFetchIntervalInSeconds(50)
    .withVerboseLevel(RoxOptions.VerboseLevel.VERBOSE_LEVEL_DEBUG)
    .withVersion(appVersion)
    .withLogger(logger)
    .withHosting("eu")
    .withConfigurationFetchedHandler(fetchHandler)
    .withImpressionHandler(impressionHandler)
    .withDynamicPropertyRule(dynamicPropertyRule)
    .withProxy(new ProxyConfig("http://proxy.example.com", "sdkuser", "sdkpassword"))
    .build();
Rox.setup(rolloutKey, 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.

Parameter Modifier and Type Description

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.

Parameter Modifier and Type Description

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.

Parameter Modifier and Type Description

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 CloudBees Feature Management dashboard for targeting.

Parameter Modifier and Type Description

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.

Parameter Modifier and Type Description

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.

Parameter Modifier and Type Description

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

Parameter

Modifier and Type

Description

dynamicPropertyRule

DynamicPropertyRule

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

Returns

The builder instance.

withHosting

RoxOptions.Builder withHosting(String region)
▼

Configures the RoxOptions Builder object with a region of your choice

Parameter

Modifier and Type

Description

region

String

The region to use, currently supported option: "eu" (any other value will result default, which is us hosting)

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 CloudBees Feature Management-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 CloudBees Feature Management 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:

Method Description 
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:

Method Description 
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.

Parameter Modifier and Type Description

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;
  }
};
▼
Go API
JavaScript Browser API