com.launchdarkly.client

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.

Method Summary

Modifier and Type	Method and Description
java.util.Map<java.lang.String,com.google.gson.JsonElement>	allFlags(LDUser user) Deprecated. Use allFlagsState(com.launchdarkly.client.LDUser, com.launchdarkly.client.FlagsStateOption...) instead. Current versions of the client-side SDK will not generate analytics events correctly if you pass the result of allFlags().
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() Tests whether the client is ready to be used.
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.
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.
com.google.gson.JsonElement	jsonVariation(java.lang.String featureKey, LDUser user, com.google.gson.JsonElement defaultValue) Deprecated. Use jsonValueVariation(String, LDUser, LDValue). Gson types may be removed from the public API in the future.
EvaluationDetail<com.google.gson.JsonElement>	jsonVariationDetail(java.lang.String featureKey, LDUser user, com.google.gson.JsonElement defaultValue) Deprecated. Use jsonValueVariationDetail(String, LDUser, LDValue). Gson types may be removed from the public API in the future.
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) Deprecated. Use trackData(String, LDUser, LDValue).
void	track(java.lang.String eventName, LDUser user, com.google.gson.JsonElement data, double metricValue) Deprecated. Use trackMetric(String, LDUser, LDValue, double).
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() The current version string of the SDK.

Method Detail

initialized

boolean initialized()

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,
           LDUser user)

Tracks that a user performed an event.

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

Parameters:

eventName - the name of the event

user - the user that performed the event

track

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

Deprecated. Use trackData(String, LDUser, LDValue).

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

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; may be null

trackData

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

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

Parameters:

eventName - the name of the event

user - the user that performed the event

data - an LDValue containing additional data associated with the event

Since:

4.8.0

track

@Deprecated
void track(java.lang.String eventName,
                       LDUser user,
                       com.google.gson.JsonElement data,
                       double metricValue)

Deprecated. Use trackMetric(String, LDUser, LDValue, double).

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

As of this version’s release date, the LaunchDarkly service does not support the metricValue parameter. As a result, calling this overload of track will not yet produce any different behavior from calling track(String, LDUser, JsonElement) without a metricValue. Refer to the SDK reference guide for the latest status.

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; may be null

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.

Since:

4.8.0

trackMetric

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.

As of this version’s release date, the LaunchDarkly service does not support the metricValue parameter. As a result, calling this overload of track will not yet produce any different behavior from calling trackData(String, LDUser, LDValue) without a metricValue. Refer to the SDK reference guide for the latest status.

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.

Since:

4.9.0

identify

void identify(LDUser user)

Registers the user.

Parameters:

user - the user to register

allFlags

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

Deprecated. Use allFlagsState(com.launchdarkly.client.LDUser, com.launchdarkly.client.FlagsStateOption...) instead. Current versions of the client-side SDK will not generate analytics events correctly if you pass the result of allFlags().

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.

Parameters:

user - the end user requesting the feature flags

Returns:

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

allFlagsState

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

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

Since:

4.3.0

boolVariation

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

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

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

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

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

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

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.

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

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.

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

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

Deprecated. Use jsonValueVariation(String, LDUser, LDValue). Gson types may be removed from the public API in the future.

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

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

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

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

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

Since:

4.8.0

boolVariationDetail

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. The reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

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

Since:

2.3.0

intVariationDetail

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

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

Since:

2.3.0

doubleVariationDetail

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. The reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

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

Since:

2.3.0

stringVariationDetail

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. The reason property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

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

Since:

2.3.0

jsonVariationDetail

@Deprecated
EvaluationDetail<com.google.gson.JsonElement> jsonVariationDetail(java.lang.String featureKey,
                                                                              LDUser user,
                                                                              com.google.gson.JsonElement defaultValue)

Deprecated. Use jsonValueVariationDetail(String, LDUser, LDValue). Gson types may be removed from the public API in the future.

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.

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

Since:

2.3.0

jsonValueVariationDetail

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

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

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

Since:

4.8.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

secureModeHash

java.lang.String secureModeHash(LDUser user)

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

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

java.lang.String version()

The current version string of the SDK.

Returns:

a string in Semantic Versioning 2.0.0 format