Java SDK Reference

Updated 3 months ago by Archana Singh

This topic explains how to use the Harness Feature Flags (FF) SDK in your Java application. To learn more about using a sample FF SDK code with Java application, see the Java SDK GitHub repository.

In this topic:

Before You Begin

Prerequisites

  1. Create a feature flag in Harness Feature Flags. Feature flags wrap your code and allow you to manage the feature release in a controlled way. See Create a Feature Flag.
  2. Ensure that you have created your SDK Key. See Create an SDK Key.
  3. A Java application to test your feature flag. If you do not have your Java Application, you can download a sample application from the Java SDK GitHub repository.
    1. On the Java SDK GitHub page, click Code and then clone the sample application. For more information, see Cloning a repository.
    2. Import your project in an IDE such as IntelliJ or Eclipse.

Use Harness Feature Flags SDKs with Java Applications

Perform the following steps to get started with using the Feature Flags SDK in your Java application:

Step 1: Install the FF SDK Dependency

The first step is to install the FF SDK as a dependency in your application using your application's dependency manager. You can use Maven, Gradle, SBT, etc. for your application.

Refer to the Harness Feature Flag Java Server SDK to identify the latest version for your build automation tool.

This section lists dependencies for Maven and Gradle and uses the 1.0.0 version:

Maven

Add the following Maven dependency in your pom.xml file:

<dependency>
<groupId>io.harness</groupId>
<artifactId>ff-java-server-sdk</artifactId>
<version>1.0.0</version>
</dependency>

If you are using the Harness Java sample application from the Java SDK GitHub repository, then do not add the Maven dependency in the pom.xml file. The Maven dependencies are added in the Harness Java sample application.

Gradle

implementation group: 'io.harness', name: 'ff-java-server-sdk', version: '1.0.0'

Step 2: Authorize your Application to Connect to the FF Client

After installing the SDK, enter the SDK keys that you created for your environment. The SDK keys authorize your application to connect to the FF client.

CfClient cfClient = new CfClient(apiKey, Config.builder().build());

Step 3: Add a Target

Targets are used to control which user sees the variation of a feature flag. You can add targets and define their attributes in your code directly as well. The targets added in the application code are discovered automatically and populated in the Harness UI.

  • A target can be any attribute that can be uniquely identified with an entity.
  • A target is identified by a name and an identifier.
    • Enter a name that will identify this target.
    • Enter a unique identifier for your target. For example, an application, systems, services, machines, resources uniquely identified by an IP address, email ID, user ID, etc.
    • See Target Management.
Add Individual Target

Target target = Target.builder().name("User1").identifier("user1@example.com").build();

Add a Target with Attributes

Attributes are the properties of your target and used to define rules for your feature flags and target groups.

Target target = Target.builder()
.name("User1")
.attributes(new HashMap<String, Object>())
.identifier("user1@example.com")
.build();

Step 4: Evaluate Target for Your Feature Flag

Once you have added the target, evaluate the target for your feature flag. A feature flag is evaluated for a particular target.

boolean result = cfClient.boolVariation(<feature_identifier>, target, <default_result>);

The <feature_identifier> is your feature flag identifier. When you name a feature flag, Harness automatically generates its identifier. For more information, see Entity Identifier Reference and Create a flag type.

Sample Code for Boolean Flag Type

Here are the sample codes:

Bool Variation

boolean result = cfClient.boolVariation("toggle", target, false);

Number Variation

boolean result = cfClient.numberVariation("sample_number_flag", target, 0);

String Variation

boolean result = cfClient.stringVariation("sample_string_flag", target, "");

Sample Code for Multivariate

Here are the sample codes:

Number Type

double number = cfClient.numberVariation(COUNT_FEATURE_KEY, parentTarget, 1);

String Type

String color = cfClient.stringVariation(COLOR_FEATURE_KEY, target, "black");

Sample FF SDK for Java Application

Here is a sample code for using FF SDKs with Java applications.

To learn more about using a sample CF SDK code with Java application, see the Java SDK GitHub repository.

public class HelloWorld {
public static void main(String[] args) {
try {
/**
* Put the API Key here from your environment
*/
String apiKey = "00000000-1111-2222-3333-444444444444";
CfClient cfClient = new CfClient(apiKey, Config.builder().build());
/**
* Define you target on which you would like to evaluate the featureFlag
*/
Target target = Target.builder()
.name("User1")
.attributes(new HashMap<String, Object>())
.identifier("user1@example.com")
.build();
while (true) {
/**
* Sleep for sometime before printing the value of the flag
*/
Thread.sleep(2000);
/**
* This is a sample boolean flag. You can replace the flag value with
* the identifier of your feature flag
*/
boolean result =
cfClient.boolVariation("toggle", target, false);
log.info("Boolean variation is " + result);
}
} catch (Exception e) {
e.printStackTrace();
}
}
}

Verify Flag Configuration Updates

SDK maintains all the feature flag details locally in its cache and evaluates flags based on it. The SDKs use streaming and a polling strategy to keep the local cache in sync with the flag configurations.

Streaming Mode

Polling Mode

  • In the case of streaming mode, a connection is open to the stream endpoint.
  • Anytime flag configuration updates, a stream event (indicating which flag/target group changed) is pushed to the application on this connection.

  • SDK fetches the latest flag configuration for the flag/target group specified in the event and updates the cache.

Config is polled periodically (default 60 seconds), and the cache is updated.

The following example shows how the variation of a feature flag is served according to its rule. By toggling the flag on/off in Harness UI, the latest features are synced and the updated flag variation is served.


Please Provide Feedback