com.launchdarkly.sdk.server

Class LDClient

java.lang.Object

com.launchdarkly.sdk.server.LDClient

All Implemented Interfaces:

LDClientInterface, java.io.Closeable, java.lang.AutoCloseable

public final class LDClient
extends java.lang.Object
implements LDClientInterface

A client for the LaunchDarkly API. Client instances are thread-safe. Applications should instantiate a single LDClient for the lifetime of their application.

Constructor Summary

Constructors

Constructor and Description
LDClient(java.lang.String sdkKey) Creates a new client instance that connects to LaunchDarkly with the default configuration.
LDClient(java.lang.String sdkKey, LDConfig config) Creates a new client to connect to LaunchDarkly with a custom configuration.

Method Summary

Modifier and Type	Method and Description
void	alias(LDUser user, LDUser previousUser) Associates two users for analytics purposes.
FeatureFlagsState	allFlagsState(LDUser user, FlagsStateOption... options) Returns an object that encapsulates the state of all feature flags for a given user, including the flag values and also metadata that can be used on the front end.
boolean	boolVariation(java.lang.String featureKey, LDUser user, boolean defaultValue) Calculates the value of a feature flag for a given user.
EvaluationDetail<java.lang.Boolean>	boolVariationDetail(java.lang.String featureKey, LDUser user, boolean defaultValue) Calculates the value of a feature flag for a given user, and returns an object that describes the way the value was determined.
void	close() Closes the LaunchDarkly client event processing thread.
double	doubleVariation(java.lang.String featureKey, LDUser user, double defaultValue) Calculates the floating point numeric value of a feature flag for a given user.
EvaluationDetail<java.lang.Double>	doubleVariationDetail(java.lang.String featureKey, LDUser user, double defaultValue) Calculates the value of a feature flag for a given user, and returns an object that describes the way the value was determined.
void	flush() Flushes all pending events.
DataSourceStatusProvider	getDataSourceStatusProvider() Returns an interface for tracking the status of the data source.
DataStoreStatusProvider	getDataStoreStatusProvider() Returns an interface for tracking the status of a persistent data store.
FlagTracker	getFlagTracker() Returns an interface for tracking changes in feature flag configurations.
void	identify(LDUser user) Registers the user.
int	intVariation(java.lang.String featureKey, LDUser user, int defaultValue) Calculates the integer value of a feature flag for a given user.
EvaluationDetail<java.lang.Integer>	intVariationDetail(java.lang.String featureKey, LDUser user, int defaultValue) Calculates the value of a feature flag for a given user, and returns an object that describes the way the value was determined.
boolean	isFlagKnown(java.lang.String featureKey) Returns true if the specified feature flag currently exists.
boolean	isInitialized() Tests whether the client is ready to be used.
boolean	isOffline() Returns true if the client is in offline mode.
LDValue	jsonValueVariation(java.lang.String featureKey, LDUser user, LDValue defaultValue) Calculates the LDValue value of a feature flag for a given user.
EvaluationDetail<LDValue>	jsonValueVariationDetail(java.lang.String featureKey, LDUser user, LDValue defaultValue) Calculates the LDValue value of a feature flag for a given user.
java.lang.String	secureModeHash(LDUser user) For more info: https://github.com/launchdarkly/js-client#secure-mode
java.lang.String	stringVariation(java.lang.String featureKey, LDUser user, java.lang.String defaultValue) Calculates the String value of a feature flag for a given user.
EvaluationDetail<java.lang.String>	stringVariationDetail(java.lang.String featureKey, LDUser user, java.lang.String defaultValue) Calculates the value of a feature flag for a given user, and returns an object that describes the way the value was determined.
void	track(java.lang.String eventName, LDUser user) Tracks that a user performed an event.
void	trackData(java.lang.String eventName, LDUser user, LDValue data) Tracks that a user performed an event, and provides additional custom data.
void	trackMetric(java.lang.String eventName, LDUser user, LDValue data, double metricValue) Tracks that a user performed an event, and provides an additional numeric value for custom metrics.
java.lang.String	version() Returns the current version string of the client library.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LDClient

