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
FeatureFlagsState	allFlagsState(LDContext context, FlagsStateOption... options) Returns an object that encapsulates the state of all feature flags for a given context, which can be passed to front-end code.
boolean	boolVariation(java.lang.String featureKey, LDContext context, boolean defaultValue) Calculates the boolean value of a feature flag for a given context.
EvaluationDetail<java.lang.Boolean>	boolVariationDetail(java.lang.String featureKey, LDContext context, boolean defaultValue) Calculates the boolean value of a feature flag for a given context, and returns an object that describes the way the value was determined.
void	close() Shuts down the client and releases any resources it is using.
double	doubleVariation(java.lang.String featureKey, LDContext context, double defaultValue) Calculates the floating-point numeric value of a feature flag for a given context.
EvaluationDetail<java.lang.Double>	doubleVariationDetail(java.lang.String featureKey, LDContext context, double defaultValue) Calculates the floating-point numeric value of a feature flag for a given context, and returns an object that describes the way the value was determined.
void	flush() Flushes all pending events.
BigSegmentStoreStatusProvider	getBigSegmentStoreStatusProvider() Returns an interface for tracking the status of the Big Segment store.
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.
LDLogger	getLogger() Returns the logger instance used by this SDK instance.
void	identify(LDContext context) Reports details about an evaluation context.
int	intVariation(java.lang.String featureKey, LDContext context, int defaultValue) Calculates the integer value of a feature flag for a given context.
EvaluationDetail<java.lang.Integer>	intVariationDetail(java.lang.String featureKey, LDContext context, int defaultValue) Calculates the integer numeric value of a feature flag for a given context, 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, LDContext context, LDValue defaultValue) Calculates the value of a feature flag for a given context as any JSON value type.
EvaluationDetail<LDValue>	jsonValueVariationDetail(java.lang.String featureKey, LDContext context, LDValue defaultValue) Calculates the value of a feature flag for a given context as any JSON value type, and returns an object that describes the way the value was determined.
MigrationVariation	migrationVariation(java.lang.String key, LDContext context, MigrationStage defaultStage) Returns the migration stage of the migration feature flag for the given evaluation context.
java.lang.String	secureModeHash(LDContext context) Creates a hash string that can be used by the JavaScript SDK to identify a context.
java.lang.String	stringVariation(java.lang.String featureKey, LDContext context, java.lang.String defaultValue) Calculates the string value of a feature flag for a given context.
EvaluationDetail<java.lang.String>	stringVariationDetail(java.lang.String featureKey, LDContext context, java.lang.String defaultValue) Calculates the string value of a feature flag for a given context, and returns an object that describes the way the value was determined.
void	track(java.lang.String eventName, LDContext context) Tracks that an application-defined event occurred.
void	trackData(java.lang.String eventName, LDContext context, LDValue data) Tracks that an application-defined event occurred.
void	trackMetric(java.lang.String eventName, LDContext context, LDValue data, double metricValue) Tracks that an application-defined event occurred, and provides an additional numeric value for custom metrics.
void	trackMigration(MigrationOpTracker tracker) Track the details of a migration.
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.

For rules regarding the throwing of unchecked exceptions for error conditions, see LDClient(String, LDConfig).

Parameters:

sdkKey - the SDK key for your LaunchDarkly environment

Throws:

java.lang.IllegalArgumentException - if a parameter contained a grossly malformed value; for security reasons, in case of an illegal SDK key, the exception message does not include the key

java.lang.NullPointerException - if a non-nullable parameter was null

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
     }
 

This constructor can throw unchecked exceptions if it is immediately apparent that the SDK cannot work with these parameters. For instance, if the SDK key contains a non-printable character that cannot be used in an HTTP header, it will throw an IllegalArgumentException since the SDK key is normally sent to LaunchDarkly in an HTTP header and no such value could possibly be valid. Similarly, a null value for a non-nullable parameter may throw a NullPointerException. The constructor will not throw an exception for any error condition that could only be detected after making a request to LaunchDarkly (such as an SDK key that is simply wrong despite being valid ASCII, so it is invalid but not illegal); those are logged and treated as an unsuccessful initialization, as described above.

Parameters:

sdkKey - the SDK key for your LaunchDarkly environment

config - a client configuration object

Throws:

java.lang.IllegalArgumentException - if a parameter contained a grossly malformed value; for security reasons, in case of an illegal SDK key, the exception message does not include the key

java.lang.NullPointerException - if a non-nullable parameter was null

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,
                  LDContext context)

Description copied from interface: LDClientInterface

