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 |
---|---|---|
apiKey |
const char * |
The environment key provided by the dashboard |
options |
Options |
A
|
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).
Custom Properties
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 |
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 |
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.
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 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
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.
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
.
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. |