Java API (4.9)

10 minute read

Class Rox

package: io.rollout.rox.server.Rox

public class Rox extends Object
▼

The Rox class provides your application its primary interface with feature flags in the CloudBees Feature Management system. This is the central repository for your application’s flags, it handles communications with the server to obtain the latest values, experiment settings, and configurations. 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 CloudBees Feature Management 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

public static Future<Void> setup(String rolloutKey)
▼
public static Future<Void> 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<Void> that completes when the SDK has retrieved data from CloudBees Feature Management servers.

register

public 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 and configurations 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

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 RoxConfigurationString welcomeMessageText = new RoxConfigurationString("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 and configuration in the dashboard will have the names Login.welcomeMessageText and Login.enableLogin. This is very handy if you want to have groups of flags and configuration.

If you don’t need a namespace, you can set the namespace to an empty string.

setCustomComputedBooleanProperty

public static void setCustomComputedBooleanProperty(String name, io.rollout.properties.CustomPropertyGenerator<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

public static void setCustomComputedDoubleProperty(String name, io.rollout.properties.CustomPropertyGenerator<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

public static void setCustomComputedIntegerProperty(String name, io.rollout.properties.CustomPropertyGenerator<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

public static void setCustomComputedSemverProperty(String name, io.rollout.properties.CustomPropertyGenerator<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

public static void setCustomComputedStringProperty(String name, io.rollout.properties.CustomPropertyGenerator<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

public 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

public 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 property name

value

double

The value of the property

setCustomIntegerProperty

public 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 property name

value

int

The value of the property

setCustomSemverProperty

public 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

public 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

reset

public void reset()
▼

This function unregisters all flags, remote variables, and custom properties that were registered before it.

This function should not be used in production and exists for cases where classes can hot reload, to allow the re-registration of flags. (Hot reloading is usually done as part of the development process.)

dynamicAPI

public static RoxDynamicAPI dynamicAPI()
▼

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

Class RoxDynamicAPI

package io.rollout.rox.server;

public class RoxOptions extends Object
▼

RoxDynamicAPI 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, RoxDynamicAPI is used to get the flag value by passing in context and defaultValue.

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

isEnabled (dynamic api)

public boolean isEnabled(String flagName,boolean defaultValue)
▼
public 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

Class RoxOptions

package io.rollout.rox.server;

public class RoxOptions extends Object
▼

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)
    .build();
Rox.setup(this, options);
▼

Class RoxOptions.Builder

package io.rollout.rox.server;

public static class RoxOptions.Builder extends Object
▼

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

build

public RoxOptions build()
▼

Builds the RoxOptions object, with the configured options.

Returns

A RoxOptions object containing the specified option values.

withVerboseLevel

public 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

public 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

public 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

public 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

public 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

public RoxOptions.Builder withFetchIntervalInSeconds(long intervalInSeconds)
▼

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

intervalInSeconds

long

seconds between fetch requests default: 60 minimum: 30

Returns

The builder instance.

Interface RoxContainer

package io.rollout.configuration;

public 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 RoxConfigurationString welcomeMessageText = new RoxConfigurationString("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 RoxEnumVariant

package io.rollout.flags;

public class RoxEnumVariant<T extends Enum<T>> extends Object
▼

Type Parameters

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

RoxEnumVariant 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 RoxEnumVariant 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 RoxEnumVariant<Colors> colorFeature = new RoxEnumVariant<>(Colors.Blue);
▼

getName

public String getName()
▼

Gets the name of this feature flag.

Returns

The feature flag’s name.

getRawVariant

public RoxVariant getRawVariant()
▼

Returns the current RoxVariant object that represents the flag’s value

Returns

A RoxVariant object representing the current flag value.

getValue

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

public class RoxFlag extends RoxVariant
▼

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

public RoxFlag enabled(io.rollout.flags.Flaggable enabledAction)
▼

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

public RoxFlag disabled(io.rollout.flags.Flaggable disabledAction)
▼

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

public boolean isEnabled()
▼
public boolean isEnabled(Context context)
▼

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

Returns

boolean

getName

public String getName()
▼

Returns the name of this flag.

Overrides

getName in class RoxVariant.

Returns

String name of this RoxFlag.

Class RoxVariant

Package:`io.rollout.flags`

public class RoxVariant extends Object
▼

RoxVariant is a feature flag object that can have values more complex than a simple boolean true or false. RoxVariant 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 RoxEnumVariant, with a focus on string enumerations only.

Example

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

getDefaultValue

public String getDefaultValue()
▼

Returns the default value for this flag. This value is the value of the flag at instantiation.

Returns

The default value provided during flag creation.

getName

public String getName()
▼

Gets the name of this feature flag.

Returns

The feature flag’s name.

getOptions

public String[] getOptions()
▼

Returns the possible values for the flag as Strings.

Returns

A string array of the possible flag values.

value

public String value()
▼

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

interface Context

package io.rollout.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:

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

ImpressionHandler functor (onImpression)

The functor signature is: onImpression(ReportingValue reportingValue, Experiment experiment, Context context)

ReportingValue provides the flag name and value:

Method Description 
public String getName()
▼

Impression’s flag name

 
public String getValue()
▼

Impression value

Experiment provides the experiment data:

Method Description 
public String getName()
▼

Experiment name

 
public String getIdentifier()
▼

Experiment Id

 
public Boolean getIsArchived()
▼

Indication whether the experiment is archived

 
public Set<String> getLabels()
▼

Experiment’s labels Assigned on dashboard.

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

JavaScript SSR API
C# API