Java SDK reference

Read time: 3 minutes

Last edited: Oct 22, 2021

Overview

This reference guide documents all of the methods available in the Java SDK, and explains in detail how these methods work. LaunchDarkly's SDKs are open source. To learn more, read Java SDK GitHub repository or our Javadocs. You can also try this SDK out by cloning and running a sample application using this SDK and an example of running it in another JRE-based language such as Scala.

Android support

The Java SDK is intended for use in server environments only, and should not be used in mobile devices. Learn more about our client-side and server-side SDKs. If you want to use LaunchDarkly in an Android application, read the Android SDK reference.

Java compatibility

Version 5.0 and higher of the LaunchDarkly Java SDK is compatible with Java 8 and higher. Prior to version 5.0, the LaunchDarkly Java SDK also supported Java 7.

Getting started

After you complete the Getting Started process, follow these instructions to start using the LaunchDarkly SDK in your Java application.

The first step is to install the LaunchDarkly SDK as a dependency in your application using your application's dependency manager. Refer to the SDK releases page to identify the latest version.

In this example, it uses version 5.3.0:

1<dependency>
2  <groupId>com.launchdarkly</groupId>
3  <artifactId>launchdarkly-java-server-sdk</artifactId>
4  <version>5.3.0</version>
5</dependency>
6
7// or in Gradle:
8implementation group: 'com.launchdarkly', name: 'launchdarkly-java-server-sdk', version: '5.3.0'

Next, import the LaunchDarkly client in your application code.

1import com.launchdarkly.sdk.*;
2import com.launchdarkly.sdk.server.*;

Once the SDK is installed and imported, you'll want to create a single, shared instance of LDClient. You should specify your SDK key here so that your application will be authorized to connect to LaunchDarkly and for your application and environment.

Here's how:

1LDClient client = new LDClient("YOUR_SDK_KEY");

LDClient must be a singleton

It's important to make this a singleton. Internally, the client instance maintains internal state that allows us to serve feature flags without making any remote requests. Be sure that you're not instantiating a new client with every request.

Using client, you can check which variation a particular user should receive for a given feature flag:

1LDUser user = new LDUser("user@test.com");
2boolean showFeature = client.boolVariation("your.feature.key", user, false);
3if (showFeature) {
4  // application code to show the feature
5}
6else {
7  // the code to run if the feature is off
8}

Lastly, when your application is about to terminate, shut down client with close(). This ensures that the client releases any resources it is using, and that any pending analytics events are delivered to LaunchDarkly. If your application quits without this shutdown step, you may not see your requests and users on the dashboard, because they are derived from analytics events. This is something you only need to do once.

Here's how:

1// shut down the client, since we're about to quit
2client.close();

Using the Java SDK in OSGi

Versions 4.6.0 and higher of the SDK can be installed as OSGi bundles.

Note that the SDK's default jar—the one you get from Maven or Gradle if you do not specify a "classifier"—does not contain Gson or SLF4j, since applications are often built with their own specific versions of those libraries. Therefore, using that jar in OSGi requires Gson and SLF4j to be provided by some other bundle.

However, there is also a distribution that includes Gson and SLF4j as part of the SDK bundle. You can use this if you do not care about controlling the versions of those libraries separately. To do so, add the classifier "all":

1<!-- in Maven: -->
2<dependency>
3   <groupId>com.launchdarkly</groupId>
4   <artifactId>launchdarkly-java-server-sdk</artifactId>
5   <version>5.3.0</version>
6   <classifier>all</classifier>
7</dependency>
8
9// or in Gradle:
10"com.launchdarkly:launchdarkly-java-server-sdk:5.3.0:all"

Potential network connectivity issues caused by DNS caching

There is a potential problem for any Java application that communicates with a web service, if that service uses a load-balancing framework. LaunchDarkly is such a service. The issue is that if a service starts to use a different set of IP addresses, a Java application could continue trying to use an old IP address, causing connection attempts to fail. In most environments, this is unlikely to be a problem because IP addresses are not cached for very long.

However, Java has special behavior if the runtime environment has a security manager: in that case, it caches IP addresses indefinitely and will never update them until the application is restarted. If you are running in an environment that has a security manager—or if you're not sure whether that is the case—we recommend that you set the cache duration (TTL) explicitly. This page describes two ways to do so.

Lastly, shut down the client when your application terminates. To learn more, read Shutting down.

Supported features

This SDK supports the following features: