public final class LDClient extends java.lang.Object implements LDClientInterface
LDClient
for the lifetime of their application.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.
|
Modifier and Type | Method and 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.
|
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 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. |
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 |
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.
|
public LDClient(java.lang.String sdkKey)
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)
.
sdkKey
- the SDK key for your LaunchDarkly environmentjava.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 nullLDClient(String, LDConfig)
public LDClient(java.lang.String sdkKey, LDConfig config)
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.
sdkKey
- the SDK key for your LaunchDarkly environmentconfig
- a client configuration objectjava.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 nullLDClient(String, LDConfig)
public boolean isInitialized()
LDClientInterface
isInitialized
in interface LDClientInterface
public void track(java.lang.String eventName, LDUser user)
LDClientInterface
To add custom data to the event, use LDClientInterface.trackData(String, LDUser, LDValue)
.
track
in interface LDClientInterface
eventName
- the name of the eventuser
- the user that performed the eventpublic void trackData(java.lang.String eventName, LDUser user, LDValue data)
LDClientInterface
trackData
in interface LDClientInterface
eventName
- the name of the eventuser
- the user that performed the eventdata
- an LDValue
containing additional data associated with the eventpublic void trackMetric(java.lang.String eventName, LDUser user, LDValue data, double metricValue)
LDClientInterface
trackMetric
in interface LDClientInterface
eventName
- the name of the eventuser
- the user that performed the eventdata
- 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.public void identify(LDUser user)
LDClientInterface
identify
in interface LDClientInterface
user
- the user to registerpublic FeatureFlagsState allFlagsState(LDUser user, FlagsStateOption... options)
LDClientInterface
The most common use case for this method is to bootstrap a set of client-side feature flags from a back-end service.
allFlagsState
in interface LDClientInterface
user
- the end user requesting the feature flagsoptions
- optional FlagsStateOption
values affecting how the state is computed - for
instance, to filter the set of flags to only include the client-side-enabled onesFeatureFlagsState
object (will never be null; see FeatureFlagsState.isValid()
public boolean boolVariation(java.lang.String featureKey, LDUser user, boolean defaultValue)
LDClientInterface
boolVariation
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagdefaultValue
if the flag is disabled in the LaunchDarkly control panelpublic int intVariation(java.lang.String featureKey, LDUser user, int defaultValue)
LDClientInterface
If the flag variation has a numeric value that is not an integer, it is rounded toward zero (truncated).
intVariation
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagdefaultValue
if the flag is disabled in the LaunchDarkly control panelpublic double doubleVariation(java.lang.String featureKey, LDUser user, double defaultValue)
LDClientInterface
doubleVariation
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagdefaultValue
if the flag is disabled in the LaunchDarkly control panelpublic java.lang.String stringVariation(java.lang.String featureKey, LDUser user, java.lang.String defaultValue)
LDClientInterface
stringVariation
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagdefaultValue
if the flag is disabled in the LaunchDarkly control panelpublic LDValue jsonValueVariation(java.lang.String featureKey, LDUser user, LDValue defaultValue)
LDClientInterface
LDValue
value of a feature flag for a given user.jsonValueVariation
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagdefaultValue
if the flag is disabled in the LaunchDarkly control panel;
will never be a null reference, but may be LDValue.ofNull()
public EvaluationDetail<java.lang.Boolean> boolVariationDetail(java.lang.String featureKey, LDUser user, boolean defaultValue)
LDClientInterface
reason
property in the result will also be included in
analytics events, if you are capturing detailed event data for this flag.boolVariationDetail
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagEvaluationDetail
objectpublic EvaluationDetail<java.lang.Integer> intVariationDetail(java.lang.String featureKey, LDUser user, int defaultValue)
LDClientInterface
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).
intVariationDetail
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagEvaluationDetail
objectpublic EvaluationDetail<java.lang.Double> doubleVariationDetail(java.lang.String featureKey, LDUser user, double defaultValue)
LDClientInterface
reason
property in the result will also be included in
analytics events, if you are capturing detailed event data for this flag.doubleVariationDetail
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagEvaluationDetail
objectpublic EvaluationDetail<java.lang.String> stringVariationDetail(java.lang.String featureKey, LDUser user, java.lang.String defaultValue)
LDClientInterface
reason
property in the result will also be included in
analytics events, if you are capturing detailed event data for this flag.stringVariationDetail
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagEvaluationDetail
objectpublic EvaluationDetail<LDValue> jsonValueVariationDetail(java.lang.String featureKey, LDUser user, LDValue defaultValue)
LDClientInterface
LDValue
value of a feature flag for a given user.jsonValueVariationDetail
in interface LDClientInterface
featureKey
- the unique key for the feature flaguser
- the end user requesting the flagdefaultValue
- the default value of the flagEvaluationDetail
objectpublic boolean isFlagKnown(java.lang.String featureKey)
LDClientInterface
isFlagKnown
in interface LDClientInterface
featureKey
- the unique key for the feature flagpublic FlagTracker getFlagTracker()
LDClientInterface
The FlagTracker
contains methods for requesting notifications about feature flag changes using
an event listener model.
getFlagTracker
in interface LDClientInterface
FlagTracker
public DataStoreStatusProvider getDataStoreStatusProvider()
LDClientInterface
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.
getDataStoreStatusProvider
in interface LDClientInterface
DataStoreStatusProvider
public DataSourceStatusProvider getDataSourceStatusProvider()
LDClientInterface
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.
getDataSourceStatusProvider
in interface LDClientInterface
DataSourceStatusProvider
public void close() throws java.io.IOException
LDClientInterface
close
in interface LDClientInterface
close
in interface java.io.Closeable
close
in interface java.lang.AutoCloseable
java.io.IOException
- if an exception is thrown by one of the underlying network servicespublic void flush()
LDClientInterface
flush
in interface LDClientInterface
public boolean isOffline()
LDClientInterface
isOffline
in interface LDClientInterface
public java.lang.String secureModeHash(LDUser user)
LDClientInterface
secureModeHash
in interface LDClientInterface
user
- the user to be hashed along with the SDK keypublic void alias(LDUser user, LDUser previousUser)
LDClientInterface
alias
in interface LDClientInterface
user
- the newly identified user.previousUser
- the previously identified user.public java.lang.String version()
version
in interface LDClientInterface