Tracks that an application-defined event occurred.

This method creates a "custom" analytics event containing the specified event name (key) and context properties. You may attach arbitrary data or a metric value to the event by calling LDClientInterface.trackData(String, LDContext, LDValue) or LDClientInterface.trackMetric(String, LDContext, LDValue, double) instead.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see LDClientInterface.flush().

Specified by:

track in interface LDClientInterface

Parameters:

eventName - the name of the event

context - the context associated with the event

See Also:

LDClientInterface.trackData(String, LDContext, LDValue), LDClientInterface.trackMetric(String, LDContext, LDValue, double)

trackMigration

public void trackMigration(MigrationOpTracker tracker)

Description copied from interface: LDClientInterface

Track the details of a migration.

Specified by:

trackMigration in interface LDClientInterface

Parameters:

tracker - Migration tracker which was used to track details of the migration operation.

trackData

public void trackData(java.lang.String eventName,
                      LDContext context,
                      LDValue data)

Description copied from interface: LDClientInterface

Tracks that an application-defined event occurred.

This method creates a "custom" analytics event containing the specified event name (key), context properties, and optional data. If you do not need custom data, pass LDValue.ofNull() for the last parameter or simply omit the parameter. You may attach a metric value to the event by calling LDClientInterface.trackMetric(String, LDContext, LDValue, double) instead.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see LDClientInterface.flush().

Specified by:

trackData in interface LDClientInterface

Parameters:

eventName - the name of the event

context - the context associated with the event

data - additional data associated with the event, if any

See Also:

LDClientInterface.track(String, LDContext), LDClientInterface.trackMetric(String, LDContext, LDValue, double)

trackMetric

public void trackMetric(java.lang.String eventName,
                        LDContext context,
                        LDValue data,
                        double metricValue)

Description copied from interface: LDClientInterface

Tracks that an application-defined event occurred, and provides an additional numeric value for custom metrics.

This value is used by the LaunchDarkly experimentation feature in numeric custom metrics, and will also be returned as part of the custom event for Data Export.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see LDClientInterface.flush().

Specified by:

trackMetric in interface LDClientInterface

Parameters:

eventName - the name of the event

context - the context associated with 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

See Also:

LDClientInterface.track(String, LDContext), LDClientInterface.trackData(String, LDContext, LDValue)

identify

public void identify(LDContext context)

Description copied from interface: LDClientInterface

Reports details about an evaluation context.

This method simply creates an analytics event containing the context properties, to that LaunchDarkly will know about that context if it does not already.

Calling any evaluation method, such as LDClientInterface.boolVariation(String, LDContext, boolean), also sends the context information to LaunchDarkly (if events are enabled), so you only need to use this method if you want to identify the context without evaluating a flag.

Note that event delivery is asynchronous, so the event may not actually be sent until later; see LDClientInterface.flush().

Specified by:

identify in interface LDClientInterface

Parameters:

context - the context to register

allFlagsState

public FeatureFlagsState allFlagsState(LDContext context,
                                       FlagsStateOption... options)

Description copied from interface: LDClientInterface

Returns an object that encapsulates the state of all feature flags for a given context, which can be passed to front-end code.

The object returned by this method contains the flag values as well as other metadata that is used by the LaunchDarkly JavaScript client, so it can be used for bootstrapping.

This method will not send analytics events back to LaunchDarkly.

Specified by:

allFlagsState in interface LDClientInterface

Parameters:

context - the evaluation context

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,
                             LDContext context,
                             boolean defaultValue)

Description copied from interface: LDClientInterface

Calculates the boolean value of a feature flag for a given context.

If the flag variation does not have a boolean value, defaultValue is returned.

If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

Specified by:

boolVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

the variation for the given context, or defaultValue if the flag cannot be evaluated

intVariation

public int intVariation(java.lang.String featureKey,
                        LDContext context,
                        int defaultValue)

Description copied from interface: LDClientInterface

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

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

If the flag variation does not have a numeric value, defaultValue is returned.

If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

Specified by:

intVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

the variation for the given context, or defaultValue if the flag cannot be evaluated

doubleVariation

public double doubleVariation(java.lang.String featureKey,
                              LDContext context,
                              double defaultValue)

Description copied from interface: LDClientInterface

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

If the flag variation does not have a numeric value, defaultValue is returned.

If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

Specified by:

doubleVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

the variation for the given context, or defaultValue if the flag cannot be evaluated

stringVariation

public java.lang.String stringVariation(java.lang.String featureKey,
                                        LDContext context,
                                        java.lang.String defaultValue)

Description copied from interface: LDClientInterface

