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 singleLDClient
for the lifetime of their application.
-
-
Constructor Summary
Constructors Constructor 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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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.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.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 theLDValue
value of a feature flag for a given user.EvaluationDetail<LDValue>
jsonValueVariationDetail(java.lang.String featureKey, LDUser user, LDValue defaultValue)
Calculates theLDValue
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-modejava.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.
-
-
-
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, useLDClient(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 keyjava.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)
orComponents.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 byLDConfig.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 callingisInitialized()
.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 aNullPointerException
. 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 environmentconfig
- 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 keyjava.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 interfaceLDClientInterface
- 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 interfaceLDClientInterface
- Parameters:
eventName
- the name of the eventuser
- 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 interfaceLDClientInterface
- Parameters:
eventName
- the name of the eventuser
- the user that performed the eventdata
- anLDValue
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 interfaceLDClientInterface
- Parameters:
eventName
- the name of the eventuser
- the user that performed the eventdata
- anLDValue
containing additional data associated with the event; if not applicable, you may pass eithernull
orLDValue.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 interfaceLDClientInterface
- 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 interfaceLDClientInterface
- Parameters:
user
- the end user requesting the feature flagsoptions
- optionalFlagsStateOption
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; seeFeatureFlagsState.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 interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flag- Returns:
- the variation for the given user, or
defaultValue
if there is an error fetching the variation or the flag doesn't exist
-
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 interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flag- Returns:
- the variation for the given user, or
defaultValue
if there is an error fetching the variation or the flag doesn't exist
-
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 interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flag- Returns:
- the variation for the given user, or
defaultValue
if there is an error fetching the variation or the flag doesn't exist
-
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 interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flag- Returns:
- the variation for the given user, or
defaultValue
if there is an error fetching the variation or the flag doesn't exist
-
jsonValueVariation
public LDValue jsonValueVariation(java.lang.String featureKey, LDUser user, LDValue defaultValue)
Description copied from interface:LDClientInterface
Calculates theLDValue
value of a feature flag for a given user.- Specified by:
jsonValueVariation
in interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flag- Returns:
- the variation for the given user, or
defaultValue
if there is an error fetching the variation or the flag doesn't exist; will never be a null reference, but may beLDValue.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. Thereason
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 interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- 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. Thereason
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 interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- 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. Thereason
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 interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- 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. Thereason
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 interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- 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 theLDValue
value of a feature flag for a given user.- Specified by:
jsonValueVariationDetail
in interfaceLDClientInterface
- Parameters:
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- 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 interfaceLDClientInterface
- 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 interfaceLDClientInterface
- 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 interfaceLDClientInterface
- 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 interfaceLDClientInterface
- 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 interfaceLDClientInterface
- 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 interfacejava.lang.AutoCloseable
- Specified by:
close
in interfacejava.io.Closeable
- Specified by:
close
in interfaceLDClientInterface
- 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 interfaceLDClientInterface
-
isOffline
public boolean isOffline()
Description copied from interface:LDClientInterface
Returns true if the client is in offline mode.- Specified by:
isOffline
in interfaceLDClientInterface
- 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 interfaceLDClientInterface
- 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 interfaceLDClientInterface
- 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 interfaceLDClientInterface
- Returns:
- a version string conforming to Semantic Versioning (http://semver.org)
-
-