Unleash Client SDK for Java

Unleash is a private, secure, and scalable feature management platform built to reduce the risk of releasing new features and accelerate software development. This server-side Java SDK is designed to help you integrate with Unleash and evaluate feature flags inside your application.

You can use this client with Unleash Enterprise or Unleash Open Source.

Migration guides

• Migrating to v10
• Migrating to v11
• Migrating to v12

For ongoing updates, prefer v12. The latest patch releases of v10, v11, and v12 are currently aligned on the same optimized implementation path.

Java Version Compatibility

As of version 11, this library requires Java 11 or newer.

• Java 8+ is supported on versions 10.2.x and below

• Java 11+ is required starting from version 11 of the SDK

If you're using Java 8, please pin your dependency to 10.2.2 or earlier.

Getting started

This section shows you how to get started quickly and explains some common configuration scenarios. For a full overview of Unleash configuration options, check out the Configuration options section.

Step 1: Install the Unleash Java SDK

You need to add the Unleash SDK as a dependency for your project. Here's how you would add it to your pom.xml and build.gradle file:

pom.xml

<dependency>
    <groupId>io.getunleash</groupId>
    <artifactId>unleash-client-java</artifactId>
    <version>Latest version here</version>
</dependency>

build.gradle

 implementation("io.getunleash:unleash-client-java:$unleashedVersion")

Step 2: Create a new Unleash instance

---

⚠️ Important: In almost every case, you only want a single, shared instance of the Unleash class (a singleton) in your application. You would typically use a dependency injection framework (such as Spring or Guice) to inject it where you need it. Having multiple instances of the client in your application could lead to inconsistencies and performance degradation.

To help you detect cases where you configure multiple instances by mistake, the SDK will print an error message if you create multiple instances with the same configuration values. You can also tell Unleash to fail when this happens by setting the constructor parameter failOnMultipleInstantiations to true.

---

When instantiating an Unleash client, you can choose to do it either synchronously or asynchronously: The SDK will synchronize with the Unleash API on initialization, so it can take a few hundred milliseconds for the client to reach the correct state. This is usually not an issue and Unleash will do this in the background as soon as you initialize it. However, if it's important that you not continue execution until the SDK has synchronized, then you should use the synchronousFetchOnInitialisation option to block the client until it has successfully synchronized with the server.

Example configurations

💡 Tip: Refer to the section on configuration options for a more complete explanation of all the options.

Here's two examples of how you might initialize the Unleash SDK in your applications. The examples use dummy values and are almost identical. The only difference is that the first example is asynchronous, while the second example is synchronous.

Asynchronous initialization example:

UnleashConfig config = UnleashConfig.builder()
        .appName("my.java-app")
        .instanceId("your-instance-1")
        .unleashAPI("<unleash-api-url>")
        .apiKey("<client-api-token>")
        .build();

Unleash unleash = new DefaultUnleash(config);

Synchronous initialization example:

UnleashConfig config = UnleashConfig.builder()
        .appName("my.java-app")
        .instanceId("your-instance-1")
        .unleashAPI("<unleash-api-url>")
        .apiKey("<client-api-token>")
        .synchronousFetchOnInitialisation(true)
        .build();

Unleash unleash = new DefaultUnleash(config);

Step 3: Use the feature toggle

With the SDK initialized, you can use the isEnabled method to check the state of your feature toggles. The method returns a boolean indicating whether a feature is enabled for the current request.

if(unleash.isEnabled("AwesomeFeature")) {
  //do some magic
} else {
  //do old boring stuff
}

The isEnabled method also accepts a second boolean argument. The SDK uses this as a fallback value if it can't find the feature you're trying to check. For example, if unleash.isEnabled("non-existing-toggle") returns false when "non-existing-toggle" doesn't exist, calling unleash.isEnabled("non-existing-toggle", true), will return true.

You can also provide an Unleash context to the isEnabled method. Refer to the Unleash context section for more information about using the Unleash context in the Java SDK.

Activation strategies

The Java client supports Unleash built-in activation strategies (such as default, userWithId, gradualRolloutRandom, gradualRolloutUserId, gradualRolloutSessionId, remoteAddress, and applicationHostname).

As of v10, these built-ins are evaluated by the embedded Yggdrasil engine and are not exposed as public Java strategy classes in this SDK.

Read more about the strategies in the activation strategies reference documentation.

Custom strategies

You may also specify and implement your own strategy. The specification must be registered in the Unleash UI and you must register the strategy implementation when you set up Unleash.

You can also provide a fallbackStrategy via UnleashConfig if the client receives a strategy name it does not recognize.

Strategy s1 = new MyAwesomeStrategy();
Strategy s2 = new MySuperAwesomeStrategy();
Unleash unleash = new DefaultUnleash(config, s1, s2);

Unleash context

In order to use some of the common activation strategies you must provide an Unleash context. This client SDK provides two ways of providing the Unleash context:

1. As part of the isEnabled call

This is the simplest and most explicit way of providing the Unleash context. You just add it as an argument to the isEnabled call.

UnleashContext context = UnleashContext.builder()
  .userId("user@mail.com").build();

unleash.isEnabled("someToggle", context);

2. Via an UnleashContextProvider

This is a more advanced approach, where you configure an Unleash context provider. With a context provider, you don't need to rebuild or pass the Unleash context to every unleash.isEnabled call.

The provider typically binds the context to the same thread as the request. If you use Spring, the UnleashContextProvider will typically be a request-scoped bean.

