com.launchdarkly.client

Class LDClient

java.lang.Object

com.launchdarkly.client.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
java.util.Map<java.lang.String,com.google.gson.JsonElement>	allFlags(LDUser user) Returns a map from feature flag keys to JsonElement feature flag values for a given user.
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.
java.lang.Double	doubleVariation(java.lang.String featureKey, LDUser user, java.lang.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.
void	identify(LDUser user) Registers the user.
boolean	initialized()
java.lang.Integer	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	isOffline() Returns true if the client is in offline mode.
com.google.gson.JsonElement	jsonVariation(java.lang.String featureKey, LDUser user, com.google.gson.JsonElement defaultValue) Calculates the JsonElement value of a feature flag for a given user.
EvaluationDetail<com.google.gson.JsonElement>	jsonVariationDetail(java.lang.String featureKey, LDUser user, com.google.gson.JsonElement defaultValue) Calculates the value of a feature flag for a given user, and returns an object that describes the way the value was determined.
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	track(java.lang.String eventName, LDUser user, com.google.gson.JsonElement data) Tracks that a user performed an event.
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. In most cases, you should use this constructor.

Parameters:

sdkKey - the SDK key for your LaunchDarkly environment

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 client features, such as customizing the LaunchDarkly base URL.

Parameters:

sdkKey - the SDK key for your LaunchDarkly environment

config - a client configuration object

Method Detail

initialized

public boolean initialized()

Specified by:

initialized in interface LDClientInterface

track

public void track(java.lang.String eventName,
                  LDUser user,
                  com.google.gson.JsonElement data)

Description copied from interface: LDClientInterface

Tracks that a user performed an event.

Specified by:

track in interface LDClientInterface

Parameters:

eventName - the name of the event

user - the user that performed the event

data - a JSON object containing additional data associated with the event

track

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

Description copied from interface: LDClientInterface

Tracks that a user performed an event.

Specified by:

track in interface LDClientInterface

Parameters:

eventName - the name of the event

user - the user that performed the event

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

allFlags

public java.util.Map<java.lang.String,com.google.gson.JsonElement> allFlags(LDUser user)

Description copied from interface: LDClientInterface

Returns a map from feature flag keys to JsonElement feature flag values for a given user. If the result of a flag's evaluation would have returned the default variation, it will have a null entry in the map. If the client is offline, has not been initialized, or a null user or user with null/empty user key a null map will be returned. This method will 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:

allFlags in interface LDClientInterface

Parameters:

user - the end user requesting the feature flags

Returns:

a map from feature flag keys to JsonElement for the specified user

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 java.lang.Integer 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.

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 java.lang.Double doubleVariation(java.lang.String featureKey,
                                        LDUser user,
                                        java.lang.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

jsonVariation

public com.google.gson.JsonElement jsonVariation(java.lang.String featureKey,
                                                 LDUser user,
                                                 com.google.gson.JsonElement defaultValue)

Description copied from interface: LDClientInterface

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

Specified by:

jsonVariation 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

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.

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

jsonVariationDetail

public EvaluationDetail<com.google.gson.JsonElement> jsonVariationDetail(java.lang.String featureKey,
                                                                         LDUser user,
                                                                         com.google.gson.JsonElement 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:

jsonVariationDetail 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

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

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)