Java client SDK reference

The CloudBees Java (client-side) SDK allows applications to manage feature flags dynamically. It is designed for applications running on user devices, such as mobile apps and desktop clients.

Prerequisites:

Java 8 or later
Install the SDK by following the steps in the Java SDK installation

The following information is for the latest SDK version (6.x). The CloudBees platform requires that your installed SDK version be at least 6.x. Please install the latest SDK by following the instructions in the platform UI or in the SDK installation documentation.

Any updates to version 6.x are noted in the platform changelog.

ROX class

The Rox class provides an interface for the CloudBees platform to manage feature flags that control the behavior of your application. This class handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. It works with a RoxContainer-derived object, which holds your application’s feature flags.

The values in the provided container are marked as feature flags and displayed in the UI once the application is run.

This class also allows you to manage custom properties. These can be static settings of type String, boolean, int, 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, for example:

Setting verbosity level
Custom platform
Global freeze level
Impression handler
Fetch handler

Setup

Set up the SDK with the application key.

public class FeatureFlagsExample {
    public static void main(String[] args) {
        String rolloutKey = "YOUR_ROLLOUT_KEY";

        Rox.setup(rolloutKey).thenAccept(coreState -> {
            if (coreState == CoreState.Set) {
                System.out.println("Feature flags successfully initialized.");
            } else {
                System.err.println("Feature flag initialization failed.");
            }
        });
    }
}▼

Parameters:

appKey: The application’s CloudBees platform key.
options: A RoxOptions instance with the desired configuration for this application.

Returns:

A Future<CoreState> that completes when the SDK has retrieved data from the platform.

If the setup is successful, CoreState.Set is returned.
If CoreState.Corrupted is returned, CloudBees recommends that you analyze the logging output to identify the reason for the failure.
Once Rox.setup has been issued, additional Rox.setup calls are ignored, unless the last setup failed, or Rox.shutdown is invoked.

Shutdown

Deactivates the SDK and unregisters all feature flags.

public class FeatureFlagsExample {
    public static void main(String[] args) {
        Rox.setup("YOUR_ROLLOUT_KEY");

        // Cleanup before application exit
        Runtime.getRuntime().addShutdownHook(new Thread(() -> {
            Rox.shutdown();
            System.out.println("SDK shutdown complete.");
        }));
    }
}▼

Register

Register a feature flag container with the Rox client. The public member variables of this container will become flags in your dashboard and will be named with the object name.

public class RoxFeatureManager {
    public static void register(RoxContainer container) {
        // Registration logic here
    }

    public static void register(String namespace, RoxContainer container) {
        // Registration logic with namespace
    }
}▼

Parameters:

namespace: The prefix namespace for all flags in this container; defaults to an empty string if not provided.
container: An object derived from RoxContainer that contains your application’s feature flags.

For example, assume we have the following container:

package com.example.pacman;

public class MyContainer implements RoxContainer {
  public RoxString welcomeMessageText = new RoxString("Hello User");
  public RoxFlag enableLogin = new RoxFlag();
}▼

And we register the container with the following code:

public class FeatureFlagsExample {
    public static void main(String[] args) {
        String rolloutKey = "YOUR_ROLLOUT_KEY"; // Define rollout key
        RoxContainer conf = new MyContainer();
        Rox.register("Login", conf);
        Rox.setup(rolloutKey);
    }
}▼

Class RoxOptions

The RoxOptions class allows you to configure various aspects of the Rox client, including fetch interval and impression handler settings. You can create instances of this class using RoxOptions.Builder.

RoxOptions configuration

The RoxOptions class lets you customize SDK behavior.

Option Description

Option	Description
`setFetchIntervalInSeconds(int interval)`	Sets how often feature flag updates are retrieved.
`setImpressionHandler(ImpressionHandler handler)`	Defines how impressions (flag evaluations) are logged.
`setConfigurationFetchedHandler(ConfigurationFetchedHandler handler)`	Handles SDK config fetch events.
`setVerboseLevel(VerboseLevel level)`	Sets logging verbosity.

setFetchIntervalInSeconds(int interval)

Sets how often feature flag updates are retrieved.

setImpressionHandler(ImpressionHandler handler)

Defines how impressions (flag evaluations) are logged.

setConfigurationFetchedHandler(ConfigurationFetchedHandler handler)

Handles SDK config fetch events.

setVerboseLevel(VerboseLevel level)

Sets logging verbosity.

For example, the following sets up a new RoxOptions object:

public class FeatureFlagsExample {
    public static void main(String[] args) {
        RoxOptions options = new RoxOptions.Builder()
            .setImpressionHandler(new ImpressionHandler() {
                @Override
                public void onImpression(ReportingValue value, Experiment experiment, Context context) {
                    // Handle impression
                }
            })
            .setConfigurationFetchedHandler(new ConfigurationFetchedHandler() {
                @Override
                public void onConfigurationFetched(FetcherResult result) {
                    // Handle configuration fetched
                }
            })
            .build();
    }
}▼

Set global context

The global context allows feature flags to evaluate user-specific data.

import java.util.Map;
import com.cloudbees.feature.management.Rox;
import com.cloudbees.feature.management.context.Context;
import com.google.common.collect.ImmutableMap;

Context userContext = new Context.Builder()
    .from(ImmutableMap.of("userRole", "admin", "region", "EU"))
    .build();

Rox.setContext(userContext);▼

Class RoxFlag

The RoxFlag class represents a Boolean feature flag. It allows you to enable or disable specific features in your application.

Example:

public class Flags implements RoxContainer {
    public RoxFlag enableTutorial = new RoxFlag(false);
}▼

Class RoxString

The RoxString class represents a string-based feature flag with a default value and an optional list of possible values.

Example:

public class Flags implements RoxContainer {
    public RoxString titleColor = new RoxString("red", new String[]{"red", "blue", "green"});
}▼

Class RoxInt

The RoxInt class represents an integer-based feature flag with a default value and an optional list of possible values.

Example:

public class Flags implements RoxContainer {
    public RoxInt titleSize = new RoxInt(14, new Integer[]{14, 18, 24});
}▼

Class RoxDouble

The RoxDouble class represents a double-based feature flag with a default value and an optional list of possible values.

Example:

public class Flags implements RoxContainer {
    public RoxDouble priceVariant = new RoxDouble(19.99, new Double[]{19.99, 29.99, 40.5});
}▼