OpenFeature Java Provider

Introduction

The OpenFeature Java Provider is intended to be used in combination with the OpenFeature Java SDK. The provider wraps the ConfigDirector Java SDK.

The minimum Java version supported is 17.

The provider is thread safe. Register one instance when your application starts, and shut OpenFeature down when it stops. Evaluations read config state the provider already holds in memory, so they make no network calls on the request path.

Installation

The provider can be installed from Maven Central: https://central.sonatype.com/artifact/com.configdirector/configdirector-openfeature-server-provider

The OpenFeature Java SDK and the ConfigDirector Java SDK are included as transitive dependencies.

dependencies {
    implementation("com.configdirector:configdirector-openfeature-server-provider:1.0.0")
}

dependencies {
    implementation 'com.configdirector:configdirector-openfeature-server-provider:1.0.0'
}

<dependency>
  <groupId>com.configdirector</groupId>
  <artifactId>configdirector-openfeature-server-provider</artifactId>
  <version>1.0.0</version>
</dependency>

Configure and initialize the client

1. Create an instance of the provider using your server SDK key. You can retrieve a server SDK key for each environment under SDK Keys in the dashboard's navigation panel.
2. Set the OpenFeature provider.
3. Get a client instance from OpenFeature.

import com.configdirector.openfeature.ConfigDirectorProvider;
import dev.openfeature.sdk.Client;
import dev.openfeature.sdk.OpenFeatureAPI;

OpenFeatureAPI api = OpenFeatureAPI.getInstance();
api.setProviderAndWait(new ConfigDirectorProvider("YOUR-SERVER-SDK-KEY"));
Client client = api.getClient();

setProviderAndWait blocks until the initial config state arrives or the configured timeout elapses, and it does not throw on a connection failure. Until config state arrives, evaluations return the default value with the PROVIDER_NOT_READY error code, and the provider continues to connect in the background.

Additional configuration options

Additional configuration options can be passed into the provider in the optional second argument of the constructor.

For example, the metadata can be provided like this:

import com.configdirector.openfeature.ConfigDirectorProvider;

ConfigDirectorProvider provider = new ConfigDirectorProvider(
    "YOUR-SERVER-SDK-KEY",
    options -> options.metadata("YOUR-APP-NAME", "1.0.2"));

The provider accepts the same configuration options as the Java SDK client, refer to the additional configuration options section of the Java SDK for a full list.

Shut down

Shutting OpenFeature down closes the provider, which closes its connections and reports any pending telemetry:

OpenFeatureAPI.getInstance().shutdown();

Retrieve config values

To retrieve config values, use the OpenFeature client:

boolean booleanValue = client.getBooleanValue("my-config-key", false);

String stringValue = client.getStringValue("my-string-config-key", "Default");

Each OpenFeature getter maps to a ConfigDirector config type:

For getObjectValue, the default value decides the expected shape: provide a structure for a JSON object, or a list for a JSON array.

import dev.openfeature.sdk.ImmutableStructure;
import dev.openfeature.sdk.Value;

Value settings = client.getObjectValue("my-json-config-key", new Value(new ImmutableStructure()));
String theme = settings.asStructure().getValue("theme").asString();

For additional information regarding the OpenFeature client refer to the OpenFeature Java SDK documentation.

Evaluation details

The detailed getters of the OpenFeature client, such as getBooleanDetails, report why an evaluation produced the value that it did:

When a value was found, the variant is ConfigDirector's identifier for that value. In every other case the default value is returned.

User context

import dev.openfeature.sdk.EvaluationContext;
import dev.openfeature.sdk.ImmutableContext;
import dev.openfeature.sdk.ImmutableStructure;
import dev.openfeature.sdk.Value;
import java.util.Map;

// Any arbitrary traits which can be referenced in targeting rules
ImmutableStructure traits = new ImmutableStructure(Map.of("region", new Value("North America")));

EvaluationContext context = new ImmutableContext(
    "12345", // In OpenFeature, the targeting key represents the context's user ID
    Map.of("name", new Value("Example User"), "traits", new Value(traits)));

boolean booleanValue = client.getBooleanValue("my-config-key", false, context);

The evaluation context maps onto the ConfigDirector user context as follows:

For additional information regarding the OpenFeature client refer to the OpenFeature Java SDK documentation.

Events

The provider emits PROVIDER_CONFIGURATION_CHANGED whenever configs are updated on the dashboard or via the admin API, carrying the keys of the configs in the update:

OpenFeatureAPI.getInstance().onProviderConfigurationChanged(
    details -> System.out.println("Configs updated: " + details.getFlagsChanged()));

It emits PROVIDER_READY when the initial config state arrives after setProviderAndWait has already returned.