UnleashContextProvider contextProvider = new MyAwesomeContextProvider();

UnleashConfig config = new UnleashConfig.Builder()
            .appName("java-test")
            .instanceId("instance x")
            .unleashAPI("http://unleash.herokuapp.com/api/")
            .apiKey("<client-api-token>")
            .unleashContextProvider(contextProvider)
            .build();

Unleash unleash = new DefaultUnleash(config);

// Anywhere in the code unleash will get the unleash context from your registered provider.
unleash.isEnabled("someToggle");

Custom HTTP headers

If you want the client to send custom HTTP Headers with all requests to the Unleash API you can define that by setting them via the UnleashConfig.

UnleashConfig unleashConfig = UnleashConfig.builder()
                .appName("my-app")
                .instanceId("my-instance-1")
                .unleashAPI(unleashAPI)
                .apiKey("12312Random")
                .customHttpHeader("<name>", "<value>")
                .build();

Dynamic custom HTTP headers

If you need custom HTTP headers that change during the lifetime of the client, a provider can be defined via the UnleashConfig.

public class CustomHttpHeadersProviderImpl implements CustomHttpHeadersProvider {
    @Override
    public Map<String, String> getCustomHeaders() {
        String token = "Acquire or refresh token";
        return new HashMap() {{ put("Authorization", "Bearer "+token); }};
    }
}

CustomHttpHeadersProvider provider = new CustomHttpHeadersProviderImpl();

UnleashConfig unleashConfig = UnleashConfig.builder()
                .appName("my-app")
                .instanceId("my-instance-1")
                .unleashAPI(unleashAPI)
                .apiKey("API token")
                .customHttpHeadersProvider(provider)
                .build();

Subscriber API

Introduced in 3.2.2

Sometimes you want to know when Unleash updates internally. This can be achieved by registering a subscriber. An example on how to configure a custom subscriber is shown below. Have a look at UnleashSubscriber.java to get a complete overview of all methods you can override.

UnleashConfig unleashConfig = UnleashConfig.builder()
    .appName("my-app")
    .instanceId("my-instance-1")
    .unleashAPI(unleashAPI)
    .apiKey("API token")
    .subscriber(new UnleashSubscriber() {
        @Override
        public void onReady(UnleashReady ready) {
            System.out.println("Unleash is ready");
        }
        @Override
        public void togglesFetched(FeatureToggleResponse toggleResponse) {
            System.out.println("Fetch toggles with status: " + toggleResponse.getStatus());
        }

        @Override
        public void togglesBackedUp(ToggleCollection toggleCollection) {
            System.out.println("Backup stored.");
        }

    })
    .build();

Options

• appName - Required. Should be a unique name identifying the client application using Unleash.
• synchronousFetchOnInitialisation - Allows the user to specify that the Unleash client should do one synchronous fetch to the unleash-api at initialisation. This will slow down the initialisation (the client must wait for an HTTP response). If the unleash-api is unavailable the client will silently move on and assume the api will be available later.
• disablePolling - Stops the client from polling. If used without synchronousFetchOnInitialisation will cause the client to never fetch toggles from the unleash-api.
• fetchTogglesInterval - Sets the interval (in seconds) between each poll to the unleash-api. Set this to 0 to do a single fetch and then stop refreshing while the process lives.

HTTP Proxy with Authentication

The Unleash Java client uses HttpURLConnection as its HTTP client, which automatically recognizes common JVM proxy settings such as http.proxyHost and http.proxyPort. If your proxy does not require authentication, it works without additional configuration. However, if you have to use Basic Authentication, settings such as http.proxyUser and http.proxyPassword are not recognized by default. To enable Basic Authentication for an HTTP proxy, enable the following option on the configuration builder:

UnleashConfig config = UnleashConfig.builder()
    .appName("my-app")
    .unleashAPI("http://unleash.org")
    .apiKey("API token")
    .enableProxyAuthenticationByJvmProperties()
    .build();

Toggle fetcher

The Unleash Java client supports using your own toggle fetcher. The Config builder has been expanded to accept an io.getunleash.util.UnleashFeatureFetcherFactory which should be a Function<UnleashConfig, FeatureFetcher>. If you want to use OkHttp instead of HttpURLConnection you'll need a dependency on okhttp

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.10+</version>
</dependency>

Then you can change your config to

UnleashConfig config = UnleashConfig.builder()
    .appName("my-app")
    .unleashAPI("http://unleash.org")
    .apiKey("API token")
    .unleashFeatureFetcherFactory(OkHttpFeatureFetcher::new)
    .build();

This will then start using OkHttp instead of HttpURLConnection.

Metrics sender

The Unleash Java client supports using your own metrics sender. The Config builder has been expanded to accept a io.getunleash.util.MetricsSenderFactory which should be a Function<UnleashConfig, MetricsSender>.

If you want to use OkHttp instead of HttpURLConnection you'll need a dependency on okhttp

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>okhttp</artifactId>
    <version>4.10+</version>
</dependency>

Then you can change your config to

UnleashConfig config = UnleashConfig.builder()
    .appName("my-app")
    .unleashAPI("http://unleash.org")
    .customHttpHeader("Authorization", "API token")
    .unleashMetricsSenderFactory(OkHttpMetricsSender::new)
    .build();

This will then start using OkHttp instead of HttpURLConnection to send metrics.

Impact metrics

Impact metrics are lightweight, application