Java Quickstart

Updated 3 months ago by Archana Singh

This quickstart shows you how to create a Feature Flag in Harness and use Feature Flags (FF) SDK in your Java application.

Objectives

You'll learn how to:

  • Create a Project in Harness
  • Create a Feature Flag in Harness
  • Create an Environment
  • Add an SDK Key for your Environment
  • Use Harness Feature Flags SDKs with Java Applications. Your flag is automatically available for use in all environments of your project. However, you need to install Harness SDK to environments you wish to initiate your flag in.

Before You Begin

Review Feature Flag and Client-Side and Server-Side SDKs to establish a general understanding of Harness Feature Flag and SDKs.

Feature Flags Overview

The following video provides a general overview of how Harness Feature Flags work:

Step 1: Create a Project

As a first step, you need to create a project in Harness. Here is a quick visual summary of the steps involved:

  1. In Harness, click Feature Flags and click Create Project.
  2. In Projects, click Project.
  3. In About the Project, in Name, enter the name for your project. You will create your Feature Flag for this project.
  4. (Optional) Select color for your project.
  5. Select the Organization from the list. If you need to create a new organization, see Create a Harness Organization and Projects and Organizations.
  6. Click Save and Continue.
  7. (Optional) In Invite Collaborators, in Invite People to Collaborate, add members to collaborate.
  8. (Optional) Assign a role to the collaborators and click Add. You can select Project AdminProject Member, or Project Viewer. For more information on the permissions, see Permissions Reference.
  9. Once you're done adding contributors and adding a role, click Save and Continue.
  10. Click GO TO FEATURE FLAGS.

Step 2: Create an Environment

Once you've created a project, you need to create an environment. An environment is the representation of your production or non-production infrastructure. You can configure the targeting rules of your flag in the environment.

Here is a quick visual summary of the steps involved:

  1. In Feature Flags, select the Project that you created. For example, FFDOcs.
  2. In your Project, in Environments, click Create an Environment.
  3. Enter a name for your environment.
  4. Select the environment type and click Create.

    Your environment is listed in Environments.

Step 3: Create an SDK Key

Now you have the environment ready, you need to create an SDK key for your environment. The SDK keys are used in your application's code to authorize your application to connect to the Feature Flag client.

Here is a quick visual summary of the steps involved:

  1. Click on the environment that you created in the previous step.
  2. In Environments, in Settings, click Add Key.
  3. In Create SDK Key, in Name, enter a name for your SDK key.
  4. In Key Type, select the Key Type. You can select Client or Server. For this quickstart, we'll use the Server Key type.

    Client Key Type

    Server Key Type

    The client-side ID is not considered confidential and they are visible all the time.

    Keys are visible right after the creation and redacted once you leave the page. Make sure to copy and store your secret.

    The keys are used to authenticate to client-side SDKs.

    The keys are used to authenticate to server-side SDKs. With this key, server-side SDKs can download the entire flag ruleset for all flags in the environment.

    Server SDKs sync flag rulesets in the background and keep an in-memory cache.

    If your organization needs to rotate the keys, you can choose to add more than one key for the same environment.

    The SDK keys with the secret are created.
  5. Copy and store your secret.
    Keys are visible right after the creation and redacted once you leave the page. Make sure to copy and store your secret.

Step 4: Create a Boolean Flag Type

Harness Feature Flags support Boolean and Multivariate flag type. This quickstart uses Boolean flag type. A Boolean flag typically has two variations true or false.

Here is a quick visual summary of the steps involved:

Perform the following steps to create a boolean flag type:

  1. In Feature Flags, click Flag.
  2. Select the Boolean type.
  3. In About the Flag, in Name, enter a name for your boolean flag and click Next.

    When you name a feature flag, Harness automatically generates its identifier. You can edit the Identifier when you are creating the feature flag, but not after it is saved. If you rename the feature flag, the Identifier remains the same. For more information, see Entity Identifier Reference.
    If you need to make the feature flag a permanent flag, select the checkbox This is a permanent flag.
  4. In Variation settings, do the following:
    1. Select the flag type: In Flag Type, select Boolean.
    2. Define the variation: In boolean, you can have only two variations true or false.
      1. Enter a name for your variations. For example, True and False.
    3. Define rules for the flag: Defines which variation you will see by default when the flag is ON or OFF. Once you save the variations, a flag is created for the environment with these variations set as ON and OFF.
      For example:
      - If the flag is ON, serve the variation True.
      - If the flag is OFF, serve the variation False.
  5. Click Save and Close. The feature flag is created. By default, the feature flag is set to OFF.

Once you have created your flag type, optionally you can manage targets and modify the variationsrules, and add prerequisites of your flag.

Step 5: Use Harness Feature Flags SDKs with Java Applications

In a nutshell, here is how the server-side SDK works:

  1. The client authenticates with a server using an API Key.
  2. Configuration is fetched and cached in the memory.
    1. One call to fetch all Feature Flag configurations for the environment.
    2. One call to fetch all Target Group configurations for the environment.
  3. SDK maintains all the feature flag details locally in its cache and evaluates flags based on it. The SDKs use streaming and 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.

  4. All the evaluations are run against the cached data.

Set Up Your Application

You need 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.
  3. 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 quickstart uses 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.
  4. 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());
  5. 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();
  6. 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

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

Test Your Flag

Verify flag configuration updates in your code. 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.

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