C++ API (4.9)

Class Rox

The Rox class provides your application with its primary interface with feature flags in the CloudBees Feature Management system. This interface manages your application’s flags repository, handles communications with the server to obtain the latest values, implements experiment settings, and sets up configurations. It provides a mechanism through which you can use feature flags to control your application’s behavior. The repository manages RoxVariant structures, which holds your application’s feature flags. Those variants 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 CustomPropertyGeneratorInterface, which is an interface.

You can also use a RoxOptions object to configure some aspects of this class. You can set the custom platform, impression handler, and configuration fetched handler.

Setup

void Setup(const char *api_key, Options *options = nullptr)

Configures the Rox object to work with the provided application.

Parameter Modifier and Type Description

Parameter	Modifier and Type	Description
apiKey	const char *	The environment key provided by the dashboard
options	Options	A `Options` instance with the desired configuration for this application optional

apiKey

const char *

The environment key provided by the dashboard

options

Options

A Options instance with the desired configuration for this application

optional

Shutdown

void Shutdown()

Frees all Rox Internal Objects. Should be used on application exit.

Example

// application start
Rox::Setup(DEFAULT_API_KEY)

// application end
Rox::Shutdown();

SetContext

void SetContext(Context *context)

Set a global context. This context will be available to all flags evaluations (in addition to the specific call context).

Fetch

void Fetch()

Create a network request for the latest configuration.

Custom Properties

The role of Custom Properties is to segment the audience.

The custom properties can be these types:

bool
int
double
semver
string

There are simple (direct) Custom Properties and calculated ones, using RoxContext to be more dynamic.

Simple (direct) Custom Properties

SetCustomProperty

template<typename T> void SetCustomProperty(const char *name, T value)

Sets a custom property representing a T value.

Parameter	Modifier and Type	Description
name	const char *	The name of the property to create
value	T	The value for the custom property depends on the type

Parameter

Modifier and Type

Description

name

const char *

The name of the property to create

value

The value for the custom property depends on the type

SetCustomSemverProperty

voidSetCustomSemverProperty(const char *name, const char *value)

Sets a custom property representing a semver value.

Parameter	Modifier and Type	Description
name	const char *	The name of the property to create
value	const char *	The semver value for the custom property

Parameter

Modifier and Type

Description

name

const char *

The name of the property to create

value

const char *

The semver value for the custom property

Computed Custom properties (using RoxContext)

SetCustomComputedProperty

template<typename T> void SetCustomComputedProperty(const char *name, CustomPropertyGeneratorInterface *generator)

Sets a computed T Custom Property on the Rox client. This is a computable T, with an object that generates the value for the property. The generator should be a delegate of type CustomPropertyGeneratorInterface.

Parameter	Modifier and Type	Description
name	const char *	The name of the property to create
generator	CustomPropertyGeneratorInterface *	A CustomPropertyGeneratorInterface class

Parameter

Modifier and Type

Description

name

const char *

The name of the property to create

generator

CustomPropertyGeneratorInterface *

A CustomPropertyGeneratorInterface class

SetCustomComputedSemverProperty

void SetCustomComputedSemverProperty(const char *name, CustomPropertyGeneratorInterface *generator)

Sets a computed semver Custom Property on the Rox client. This is a computable semver, with an object that generates the value for the property. The generator should be a delegate of type CustomPropertyGeneratorInterface.

Parameter	Modifier and Type	Description
name	string	The name of the property to create
generator	CustomPropertyGeneratorInterface *	A CustomPropertyGeneratorInterface class

Parameter

Modifier and Type

Description

name

string

The name of the property to create

generator

CustomPropertyGeneratorInterface *

A CustomPropertyGeneratorInterface class

Class Options

RoxOptions covers configuration options for the Rox client. This includes settings like configuration fetch interval, impression handler and more.

Instances of this class should be created using OptionsBuilder.

Here is an example of setting up a new Options object. This options object sets the version, provides an impression handler, and calls the fetch handler.

class ImpressionHandler : public Rox::ImpressionHandlerInterface {
    public:
        explicit ImpressionHandler() {}

    public:
        void HandleImpression(
            RoxReportingValue *value,
            RoxExperiment *experiment,
            RoxContext *context) {
      // do something on impression
        }
};

