com.launchdarkly.sdk.android

Class LDClient

java.lang.Object

com.launchdarkly.sdk.android.LDClient

All Implemented Interfaces:

LDClientInterface, java.io.Closeable, java.lang.AutoCloseable

public class LDClient
extends java.lang.Object
implements LDClientInterface, java.io.Closeable

Client for accessing LaunchDarkly's Feature Flag system. This class enforces a singleton pattern. The main entry point is the init(Application, LDConfig, LDUser) method.

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	LDClient(android.app.Application application, LDConfig config)
protected	LDClient(android.app.Application application, LDConfig config, java.lang.String environmentName)

Method Summary

Modifier and Type	Method and Description
void	alias(LDUser user, LDUser previousUser) Alias associates two users for analytics purposes.
java.util.Map<java.lang.String,LDValue>	allFlags() Returns a map of all feature flags for the current user.
boolean	boolVariation(java.lang.String key, boolean defaultValue) Returns the flag value for the current user.
EvaluationDetail<java.lang.Boolean>	boolVariationDetail(java.lang.String key, boolean defaultValue) Returns the flag value for the current user, along with information about how it was calculated.
void	close() Closes the client.
double	doubleVariation(java.lang.String flagKey, double defaultValue) Returns the flag value for the current user.
EvaluationDetail<java.lang.Double>	doubleVariationDetail(java.lang.String flagKey, double defaultValue) Returns the flag value for the current user, along with information about how it was calculated.
void	flush() Sends all pending events to LaunchDarkly.
static LDClient	get()
ConnectionInformation	getConnectionInformation() Gets a ConnectionInformation object from the client representing the current state of the clients connection.
static LDClient	getForMobileKey(java.lang.String keyName)
java.lang.String	getVersion() Returns the version of the SDK, for instance "2.7.0".
java.util.concurrent.Future<java.lang.Void>	identify(LDUser user) Sets the current user, retrieves flags for that user, then sends an Identify Event to LaunchDarkly.
static java.util.concurrent.Future<LDClient>	init(android.app.Application application, LDConfig config, LDUser user) Initializes the singleton/primary instance.
static LDClient	init(android.app.Application application, LDConfig config, LDUser user, int startWaitSeconds) Initializes the singleton instance and blocks for up to startWaitSeconds seconds until the client has been initialized.
int	intVariation(java.lang.String key, int defaultValue) Returns the flag value for the current user.
EvaluationDetail<java.lang.Integer>	intVariationDetail(java.lang.String key, int defaultValue) Returns the flag value for the current user, along with information about how it was calculated.
boolean	isDisableBackgroundPolling() Checks whether LDConfig.Builder.disableBackgroundUpdating(boolean) was set to true in the configuration.
boolean	isInitialized() Checks whether the client is ready to return feature flag values.
boolean	isOffline() Checks whether the client has been put into offline mode.
LDValue	jsonValueVariation(java.lang.String key, LDValue defaultValue) Returns the flag value for the current user.
EvaluationDetail<LDValue>	jsonValueVariationDetail(java.lang.String key, LDValue defaultValue) Returns the flag value for the current user, along with information about how it was calculated.
void	registerAllFlagsListener(LDAllFlagsListener allFlagsListener) Registers a LDAllFlagsListener to be called when a flag update is processed by the SDK.
void	registerFeatureFlagListener(java.lang.String flagKey, FeatureFlagChangeListener listener) Registers a FeatureFlagChangeListener to be called when the flagKey changes from its current value.
void	registerStatusListener(LDStatusListener LDStatusListener) Registers a LDStatusListener to be called on connection status updates.
void	setOffline() Shuts down any network connections maintained by the client and puts the client in offline mode, preventing the client from opening new network connections until setOnline() is called.
void	setOnline() Restores network connectivity for the client, if the client was previously in offline mode.
java.lang.String	stringVariation(java.lang.String key, java.lang.String defaultValue) Returns the flag value for the current user.
EvaluationDetail<java.lang.String>	stringVariationDetail(java.lang.String key, java.lang.String defaultValue) Returns the flag value for the current user, along with information about how it was calculated.
void	track(java.lang.String eventName) Tracks that a user performed an event.
void	trackData(java.lang.String eventName, LDValue data) Tracks that a user performed an event, and provides additional custom data.
void	trackMetric(java.lang.String eventName, LDValue data, double metricValue) Tracks that a user performed an event, and provides an additional numeric value for custom metrics.
void	unregisterAllFlagsListener(LDAllFlagsListener allFlagsListener) Unregisters a LDAllFlagsListener so it will no longer be called on flag updates.
void	unregisterFeatureFlagListener(java.lang.String flagKey, FeatureFlagChangeListener listener) Unregisters a FeatureFlagChangeListener for the flagKey.
void	unregisterStatusListener(LDStatusListener LDStatusListener) Unregisters a LDStatusListener so it will no longer be called on connection status updates.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LDClient

