The following information is for the latest version of the C++ SDK. If you are running an older version, please check the CloudBees Feature Management - C/C++ changelog for any differences. |
Rox Namespace
The Rox
namespace provides an interface for CloudBees Feature Management to manage feature flags that control the behavior of your application. This is the central repository for your application’s flags. This namespace handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. The values in the namespace are marked as feature flags and display in the CloudBees Feature Management UI once the application is run.
These classes and interfaces also allow 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
.
You can also use an Options
object to configure some aspects of feature flag management in CloudBees Feature Management. You can set the custom platform, impression handler, dynamic properties rule, and configuration fetched handler.
Setup
StateCode 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 |
Return value
typedef enum RoxStateCode { RoxUninitialized = 0, RoxSettingUp = 1, RoxInitialized = 2, RoxShuttingDown = 3, RoxErrorEmptyApiKey = -1, RoxErrorInvalidApiKey = -2, RoxErrorGenericSetupFailure = -1000 } RoxStateCode;
In case of a successful call, Setup
will return RoxInitialized
code. Otherwise, the application logs should be analyzed for errors and warnings. If Setup
returned failure code, it may be called again after fixing the errors from the logs.
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) { // TODO: do something on impression } }; class ConfigurationFetchedHandler : public Rox::ConfigurationFetchedHandlerInterface { public: explicit ConfigurationFetchedHandler() { } public: void ConfigurationFetched(Rox::ConfigurationFetchedArgs *args) override { // TODO: do something on configuration fetched } }; class DynamicRulerHandler : public Rox::DynamicPropertiesRuleInterface { public: explicit DynamicRulerHandler() {} public: DynamicValue *Invoke(const char *propName, Context *context) { // TODO: 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); // do something... 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 String
Class Int
Class Double
Class Context
The context class is used to pass data to the feature flag 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.
AddUndefined
ContextBuilder &AddUndefined(const char *name)
Adds an undefined value to the name
key in the context.
Build
Context *Build()
Builds the Context
to use in the evaluation of Flag
and Variant
.
For an example, see Flag 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.
GetString/GetInt/GetDouble - obtain flag value
char *GetString(const char *name, char *default_value = nullptr, Context *context = nullptr); char *GetString(const char *name, char *default_value, const std::vector<std::string> &options, Context *context); int GetInt(const char *name, int default_value, Context *context = nullptr) int GetInt(const char *name, int default_value, const std::vector<int> &options Context *context) double GetDouble(const char *name, double default_value, Context *context = nullptr); double GetDouble(const char *name, double default_value, const std::vector<double> &options, Context *context);
Evaluate a feature flag 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.
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 submit a product request directly to CloudBees Support. |