public LDClient(java.lang.String sdkKey)

Creates a new client instance that connects to LaunchDarkly with the default configuration.

If you need to specify any custom SDK options, use LDClient(String, LDConfig) instead.

Applications should instantiate a single instance for the lifetime of the application. In unusual cases where an application needs to evaluate feature flags from different LaunchDarkly projects or environments, you may create multiple clients, but they should still be retained for the lifetime of the application rather than created per request or per thread.

The client will begin attempting to connect to LaunchDarkly as soon as you call the constructor. The constructor will return when it successfully connects, or when the default timeout of 5 seconds expires, whichever comes first. If it has not succeeded in connecting when the timeout elapses, you will receive the client in an uninitialized state where feature flags will return default values; it will still continue trying to connect in the background. You can detect whether initialization has succeeded by calling isInitialized(). If you prefer to customize this behavior, use LDClient(String, LDConfig) instead.

Parameters:

sdkKey - the SDK key for your LaunchDarkly environment

See Also:

LDClient(String, LDConfig)

LDClient

public LDClient(java.lang.String sdkKey,
                LDConfig config)

Creates a new client to connect to LaunchDarkly with a custom configuration.

This constructor can be used to configure advanced SDK features; see LDConfig.Builder.

Applications should instantiate a single instance for the lifetime of the application. In unusual cases where an application needs to evaluate feature flags from different LaunchDarkly projects or environments, you may create multiple clients, but they should still be retained for the lifetime of the application rather than created per request or per thread.

Unless it is configured to be offline with LDConfig.Builder.offline(boolean) or Components.externalUpdatesOnly(), the client will begin attempting to connect to LaunchDarkly as soon as you call the constructor. The constructor will return when it successfully connects, or when the timeout set by LDConfig.Builder.startWait(java.time.Duration) (default: 5 seconds) expires, whichever comes first. If it has not succeeded in connecting when the timeout elapses, you will receive the client in an uninitialized state where feature flags will return default values; it will still continue trying to connect in the background. You can detect whether initialization has succeeded by calling isInitialized().

If you prefer to have the constructor return immediately, and then wait for initialization to finish at some other point, you can use getDataSourceStatusProvider() as follows:

     LDConfig config = new LDConfig.Builder()
         .startWait(Duration.ZERO)
         .build();
     LDClient client = new LDClient(sdkKey, config);
     
     // later, when you want to wait for initialization to finish:
     boolean inited = client.getDataSourceStatusProvider().waitFor(
         DataSourceStatusProvider.State.VALID, Duration.ofSeconds(10));
     if (!inited) {
         // do whatever is appropriate if initialization has timed out
     }
 

Parameters:

sdkKey - the SDK key for your LaunchDarkly environment

config - a client configuration object

See Also:

LDClient(String, LDConfig)

Method Detail

isInitialized

public boolean isInitialized()

Description copied from interface: LDClientInterface

Tests whether the client is ready to be used.

Specified by:

isInitialized in interface LDClientInterface

Returns:

true if the client is ready, or false if it is still initializing

track

public void track(java.lang.String eventName,
                  LDUser user)

Description copied from interface: LDClientInterface

Tracks that a user performed an event.

To add custom data to the event, use LDClientInterface.trackData(String, LDUser, LDValue).

Specified by:

track in interface LDClientInterface

Parameters:

eventName - the name of the event

user - the user that performed the event

trackData

public void trackData(java.lang.String eventName,
                      LDUser user,
                      LDValue data)

Description copied from interface: LDClientInterface

Tracks that a user performed an event, and provides additional custom data.

Specified by:

trackData in interface LDClientInterface

Parameters:

eventName - the name of the event

user - the user that performed the event

data - an LDValue containing additional data associated with the event

trackMetric

public void trackMetric(java.lang.String eventName,
                        LDUser user,
                        LDValue data,
                        double metricValue)

Description copied from interface: LDClientInterface

Tracks that a user performed an event, and provides an additional numeric value for custom metrics.

Specified by:

trackMetric in interface LDClientInterface

Parameters:

eventName - the name of the event

user - the user that performed the event