protected LDClient(android.app.Application application,
                   @NonNull
                   LDConfig config)

LDClient

protected LDClient(android.app.Application application,
                   @NonNull
                   LDConfig config,
                   java.lang.String environmentName)

Method Detail

init

public static java.util.concurrent.Future<LDClient> init(@NonNull
                                                         android.app.Application application,
                                                         @NonNull
                                                         LDConfig config,
                                                         @NonNull
                                                         LDUser user)

Initializes the singleton/primary instance. The result is a Future which will complete once the client has been initialized with the latest feature flag values. For immediate access to the Client (possibly with out of date feature flags), it is safe to ignore the return value of this method, and afterward call get()

If the client has already been initialized, is configured for offline mode, or the device is not connected to the internet, this method will return a Future that is already in the completed state.

Parameters:

application - Your Android application.

config - Configuration used to set up the client

user - The user used in evaluating feature flags

Returns:

a Future which will complete once the client has been initialized.

init

public static LDClient init(android.app.Application application,
                            LDConfig config,
                            LDUser user,
                            int startWaitSeconds)

Initializes the singleton instance and blocks for up to startWaitSeconds seconds until the client has been initialized. If the client does not initialize within startWaitSeconds seconds, it is returned anyway and can be used, but may not have fetched the most recent feature flag values.

Parameters:

application - Your Android application.

config - Configuration used to set up the client

user - The user used in evaluating feature flags

startWaitSeconds - Maximum number of seconds to wait for the client to initialize

Returns:

The primary LDClient instance

get

public static LDClient get()
                    throws LaunchDarklyException

Returns:

the singleton instance.

Throws:

LaunchDarklyException - if init(Application, LDConfig, LDUser) has not been called.

getForMobileKey

public static LDClient getForMobileKey(java.lang.String keyName)
                                throws LaunchDarklyException

Parameters:

keyName - The name to lookup the instance by.

Returns:

the singleton instance for the environment associated with the given name.

Throws:

LaunchDarklyException - if init(Application, LDConfig, LDUser) has not been called.

trackMetric

