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 |
---|---|
java.util.Map<java.lang.String,com.google.gson.JsonElement> |
allFlags(LDUser user)
Returns a map from feature flag keys to
JsonElement feature flag values for a given user. |
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)
Calculates the
JsonElement value of a feature flag for a given user. |
EvaluationDetail<com.google.gson.JsonElement> |
jsonVariationDetail(java.lang.String featureKey,
LDUser user,
com.google.gson.JsonElement defaultValue)
Calculates the value of a feature flag for a given user, and returns an object that describes the
way the value was determined.
|
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)
Tracks that a user performed an event, and provides additional custom data.
|
void |
track(java.lang.String eventName,
LDUser user,
com.google.gson.JsonElement data,
double metricValue)
Tracks that a user performed an event, and provides an additional numeric value for custom metrics.
|
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 initialized()
.
sdkKey
- the SDK key for your LaunchDarkly environmentLDClient(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
LDConfig.Builder.useLdd(boolean)
, 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.startWaitMillis(long)
(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 initialized()
.
sdkKey
- the SDK key for your LaunchDarkly environmentconfig
- a client configuration objectLDClient(String, LDConfig)
public boolean initialized()
LDClientInterface
initialized
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 track(java.lang.String eventName, LDUser user, com.google.gson.JsonElement data)
LDClientInterface
track
in interface LDClientInterface
eventName
- the name of the eventuser
- the user that performed the eventdata
- a JSON object containing additional data associated with the event; may be nullpublic void track(java.lang.String eventName, LDUser user, com.google.gson.JsonElement data, double metricValue)
LDClientInterface
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 LDClientInterface.track(String, LDUser, JsonElement)
without a metricValue
.
Refer to the SDK reference guide for the latest status.
track
in interface LDClientInterface
eventName
- the name of the eventuser
- the user that performed the eventdata
- a JSON object containing additional data associated with the event; may be nullmetricValue
- 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 trackMetric(java.lang.String eventName, LDUser user, LDValue data, double metricValue)
LDClientInterface
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 LDClientInterface.trackData(String, LDUser, LDValue)
without a metricValue
.
Refer to the SDK reference guide for the latest status.
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 java.util.Map<java.lang.String,com.google.gson.JsonElement> allFlags(LDUser user)
LDClientInterface
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.
allFlags
in interface LDClientInterface
user
- the end user requesting the feature flagsJsonElement
for the specified userpublic 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 java.lang.Integer 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 java.lang.Double doubleVariation(java.lang.String featureKey, LDUser user, java.lang.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 com.google.gson.JsonElement jsonVariation(java.lang.String featureKey, LDUser user, com.google.gson.JsonElement defaultValue)
LDClientInterface
JsonElement
value of a feature flag for a given user.jsonVariation
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<com.google.gson.JsonElement> jsonVariationDetail(java.lang.String featureKey, LDUser user, com.google.gson.JsonElement defaultValue)
LDClientInterface
reason
property in the result will also be included in
analytics events, if you are capturing detailed event data for this flag.jsonVariationDetail
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 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 java.lang.String version()
version
in interface LDClientInterface