• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
    No results for ""
    EXPAND ALL

    EDIT ON GITHUB

    Java SDK reference

    Read time: 3 minutes
    Last edited: Apr 29, 2023
    Version 6 of the Java SDK replaces users with contexts

    A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users."

    Code samples on this page are from the two most recent SDK versions where they differ. To learn more about upgrading, read Java SDK 5.x to 6.0 migration guide and Best practices for upgrading users to contexts.

    Overview

    This topic documents how to get started with the Java SDK, and links to reference information on all of the supported features.

    SDK quick links

    LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and sample applications:

    ResourceLocation
    SDK API documentationSDK API docs
    GitHub repositoryjava-server-sdk
    Sample applicationsJava
    Scala
    Clojure
    You can also use this SDK with Kotlin
    Published moduleMaven
    For use in server-side applications only

    This SDK is intended for use in multi-user Java server applications. If you have an Android application and want to set up LaunchDarkly in a mobile, desktop, or embedded application, read the Android SDK reference.

    To learn more about LaunchDarkly's different SDK types, read Client-side and server-side SDKs.

    SDK version compatibility

    The LaunchDarkly Java SDK, version 5.0 and higher, 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.

    First, 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 6.0.0:

    <dependency>
    <groupId>com.launchdarkly</groupId>
    <artifactId>launchdarkly-java-server-sdk</artifactId>
    <version>6.0.0</version>
    </dependency>
    // or in Gradle:
    implementation group: 'com.launchdarkly', name: 'launchdarkly-java-server-sdk', version: '6.0.0'

    Next, import the LaunchDarkly client in your application code.

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

    After you install and import the SDK, create a single, shared instance of LDClient. Specify your SDK key here to authorize your application to connect to a particular environment within LaunchDarkly.

    Here's how:

    LDClient client = new LDClient("sdk-key-123abc");
    LDClient must be a singleton

    It's important to make LDClient a singleton for each LaunchDarkly project. The client instance maintains internal state that allows LaunchDarkly to serve feature flags without making any remote requests. Do not instantiate a new client with every request.

    If you have multiple LaunchDarkly projects, you can create one LDClient for each. In this situation, the clients operate independently. For example, they do not share a single connection to LaunchDarkly.

    You can use client to check which variation a particular context will receive for a given feature flag. To learn more, read Evaluating flags and Flag evaluation reasons. For more information about how contexts are specified, read User and context configuration.

    In the v6 example, the context key is the string "context-key-123abc". In the v5 example, the user key is the string "user-key-123abc":

    LDContext context = LDContext.builder("context-key-123abc")
    .name("Sandy")
    .build();
    boolean flagValue = client.boolVariation("flag-key-123abc", context, false);
    if (flagValue) {
    // Application code to show the feature
    }
    else {
    // The code to run if the feature is off
    }

    Using the Java SDK in OSGi

    You can install versions 4.6.0 and higher of the SDK as OSGi bundles.

    The SDK's default jar, which it gets from Maven or Gradle if you do not specify a "classifier," does not contain Gson or SLF4j because applications are often built with their own specific versions of those libraries. Using the default 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 need to control the versions of those libraries separately.

    To do so, add the classifier "all":

    <!-- in Maven -->
    <dependency>
    <groupId>com.launchdarkly</groupId>
    <artifactId>launchdarkly-java-server-sdk</artifactId>
    <version>6.0.0</version>
    <classifier>all</classifier>
    </dependency>
    <!-- or in Gradle -->
    "com.launchdarkly:launchdarkly-java-server-sdk:6.0.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, such as LaunchDarkly, that also uses a load-balancing framework. 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 doesn't 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. To learn how, read Setting the JVM TTL for DNS Name Lookups.

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

    Supported features

    This SDK supports the following features: