Rollout.io - Documentation

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 Rollout 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 behaviour. 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 Rollout.io 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, 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.

Parameters

Parameter
Modifier and Type
Description

rolloutKey

String

The application Rollout 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 Rollout 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 Rollout dashboard and will be named with the object name

Parameters

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

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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 semver.org for more information on Semantic Versioning

Parameters

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, which is a string property you can fetch by name
Parameters

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 property that was registered before it

Use with Caution
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 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 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

Parameters

Parameter
Modifier and Type
Description

flagName

String

Flag name to evaluate

context

Context

The context to be used when evaluating 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 theRoxOptions 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

Parameters

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

Parameters

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

Parameters

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 Rollout dashboard for targeting.

Parameters

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

Parameters

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

Parameters

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 Rollout-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 Rollout flags 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 Rollout, creating relevant flags in Rollout'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 behaviours 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.

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

Parameters
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 Rollout's 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 CustomProperties to evaluate the experiment expression and return the flag value

You can create a context using the Context's Builder and sending a Map to its from function, which looks like this :
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)

Has a couple of useful parameters which can help you decide on further actions.
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)

Example
see Impression Handler

Java API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.