public void trackMetric(java.lang.String eventName,
                        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 interface LDClientInterface

Parameters:

eventName - the name of 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. This field will also be returned as part of the custom event for Data Export.

trackData

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

Description copied from interface: LDClientInterface

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

Specified by:

trackData in interface LDClientInterface

Parameters:

eventName - the name of the event

data - an LDValue containing additional data associated with the event

track

public void track(java.lang.String eventName)

Description copied from interface: LDClientInterface

Tracks that a user performed an event.

Specified by:

track in interface LDClientInterface

Parameters:

eventName - the name of the event

identify

public java.util.concurrent.Future<java.lang.Void> identify(LDUser user)

Description copied from interface: LDClientInterface

Sets the current user, retrieves flags for that user, then sends an Identify Event to LaunchDarkly. The 5 most recent users' flag settings are kept locally.

Specified by:

identify in interface LDClientInterface

Parameters:

user - The user for evaluation and event reporting

Returns:

Future whose success indicates this user's flag settings have been stored locally and are ready for evaluation.

allFlags

public java.util.Map<java.lang.String,LDValue> allFlags()

Description copied from interface: LDClientInterface

Returns a map of all feature flags for the current user. No events are sent to LaunchDarkly.

Specified by:

allFlags in interface LDClientInterface

Returns:

a map of all feature flags

boolVariation

public boolean boolVariation(@NonNull
                             java.lang.String key,
                             boolean defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user. Returns defaultValue when one of the following occurs:

1. Flag is missing
2. The flag is not of a boolean type
3. Any other error

Specified by:

boolVariation in interface LDClientInterface

Parameters:

key - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag

Returns:

value of the flag or the default value

boolVariationDetail

public EvaluationDetail<java.lang.Boolean> boolVariationDetail(@NonNull
                                                               java.lang.String key,
                                                               boolean defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user, along with information about how it was calculated. Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

Specified by:

boolVariationDetail in interface LDClientInterface

Parameters:

key - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag (see LDClientInterface.boolVariation(String, boolean))

Returns:

an EvaluationDetail object containing the value and other information.

intVariation

public int intVariation(@NonNull
                        java.lang.String key,
                        int defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user. Returns defaultValue when one of the following occurs:

1. Flag is missing
2. The flag is not of a numeric type
3. Any other error

Specified by:

intVariation in interface LDClientInterface

Parameters:

key - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag

Returns:

value of the flag or the default value

intVariationDetail

public EvaluationDetail<java.lang.Integer> intVariationDetail(@NonNull
                                                              java.lang.String key,
                                                              int defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user, along with information about how it was calculated. Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

Specified by:

intVariationDetail in interface LDClientInterface

Parameters:

key - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag (see LDClientInterface.intVariation(String, int))

Returns:

an EvaluationDetail object containing the value and other information.

doubleVariation

public double doubleVariation(java.lang.String flagKey,
                              double defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user. Returns defaultValue when one of the following occurs:

1. Flag is missing
2. The flag is not of a numeric type
3. Any other error

Specified by:

doubleVariation in interface LDClientInterface

Parameters:

flagKey - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag

Returns:

value of the flag or the default value

doubleVariationDetail

public EvaluationDetail<java.lang.Double> doubleVariationDetail(java.lang.String flagKey,
                                                                double defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user, along with information about how it was calculated. Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

Specified by:

doubleVariationDetail in interface LDClientInterface

Parameters:

flagKey - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag (see LDClientInterface.doubleVariation(String, double))

Returns:

an EvaluationDetail object containing the value and other information.

stringVariation

public java.lang.String stringVariation(@NonNull
                                        java.lang.String key,
                                        java.lang.String defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user. Returns default when one of the following occurs:

1. Flag is missing
2. The flag is not of a string type
3. Any other error

Specified by:

stringVariation in interface LDClientInterface

Parameters:

key - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag

Returns:

value of the flag or the default value

stringVariationDetail

public EvaluationDetail<java.lang.String> stringVariationDetail(@NonNull
                                                                java.lang.String key,
                                                                java.lang.String defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user, along with information about how it was calculated. Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

Specified by:

stringVariationDetail in interface LDClientInterface

Parameters:

key - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag (see LDClientInterface.stringVariation(String, String))

Returns:

an EvaluationDetail object containing the value and other information.

jsonValueVariation

public LDValue jsonValueVariation(@NonNull
                                  java.lang.String key,
                                  LDValue defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user. Returns defualtValue when one of the following occurs:

1. Flag is missing
2. Any other error

Specified by:

jsonValueVariation in interface LDClientInterface

Parameters:

key - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag

Returns:

value of the flag or the default value. Result will never be null, but may be LDValue#ofNull()

jsonValueVariationDetail

public EvaluationDetail<LDValue> jsonValueVariationDetail(@NonNull
                                                          java.lang.String key,
                                                          LDValue defaultValue)

Description copied from interface: LDClientInterface

Returns the flag value for the current user, along with information about how it was calculated. Note that this will only work if you have set evaluationReasons to true with LDConfig.Builder.evaluationReasons(boolean). Otherwise, the reason property of the result will be null.

Specified by:

jsonValueVariationDetail in interface LDClientInterface

Parameters:

key - key for the flag to evaluate

defaultValue - default value in case of errors evaluating the flag (see LDClientInterface.jsonValueVariation(String, LDValue))

Returns:

an EvaluationDetail object containing the value and other information.

close

public void close()
           throws java.io.IOException

Closes the client. This should only be called at the end of a client's lifecycle.

Specified by:

close in interface java.io.Closeable

Specified by:

close in interface java.lang.AutoCloseable

Throws:

java.io.IOException - declared by the Closeable interface, but will not be thrown by the client

flush

public void flush()

Description copied from interface: LDClientInterface

Sends all pending events to LaunchDarkly.

Specified by:

flush in interface LDClientInterface

isInitialized

public boolean isInitialized()

Description copied from interface: LDClientInterface

Checks whether the client is ready to return feature flag values. This is true if either the client has successfully connected to LaunchDarkly and received feature flags, or the client has been put into offline mode (in which case it will return only default flag values).

Specified by:

isInitialized in interface LDClientInterface

Returns:

true if the client is initialized or offline

isOffline

public boolean isOffline()

Description copied from interface: LDClientInterface

Checks whether the client has been put into offline mode. This is true only if LDClientInterface.setOffline() was called, or if the configuration had LDConfig.Builder.offline(boolean) set to true, not if the client is simply offline due to a loss of network connectivity.

Specified by:

isOffline in interface LDClientInterface

Returns:

true if the client is in offline mode

setOffline

public void setOffline()

Description copied from interface: LDClientInterface

Shuts down any network connections maintained by the client and puts the client in offline mode, preventing the client from opening new network connections until setOnline() is called.

Note: The client automatically monitors the device's network connectivity and app foreground status, so calling setOffline() or setOnline() is normally unnecessary in most situations.

Specified by:

setOffline in interface LDClientInterface

setOnline

public void setOnline()

Description copied from interface: LDClientInterface

Restores network connectivity for the client, if the client was previously in offline mode. This operation may be throttled if it is called too frequently.

Note: The client automatically monitors the device's network connectivity and app foreground status, so calling setOffline() or setOnline() is normally unnecessary in most situations.

Specified by:

setOnline in interface LDClientInterface

registerFeatureFlagListener

public void registerFeatureFlagListener(java.lang.String flagKey,
                                        FeatureFlagChangeListener listener)

Description copied from interface: LDClientInterface

Registers a FeatureFlagChangeListener to be called when the flagKey changes from its current value. If the feature flag is deleted, the listener will be unregistered.

Specified by:

registerFeatureFlagListener in interface LDClientInterface

Parameters:

flagKey - the flag key to attach the listener to

listener - the listener to attach to the flag key

See Also:

LDClientInterface.unregisterFeatureFlagListener(String, FeatureFlagChangeListener)

unregisterFeatureFlagListener

public void unregisterFeatureFlagListener(java.lang.String flagKey,
                                          FeatureFlagChangeListener listener)

Description copied from interface: LDClientInterface

Unregisters a FeatureFlagChangeListener for the flagKey.

Specified by:

unregisterFeatureFlagListener in interface LDClientInterface

Parameters:

flagKey - the flag key to remove the listener from

listener - the listener to remove from the flag key

See Also:

LDClientInterface.registerFeatureFlagListener(String, FeatureFlagChangeListener)

isDisableBackgroundPolling

public boolean isDisableBackgroundPolling()

Description copied from interface: LDClientInterface

Checks whether LDConfig.Builder.disableBackgroundUpdating(boolean) was set to true in the configuration.

Specified by:

isDisableBackgroundPolling in interface LDClientInterface

Returns:

true if background polling is disabled

getConnectionInformation

public ConnectionInformation getConnectionInformation()

Description copied from interface: LDClientInterface

Gets a ConnectionInformation object from the client representing the current state of the clients connection.

Specified by:

getConnectionInformation in interface LDClientInterface

Returns:

An object representing the status of the connection to LaunchDarkly.

registerStatusListener

public void registerStatusListener(LDStatusListener LDStatusListener)

Description copied from interface: LDClientInterface

Registers a LDStatusListener to be called on connection status updates.

Specified by:

registerStatusListener in interface LDClientInterface

Parameters:

LDStatusListener - the listener to be called on a connection status update

unregisterStatusListener

public void unregisterStatusListener(LDStatusListener LDStatusListener)

Description copied from interface: LDClientInterface

Unregisters a LDStatusListener so it will no longer be called on connection status updates.

Specified by:

unregisterStatusListener in interface LDClientInterface

Parameters:

LDStatusListener - the listener to be removed

registerAllFlagsListener

public void registerAllFlagsListener(LDAllFlagsListener allFlagsListener)

Description copied from interface: LDClientInterface

Registers a LDAllFlagsListener to be called when a flag update is processed by the SDK.

Specified by:

registerAllFlagsListener in interface LDClientInterface

Parameters:

allFlagsListener - the listener to be called with a list of flag keys on a flag update

unregisterAllFlagsListener

public void unregisterAllFlagsListener(LDAllFlagsListener allFlagsListener)

Description copied from interface: LDClientInterface

Unregisters a LDAllFlagsListener so it will no longer be called on flag updates.

Specified by:

unregisterAllFlagsListener in interface LDClientInterface

Parameters:

allFlagsListener - the listener to be removed

alias

public void alias(LDUser user,
                  LDUser previousUser)

Alias associates two users for analytics purposes.

Parameters:

user - The first user

previousUser - The second user

getVersion

public java.lang.String getVersion()

Description copied from interface: LDClientInterface

Returns the version of the SDK, for instance "2.7.0".

Specified by:

getVersion in interface LDClientInterface

Returns:

the version string