com.launchdarkly.sdk.server.interfaces

Interface LDClientInterface

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable

All Known Implementing Classes:

LDClient

public interface LDClientInterface
extends java.io.Closeable

This interface defines the public methods of LDClient.

Applications will normally interact directly with LDClient, and must use its constructor to initialize the SDK, but being able to refer to it indirectly via an interface may be helpful in test scenarios (mocking) or for some dependency injection frameworks.

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 key, LDContext context, boolean defaultValue) Calculates the boolean value of a feature flag for a given context.
EvaluationDetail<java.lang.Boolean>	boolVariationDetail(java.lang.String key, 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() Closes the LaunchDarkly client event processing thread.
double	doubleVariation(java.lang.String key, 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 key, 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 key, LDContext context, int defaultValue) Calculates the integer value of a feature flag for a given context.
EvaluationDetail<java.lang.Integer>	intVariationDetail(java.lang.String key, 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 key, 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 key, 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 key, 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 key, 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() The current version string of the SDK.

Method Detail

isInitialized

boolean isInitialized()

Tests whether the client is ready to be used.

Returns:

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

track

void track(java.lang.String eventName,
           LDContext context)

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 trackData(String, LDContext, LDValue) or trackMetric(String, LDContext, LDValue, double) instead.

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

Parameters:

eventName - the name of the event

context - the context associated with the event

Since:

6.0.0

See Also:

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

trackData

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

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 trackMetric(String, LDContext, LDValue, double) instead.

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

Parameters:

eventName - the name of the event

context - the context associated with the event

data - additional data associated with the event, if any

Since:

6.0.0

See Also:

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

trackMetric

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.

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 flush().

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

Since:

4.9.0

See Also:

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

trackMigration

void trackMigration(MigrationOpTracker tracker)

Track the details of a migration.

Parameters:

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

Since:

7.0.0

identify

void identify(LDContext context)

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 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 flush().

Parameters:

context - the context to register

Since:

6.0.0

allFlagsState

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.

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.

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

Since:

6.0.0

boolVariation

boolean boolVariation(java.lang.String key,
                      LDContext context,
                      boolean defaultValue)

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.

Parameters:

key - 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

Since:

6.0.0

intVariation

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

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.

Parameters:

key - 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

Since:

6.0.0

doubleVariation

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

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.

Parameters:

key - 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

Since:

6.0.0

stringVariation

java.lang.String stringVariation(java.lang.String key,
                                 LDContext context,
                                 java.lang.String defaultValue)

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.

Parameters:

key - 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

Since:

6.0.0

jsonValueVariation

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

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.

Parameters:

key - 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

Since:

6.0.0

boolVariationDetail

EvaluationDetail<java.lang.Boolean> boolVariationDetail(java.lang.String key,
                                                        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.

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 boolVariation(String, LDContext, boolean).

Parameters:

key - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

Since:

6.0.0

intVariationDetail

EvaluationDetail<java.lang.Integer> intVariationDetail(java.lang.String key,
                                                       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.

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 intVariation(String, LDContext, int).

Parameters:

key - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

Since:

6.0.0

doubleVariationDetail

EvaluationDetail<java.lang.Double> doubleVariationDetail(java.lang.String key,
                                                         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.

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 doubleVariation(String, LDContext, double).

Parameters:

key - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

Since:

6.0.0

stringVariationDetail

EvaluationDetail<java.lang.String> stringVariationDetail(java.lang.String key,
                                                         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.

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 stringVariation(String, LDContext, String).

Parameters:

key - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

Since:

6.0.0

jsonValueVariationDetail

EvaluationDetail<LDValue> jsonValueVariationDetail(java.lang.String key,
                                                   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.

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 jsonValueVariation(String, LDContext, LDValue).

Parameters:

key - the unique key for the feature flag

context - the evaluation context

defaultValue - the default value of the flag

Returns:

an EvaluationDetail object

Since:

6.0.0

migrationVariation

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

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.

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

Since:

7.0.0

isFlagKnown

boolean isFlagKnown(java.lang.String featureKey)

Returns true if the specified feature flag currently exists.

Parameters:

featureKey - the unique key for the feature flag

Returns:

true if the flag exists

close

void close()
    throws java.io.IOException

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

Specified by:

close in interface java.lang.AutoCloseable

Specified by:

close in interface java.io.Closeable

Throws:

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

flush

void flush()

Flushes all pending events.

isOffline

boolean isOffline()

Returns true if the client is in offline mode.

Returns:

whether the client is in offline mode

getFlagTracker

FlagTracker getFlagTracker()

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.

Returns:

a FlagTracker

Since:

5.0.0

getBigSegmentStoreStatusProvider

BigSegmentStoreStatusProvider getBigSegmentStoreStatusProvider()

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.

Returns:

a BigSegmentStoreStatusProvider

Since:

5.7.0

getDataSourceStatusProvider

DataSourceStatusProvider getDataSourceStatusProvider()

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.

Returns:

a DataSourceStatusProvider

Since:

5.0.0

getDataStoreStatusProvider

DataStoreStatusProvider getDataStoreStatusProvider()

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.

Returns:

a DataStoreStatusProvider

Since:

5.0.0

getLogger

LDLogger getLogger()

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.

Returns:

a LDLogger

Since:

7.0.0

secureModeHash

java.lang.String secureModeHash(LDContext context)

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

See Secure mode in the JavaScript SDK Reference.

Parameters:

context - the evaluation context

Returns:

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

Since:

6.0.0

version

java.lang.String version()

The current version string of the SDK.

Returns:

a string in Semantic Versioning 2.0.0 format