class ConfigurationFetchedHandler : public Rox::ConfigurationFetchedHandlerInterface {
  public:
    explicit ConfigurationFetchedHandler() {
  }

  public:
    void ConfigurationFetched(Rox::ConfigurationFetchedArgs *args) override {
            // do something on configuration fetched
    }
};

class DynamicRulerHandler : public Rox::DynamicPropertiesRuleInterface {
    public:
        explicit DynamicRulerHandler() {}

    public:
        DynamicValue *Invoke(const char *propName, Context *context) {
      // return a DynanmicValue
        }
};

int main(int argc, char **argv) {
    ImpressionHandler imp = ImpressionHandler();
  ConfigurationFetchedHandler conf = ConfigurationFetchedHandler();
  DynamicRulerHandler dynamicRule = DynamicRulerHandler();

  Rox::Options *options = Rox::OptionsBuilder()
        .SetConfigurationFetchedHandler(&conf)
    .SetDevModeKey("your_dev_mode_secret")
    .SetDynamicPropertiesRule(&dynamicRule)
    .SetImpressionHandler(&imp)
    .SetRoxyUrl("http://localhost:4444")
    .SetVersion("2.1.0")
        .SetFetchInterval(100)
    .Build();

    Rox::Setup("ROLLOUT_KEY", options);
    Rox::Shutdown();
}

Class OptionsBuilder

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

SetVersion

OptionsBuilder &SetVersion(const char *version);

Set the version of the service running the CloudBees Feature Management SDK. This can be used on the dashboard for targeting filtering.

SetFetchInterval

OptionsBuilder &SetFetchInterval(int intervalInSeconds)

Set the polling interval for fetching configuration from the CloudBees Feature Management storage service.

SetConfigurationFetchedHandler

OptionsBuilder &SetConfigurationFetchedHandler(ConfigurationFetchedHandlerInterface *handler)

Set the configuration event handler to actions after configurations are fetched.

SetImpressionHandler

OptionsBuilder &SetImpressionHandler(ImpressionHandlerInterface *handler)

Set the impression event handler to add actions after an impression.

SetDynamicPropertiesRule

OptionsBuilder &SetDynamicPropertiesRule(DynamicPropertiesRuleInterface *rule)

The Dynamic Custom Property Generator is called when an explicit Custom property definition does not exists on the client side.

If you do not set the SetDynamicPropertiesRule, it will then activate the default function which tries to extract the prop value from the context by its name.

if (context != NULL) {    return rox_context_get(context, prop_name);  }  return NULL;

Class DynamicPropertiesRuleInterface

Create a custom dynamic property rule, by overriding this class.

Invoke

virtual DynamicValue *Invoke(const char *propName, Context *context) = 0

See C API RoxDynamicValue for DynamicValue.

For an example, see Defining custom properties.

SetRoxyUrl

OptionsBuilder &SetRoxyUrl(const char *roxy_url)

A roxy URL. See Microservices automated testing and local development.

SetDevModeKey

OptionsBuilder &SetDevModeKey(const char *devModeKey)

Set dev mode secret.

See Enabling secret mode.

Build

Options *Build()

Creates the options object with all the property that were set.

Class Variant

Variant is a feature flag object that can have values more complex than a simple boolean true or false. Variant accepts a list of possible values 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.

GetValue

char *GetValue(Context *context = nullptr)

Returns the variant current value (or the default if no value was set).

GetValueOrNull

char *GetValueOrNull(Context *context = nullptr)

Returns the variant current value or null.

Create

static Variant *Create(const char *name, const char *defaultValue)

Create a Variant with only default value.

Flags and Variants name can (optional) include a namespace. this is done by including a "." in the name.

For example, for system.serviceType on the dashboard, system will be the namespace, and the variant name will be serviceType.

Separating Flags and Variants to namespace is only for your convenient.

static Variant *Create(const char *name, const char *defaultValue, const std::vector<std::string> &options)

Create a Variant with default value and options.

Class Flag

Flag is a boolean feature flag. It can be either true or false.

IsEnabled

bool IsEnabled(Context *context = nullptr)

Returns the feature flag current value (or the default if no value was set).

Create

