Java SDK reference

13 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.rox.server;

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 Future<CoreState> setup(String appKey)
static Future<CoreState> setup(String appKey, RoxOptions options)
▼

Set up the SDK with the application key.

Parameter Modifier and type Description

appKey

String

The application’s CloudBees platform key.

RoxOptions

A RoxOptions instance with the desired configuration for this application.

Returns Future<CoreState> that completes when the SDK has retrieved data from the platform.

If setup was successful, the returned future returns CoreState.Set. If the returned state is CoreState.Corrupted, then CloudBees recommends that you analyze logging output in order to identify the reason for the failure.

Further Rox.setup calls after Rox is set are ignored, unless the last setup failed, or unless Rox.shutdown is invoked.

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(appKey);
▼

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

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.

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 1. 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 2. 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 3. 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 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.

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

static void shutdown()
▼

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

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.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 follows. It sets the verbosity level to DEBUG and provides options such as an impression handler and a fetch handler.

 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

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 SLF4J logger. Returns the builder instance.

Parameter Modifier and type Description

logger

Logger

A custom logger instance.

withVersion

RoxOptions.Builder withVersion(String version)
▼

Configures the RoxOptions.Builder object with the app version. This version can be used in the UI for targeting. Returns the builder instance.

Parameter Modifier and type Description

version

String

the app version.

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 flag is evaluated.

withFetchIntervalInSeconds

RoxOptions.Builder withFetchIntervalInSeconds(long intervalInSeconds)
▼

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

Parameter Modifier and type Description

intervalInSeconds

long

seconds between fetch requests default: 60 minimum: 30.

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.

withCustomStorageImplementation

Provides the custom storage implementation used for caching. Returns the builder instance.

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

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
   public class MyContainer implements RoxContainer {
     // This creates 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(appKey);
▼

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

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

Class RoxString

package io.rollout.flags;

class RoxString implements StringFeatureFlag
▼

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 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 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 name of the feature flag.

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

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