data - an LDValue containing additional data associated with the event; if not applicable, you may pass either null or LDValue.ofNull()

metricValue - a numeric value used by the LaunchDarkly experimentation feature in numeric custom metrics. Can be omitted if this event is used by only non-numeric metrics. This field will also be returned as part of the custom event for Data Export.

identify

public void identify(LDUser user)

Description copied from interface: LDClientInterface

Registers the user.

Specified by:

identify in interface LDClientInterface

Parameters:

user - the user to register

allFlagsState

public FeatureFlagsState allFlagsState(LDUser user,
                                       FlagsStateOption... options)

Description copied from interface: LDClientInterface

Returns an object that encapsulates the state of all feature flags for a given user, including the flag values and also metadata that can be used on the front end. This method does not send analytics events back to LaunchDarkly.

The most common use case for this method is to bootstrap a set of client-side feature flags from a back-end service.

Specified by:

allFlagsState in interface LDClientInterface

Parameters:

user - the end user requesting the feature flags

options - optional FlagsStateOption values affecting how the state is computed - for instance, to filter the set of flags to only include the client-side-enabled ones

Returns:

a FeatureFlagsState object (will never be null; see FeatureFlagsState.isValid()

boolVariation

public boolean boolVariation(java.lang.String featureKey,
                             LDUser user,
                             boolean defaultValue)

Description copied from interface: LDClientInterface

Calculates the value of a feature flag for a given user.

Specified by:

boolVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

whether or not the flag should be enabled, or defaultValue if the flag is disabled in the LaunchDarkly control panel

intVariation

public int intVariation(java.lang.String featureKey,
                        LDUser user,
                        int defaultValue)

Description copied from interface: LDClientInterface

Calculates the integer value of a feature flag for a given user.

If the flag variation has a numeric value that is not an integer, it is rounded toward zero (truncated).

Specified by:

intVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

the variation for the given user, or defaultValue if the flag is disabled in the LaunchDarkly control panel

doubleVariation

public double doubleVariation(java.lang.String featureKey,
                              LDUser user,
                              double defaultValue)

Description copied from interface: LDClientInterface

Calculates the floating point numeric value of a feature flag for a given user.

Specified by:

doubleVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

the variation for the given user, or defaultValue if the flag is disabled in the LaunchDarkly control panel

stringVariation

public java.lang.String stringVariation(java.lang.String featureKey,
                                        LDUser user,
                                        java.lang.String defaultValue)

Description copied from interface: LDClientInterface

Calculates the String value of a feature flag for a given user.

Specified by:

stringVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

the variation for the given user, or defaultValue if the flag is disabled in the LaunchDarkly control panel

jsonValueVariation

public LDValue jsonValueVariation(java.lang.String featureKey,
                                  LDUser user,
                                  LDValue defaultValue)

Description copied from interface: LDClientInterface

Calculates the LDValue value of a feature flag for a given user.

Specified by:

jsonValueVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

the variation for the given user, or defaultValue if the flag is disabled in the LaunchDarkly control panel; will never be a null reference, but may be LDValue.ofNull()

boolVariationDetail

public EvaluationDetail<java.lang.Boolean> boolVariationDetail(java.lang.String featureKey,
                                                               LDUser user,
                                                               boolean defaultValue)

Description copied from interface: LDClientInterface

Calculates the value of a feature flag for a given user, and returns an object that describes the way the value was determined. The reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

Specified by:

boolVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

intVariationDetail

public EvaluationDetail<java.lang.Integer> intVariationDetail(java.lang.String featureKey,
                                                              LDUser user,
                                                              int defaultValue)

Description copied from interface: LDClientInterface

Calculates the value of a feature flag for a given user, and returns an object that describes the way the value was determined. The reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

If the flag variation has a numeric value that is not an integer, it is rounded toward zero (truncated).

Specified by:

intVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

doubleVariationDetail

public EvaluationDetail<java.lang.Double> doubleVariationDetail(java.lang.String featureKey,
                                                                LDUser user,
                                                                double defaultValue)

Description copied from interface: LDClientInterface

Calculates the value of a feature flag for a given user, and returns an object that describes the way the value was determined. The reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

Specified by:

doubleVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

stringVariationDetail

public EvaluationDetail<java.lang.String> stringVariationDetail(java.lang.String featureKey,
                                                                LDUser user,
                                                                java.lang.String defaultValue)

Description copied from interface: LDClientInterface

Calculates the value of a feature flag for a given user, and returns an object that describes the way the value was determined. The reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

Specified by:

stringVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

jsonValueVariationDetail

public EvaluationDetail<LDValue> jsonValueVariationDetail(java.lang.String featureKey,
                                                          LDUser user,
                                                          LDValue defaultValue)

Description copied from interface: LDClientInterface

Calculates the LDValue value of a feature flag for a given user.

Specified by:

jsonValueVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

user - the end user requesting the flag

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

isFlagKnown

public boolean isFlagKnown(java.lang.String featureKey)

Description copied from interface: LDClientInterface

Returns true if the specified feature flag currently exists.

Specified by:

isFlagKnown in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

Returns:

true if the flag exists

getFlagTracker

public FlagTracker getFlagTracker()

Description copied from interface: LDClientInterface

Returns an interface for tracking changes in feature flag configurations.

The FlagTracker contains methods for requesting notifications about feature flag changes using an event listener model.

Specified by:

getFlagTracker in interface LDClientInterface

Returns:

a FlagTracker

getDataStoreStatusProvider

public DataStoreStatusProvider getDataStoreStatusProvider()

Description copied from interface: LDClientInterface

Returns an interface for tracking the status of a persistent data store.

The DataStoreStatusProvider has methods for checking whether the data store is (as far as the SDK knows) currently operational, tracking changes in this status, and getting cache statistics. These are only relevant for a persistent data store; if you are using an in-memory data store, then this method will return a stub object that provides no information.

Specified by:

getDataStoreStatusProvider in interface LDClientInterface

Returns:

a DataStoreStatusProvider

getDataSourceStatusProvider

public DataSourceStatusProvider getDataSourceStatusProvider()

Description copied from interface: LDClientInterface

Returns an interface for tracking the status of the data source.

The data source is the mechanism that the SDK uses to get feature flag configurations, such as a streaming connection (the default) or poll requests. The DataSourceStatusProvider has methods for checking whether the data source is (as far as the SDK knows) currently operational and tracking changes in this status.

Specified by:

getDataSourceStatusProvider in interface LDClientInterface

Returns:

a DataSourceStatusProvider

close

public void close()
           throws java.io.IOException

Description copied from interface: LDClientInterface

Closes the LaunchDarkly client event processing thread. This should only be called on application shutdown.

Specified by:

close in interface LDClientInterface

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException - if an exception is thrown by one of the underlying network services

flush

public void flush()

Description copied from interface: LDClientInterface

Flushes all pending events.

Specified by:

flush in interface LDClientInterface

isOffline

public boolean isOffline()

Description copied from interface: LDClientInterface

Returns true if the client is in offline mode.

Specified by:

isOffline in interface LDClientInterface

Returns:

whether the client is in offline mode

secureModeHash

public java.lang.String secureModeHash(LDUser user)

Description copied from interface: LDClientInterface

For more info: https://github.com/launchdarkly/js-client#secure-mode

Specified by:

secureModeHash in interface LDClientInterface

Parameters:

user - the user to be hashed along with the SDK key

Returns:

the hash, or null if the hash could not be calculated

alias

public void alias(LDUser user,
                  LDUser previousUser)

Description copied from interface: LDClientInterface

Associates two users for analytics purposes. This can be helpful in the situation where a person is represented by multiple LaunchDarkly users. This may happen, for example, when a person initially logs into an application-- the person might be represented by an anonymous user prior to logging in and a different user after logging in, as denoted by a different user key.

Specified by:

alias in interface LDClientInterface

Parameters:

user - the newly identified user.

previousUser - the previously identified user.

version

public java.lang.String version()

Returns the current version string of the client library.

Specified by:

version in interface LDClientInterface

Returns:

a version string conforming to Semantic Versioning (http://semver.org)