Android API (4.9)

10 minute read

Class Rox

package: io.rollout.android 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 the dashboard for your application 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 void setup(Application app) public static void setup(Application app,RoxOptions options)

Configures the Rox object to work with the provided Android application. Using this method will result in a default verbosity level of VERBOSE_LEVEL_SILENT. If provided, apply the provided RoxOptions object, which can be used to set an increased level of logging verbosity and a callback for the completion of each sync with the server.

Parameters

Parameter Modifier and Type Description

app

Application

An Android application object representing the feature-controlled app to be managed

options

RoxOptions

A RoxOptions instance with the desired configuration for this application

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 a flag in your CloudBees Feature Management 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

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 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 https://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 https://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 properties that were registered before the call to reset.

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

RoxDynamicAPI dynamic = Rox.dynamicAPI();
boolean flagAEnabled = dynamic.isEnabled("flagA", false);
▼

isEnabled (dynamic api)

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

defaultValue

boolean

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

Class RoxOptions

Package:`io.rollout.client` public class RoxOptions extends Object

RoxOptions covers configuration options for the Rox client. This includes settings like 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()
    .withVerboseLevel(RoxOptions.VerboseLevel.VERBOSE_LEVEL_DEBUG)
    .withPlatform("FireTv")
    .withLogger(logger)
    .withConfigurationFetchedHandler(fetchHandler)
    .withFlagImpressionHandler(impressionHandler)
    .withFreeze(Freeze.UntilLaunch)
    .build();
Rox.setup(this, options);
▼

Class RoxOptions.Builder

Package:`io.rollout.android.client` 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

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 the a custom Logger, overrides the default logger logcat

Parameters

Parameter Modifier and Type Description

logger

Logger

a custom logger instance

Returns The builder instance

withFreeze

public RoxOptions.Builder withFreeze(Freeze freeze)

Configures the RoxOptions Builder object with the a default freeze behavior

Parameters

Parameter Modifier and Type Description

freeze

Freeze

the default flag freeze level to set unless it was overridden on flag constructor

Returns The builder instance

withFlagImpressionHandler

public RoxOptions.Builder withFlagImpressionHandler(FlagImpressionHandler flagImpressionHandler)

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

Parameters

Parameter Modifier and Type Description

flagImpressionHandler

FlagImpressionHandler

a Functor instance to be evaluated when flag is first evaluated

Returns The builder instance

withPlatform

public RoxOptions.Builder withPlatform(String platform)

Configures the RoxOptions Builder object with a custom platform, any String is applicable here. In practice, custom platform is used to allow easier separation of values to be sent to the client. (e.g. Android Tv, Android Tablet, Tizen)

Parameters

Parameter Modifier and Type Description

platform

String

A custom platform, any String is applicable here. (e.g. Android Tv, Android Tablet, Tizen)

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 static feature flags are converted into CloudBees Feature Management flags when the container is registered with Rox using Rox.register(). Feature flag names will be derived from the provided flag variable names.

Example Here’s 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, creating relevant flags
   Rox.register(conf)
   // Performs final setup of the Rox application.
   Rox.setup(this.getApplication());
▼

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

Parameters name - the new name for the feature flag object

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.animatedOnboarding.disabled(new Flaggable() {
    @Override
    public void execute() {
    // show old onboarding
  }
});
▼

The above code defines 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.animatedOnboarding.enabled(new Flaggable() {
    @Override
    public void execute() {
    // show animated onboarding
    }
}).disabled(new Flaggable() {
  @Override
    public void execute() {
    // show old onboarding
    }
});
▼

You can also leverage Java 8 Lambda expressions to create handler code that is easier to read:

roxContainer.featureFromAndroid1.enabled(() ->  {
    // show animated onboarding
}).disabled(() ->  {
    // show old onboarding
});
▼

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

Returns true if the flag is enabled

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

ImpressionHandler functor (onImpression)

Contains a few useful parameters to help you decide on further actions. The functor signature is onImpression(ReportingValue reportingValue, Experiment experiment)

ReportingValue provides the flag name and value:

Method Description

public String getName()

Impression’s flag name

public String getValue()

Impression value

Experiment provides the flag’s 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

For example, see Impression handler.

Objective-C API
JavaScript Browser API