static Flag *Create(const char *name, bool defaultValue = false)

Create a Flag with default value.

Class Context

The context class is used to pass data to the Flag or Variant evaluation. This object is used by the registered CustomProperties to evaluate the experiment expression and return the value.

You can create a context using the ContextBuilder.

Class ContextBuilder

ContextBuilder

ContextBuilder()

A simple constructor.

AddBoolValue

ContextBuilder &AddBoolValue(const char *name, bool value)

Adds a bool value to the name key in the context.

AddIntValue

ContextBuilder &AddIntValue(const char *name, int value)

Adds a int value to the name key in the context.

AddDoubleValue

ContextBuilder &AddDoubleValue(const char *name, double value)

Adds a double value to the name key in the context.

AddStringValue

ContextBuilder &AddStringValue(const char *name, const char *value)

Adds a string value to the name key in the context.

AddUndefined

ContextBuilder &AddUndefined(const char *name)

Adds an undefined value to the name key in the context.

AddNull

ContextBuilder &AddNull(const char *name)

Adds a NULL value to the name key in the context.

Build

Context *Build()

Builds the Context to use in the evaluation of Flag and Variant.

Using ConfigurationFetchedHandler

As seen in OptionsBuilder, SetConfigurationFetchedHandler can be used to write a handler for after new configurations request. To do so, implement ConfigurationFetchedHandlerInterface.

Class ConfigurationFetchedHandlerInterface

ConfigurationFetched

virtual void ConfigurationFetched(ConfigurationFetchedArgs *args) = 0

For ConfigurationFetchedArgs, please see RoxConfigurationFetchedArgs C API.

For an example, see Configuration fetched handler.

Using ImpressionHandler

The impression handler delegate (as seen in OptionsBuilder SetImpressionHandler) has a couple of useful parameters which can help you decide on further actions.

To use the impressions handler implement the class ImpressionHandlerInterface.

Class ImpressionHandlerInterface

HandleImpression

virtual void HandleImpression(ReportingValue *value, Experiment *experiment, Context *context) = 0

See C API RoxReportingValue (for ReportingValue) and RoxExperiment (for Experiment).

For an example, see Impression handler.

Class DynamicApi

DynamicApi is a way to evaluate flags and variants by their name, on the fly, without creating a Flag or Variant object before (using their Create method).

Create

static DynamicApi *Create()

Create a DynamicApi, the proxy to all dynamic flags and variants evaluation.

IsEnabled

bool IsEnabled(const char *name, bool default_value = false, Context *context = nullptr)

Evaluate a flag by its name, and context.

If no experiment was set via the dashboard, the default_value will be returned.

GetValue

char *GetValue(const char *name, char *default_value = nullptr, Context *context = nullptr)

Evaluate a Variant by its name, and context. Options will be sent to the dashboard to allow an easy pick in the experiment.

If no experiment was set via the dashboard, the default_value will be returned.

GetValue

char *GetValue(const char *name, char *default_value,const std::vector<std::string> &options, Context *context)

Evaluate a Variant by its name, and context. Options will be sent to the dashboard to allow an easy pick in the experiment.

If no experiment was set via the dashboard, the default_value will be returned.

Adding on CloudBees Feature Management dashboard new variations (options parameter).

For an example, see Dynamic API.

Logging

Logging helps debug in case something behave unexpectedly.

If no logging was set, default will be used, this means print to stdout errors level logs.

There are 2 method to control logging:

SetLogLevel

static void SetLogLevel(LogLevel logLevel)

To use the default logging, with a different log level.

See RoxLogLevel in C API.

SetLogMessageHandler

static void SetLogMessageHandler(LogMessageHandlerInterface *handler)

To use a customized logger, this is done by providing a class that implements LogMessageHandlerInterface.

Class LogMessageHandlerInterface

HandleLogMessage

virtual void HandleLogMessage(LogMessage *message) = 0

The customized logging handler. See RoxLogMessage C API for LogMessage.

For an example, see Turning on verbose logging.

C++ is a C wrapper

Didn’t find what you were looking for? Please look in C Api, some structs have a matching struct without the Rox prefix (For Example C’s RoxDynamicValue ⇒ C++'s DynamicValue)

Still no luck? Please contact us.