Calculates the string value of a feature flag for a given context.

If the flag variation does not have a string value, defaultValue is returned.

If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

Specified by:

stringVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

the variation for the given context, or defaultValue if the flag cannot be evaluated

jsonValueVariation

public LDValue jsonValueVariation(java.lang.String featureKey,
                                  LDContext context,
                                  LDValue defaultValue)

Description copied from interface: LDClientInterface

Calculates the value of a feature flag for a given context as any JSON value type.

The type LDValue is used to represent any of the value types that can exist in JSON. Use LDValue methods to examine its type and value.

Specified by:

jsonValueVariation in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

the variation for the given context, or defaultValue if the flag cannot be evaluated

boolVariationDetail

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

Description copied from interface: LDClientInterface

Calculates the boolean value of a feature flag for a given context, and returns an object that describes the way the value was determined.

The EvaluationDetail.getReason() property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to LDClientInterface.boolVariation(String, LDContext, boolean).

Specified by:

boolVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

intVariationDetail

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

Description copied from interface: LDClientInterface

Calculates the integer numeric value of a feature flag for a given context, and returns an object that describes the way the value was determined.

The EvaluationDetail.getReason() property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to LDClientInterface.intVariation(String, LDContext, int).

Specified by:

intVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

doubleVariationDetail

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

Description copied from interface: LDClientInterface

Calculates the floating-point numeric value of a feature flag for a given context, and returns an object that describes the way the value was determined.

The EvaluationDetail.getReason() property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to LDClientInterface.doubleVariation(String, LDContext, double).

Specified by:

doubleVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

stringVariationDetail

public EvaluationDetail<java.lang.String> stringVariationDetail(java.lang.String featureKey,
                                                                LDContext context,
                                                                java.lang.String defaultValue)

Description copied from interface: LDClientInterface

Calculates the string value of a feature flag for a given context, and returns an object that describes the way the value was determined.

The EvaluationDetail.getReason() property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to LDClientInterface.stringVariation(String, LDContext, String).

Specified by:

stringVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

jsonValueVariationDetail

public EvaluationDetail<LDValue> jsonValueVariationDetail(java.lang.String featureKey,
                                                          LDContext context,
                                                          LDValue defaultValue)

Description copied from interface: LDClientInterface

Calculates the value of a feature flag for a given context as any JSON value type, and returns an object that describes the way the value was determined.

The EvaluationDetail.getReason() property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

The behavior is otherwise identical to LDClientInterface.jsonValueVariation(String, LDContext, LDValue).

Specified by:

jsonValueVariationDetail in interface LDClientInterface

Parameters:

featureKey - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

migrationVariation

public MigrationVariation migrationVariation(java.lang.String key,
                                             LDContext context,
                                             MigrationStage defaultStage)

Description copied from interface: LDClientInterface

Returns the migration stage of the migration feature flag for the given evaluation context.

If the evaluated value of the flag cannot be converted to an LDMigrationStage, then the default value will be returned and error will be logged.

Specified by:

migrationVariation in interface LDClientInterface

Parameters:

key - the unique key for the feature flag

context - the evaluation context

defaultStage - the default stage of the migration

Returns:

the current stage and a tracker which can be used to track the migration operation

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

getBigSegmentStoreStatusProvider

public BigSegmentStoreStatusProvider getBigSegmentStoreStatusProvider()

Description copied from interface: LDClientInterface

Returns an interface for tracking the status of the Big Segment store.

The returned object has methods for checking whether the Big Segment store is (as far as the SDK knows) currently operational and tracking changes in this status. See BigSegmentStoreStatusProvider for more about this functionality.

Specified by:

getBigSegmentStoreStatusProvider in interface LDClientInterface

Returns:

a BigSegmentStoreStatusProvider

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

getLogger

public LDLogger getLogger()

Description copied from interface: LDClientInterface

Returns the logger instance used by this SDK instance.

This allows for access to the logger by other LaunchDarkly components, such as the Migration class.

It also allows for usage of the logger in wrapper implementations.

It is not intended for general purpose application logging.

Specified by:

getLogger in interface LDClientInterface

Returns:

a LDLogger

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

Shuts down the client and releases any resources it is using.

Unless it is offline, the client will attempt to deliver any pending analytics events before closing.

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(LDContext context)

Description copied from interface: LDClientInterface

Creates a hash string that can be used by the JavaScript SDK to identify a context.

See Secure mode in the JavaScript SDK Reference.

Specified by:

secureModeHash in interface LDClientInterface

Parameters:

context - the evaluation context

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)