Package com.launchdarkly.sdk.server

Class 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 single LDClient 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
      FeatureFlagsState allFlagsState​(LDContext context, FlagsStateOption... options)
      Returns an object that encapsulates the state of all feature flags for a given context, which can be passed to front-end code.
      boolean boolVariation​(java.lang.String featureKey, LDContext context, boolean defaultValue)
      Calculates the boolean value of a feature flag for a given context.
      EvaluationDetail<java.lang.Boolean> boolVariationDetail​(java.lang.String featureKey, LDContext context, boolean defaultValue)
      Calculates the boolean value of a feature flag for a given context, and returns an object that describes the way the value was determined.
      void close()
      Shuts down the client and releases any resources it is using.
      double doubleVariation​(java.lang.String featureKey, LDContext context, double defaultValue)
      Calculates the floating-point numeric value of a feature flag for a given context.
      EvaluationDetail<java.lang.Double> doubleVariationDetail​(java.lang.String featureKey, LDContext context, double defaultValue)
      Calculates the floating-point numeric value of a feature flag for a given context, 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.
      LDLogger getLogger()
      Returns the logger instance used by this SDK instance.
      void identify​(LDContext context)
      Reports details about an evaluation context.
      int intVariation​(java.lang.String featureKey, LDContext context, int defaultValue)
      Calculates the integer value of a feature flag for a given context.
      EvaluationDetail<java.lang.Integer> intVariationDetail​(java.lang.String featureKey, LDContext context, int defaultValue)
      Calculates the integer numeric value of a feature flag for a given context, 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, LDContext context, LDValue defaultValue)
      Calculates the value of a feature flag for a given context as any JSON value type.
      EvaluationDetail<LDValue> jsonValueVariationDetail​(java.lang.String featureKey, LDContext context, LDValue defaultValue)
      Calculates the value of a feature flag for a given context as any JSON value type, and returns an object that describes the way the value was determined.
      MigrationVariation migrationVariation​(java.lang.String key, LDContext context, MigrationStage defaultStage)
      Returns the migration stage of the migration feature flag for the given evaluation context.
      java.lang.String secureModeHash​(LDContext context)
      Creates a hash string that can be used by the JavaScript SDK to identify a context.
      java.lang.String stringVariation​(java.lang.String featureKey, LDContext context, java.lang.String defaultValue)
      Calculates the string value of a feature flag for a given context.
      EvaluationDetail<java.lang.String> stringVariationDetail​(java.lang.String featureKey, LDContext context, java.lang.String defaultValue)
      Calculates the string value of a feature flag for a given context, and returns an object that describes the way the value was determined.
      void track​(java.lang.String eventName, LDContext context)
      Tracks that an application-defined event occurred.
      void trackData​(java.lang.String eventName, LDContext context, LDValue data)
      Tracks that an application-defined event occurred.
      void trackMetric​(java.lang.String eventName, LDContext context, LDValue data, double metricValue)
      Tracks that an application-defined event occurred, and provides an additional numeric value for custom metrics.
      void trackMigration​(MigrationOpTracker tracker)
      Track the details of a migration.
      java.lang.String version()
      Returns the current version string of the client library.

      • Methods inherited from class java.lang.Object

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

    • 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, use LDClient(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 key
        java.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) 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.

        Parameters:
        sdkKey - the SDK key for your LaunchDarkly environment
        config - 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 key
        java.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 interface LDClientInterface
        Returns:
        true if the client is ready, or false if it is still initializing

      • trackMetric

        public void trackMetric​(java.lang.String eventName,
                        LDContext context,
                        LDValue data,
                        double metricValue)
        Description copied from interface: LDClientInterface
        Tracks that an application-defined event occurred, and provides an additional numeric value for custom metrics.

        This value is used by the LaunchDarkly experimentation feature in numeric custom metrics, and will also be returned as part of the custom event for Data Export.

        Note that event delivery is asynchronous, so the event may not actually be sent until later; see LDClientInterface.flush().

        Specified by:
        trackMetric in interface LDClientInterface
        Parameters:
        eventName - the name of the event
        context - the context associated with 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
        See Also:
        LDClientInterface.track(String, LDContext), LDClientInterface.trackData(String, LDContext, LDValue)

      • identify

        public void identify​(LDContext context)
        Description copied from interface: LDClientInterface
        Reports details about an evaluation context.

        This method simply creates an analytics event containing the context properties, to that LaunchDarkly will know about that context if it does not already.

        Calling any evaluation method, such as LDClientInterface.boolVariation(String, LDContext, boolean), also sends the context information to LaunchDarkly (if events are enabled), so you only need to use this method if you want to identify the context without evaluating a flag.

        Note that event delivery is asynchronous, so the event may not actually be sent until later; see LDClientInterface.flush().

        Specified by:
        identify in interface LDClientInterface
        Parameters:
        context - the context to register

      • allFlagsState

        public FeatureFlagsState allFlagsState​(LDContext context,
                                       FlagsStateOption... options)
        Description copied from interface: LDClientInterface
        Returns an object that encapsulates the state of all feature flags for a given context, which can be passed to front-end code.

        The object returned by this method contains the flag values as well as other metadata that is used by the LaunchDarkly JavaScript client, so it can be used for bootstrapping.

        This method will not send analytics events back to LaunchDarkly.

        Specified by:
        allFlagsState in interface LDClientInterface
        Parameters:
        context - the evaluation context
        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()

      • boolVariation

        public boolean boolVariation​(java.lang.String featureKey,
                             LDContext context,
                             boolean defaultValue)
        Description copied from interface: LDClientInterface
        Calculates the boolean value of a feature flag for a given context.

        If the flag variation does not have a boolean value, defaultValue is returned.

        If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

        Specified by:
        boolVariation in interface LDClientInterface
        Parameters:
        featureKey - the unique key for the feature flag
        context - the evaluation context
        defaultValue - the default value of the flag
        Returns:
        the variation for the given context, or defaultValue if the flag cannot be evaluated

      • intVariation

        public int intVariation​(java.lang.String featureKey,
                        LDContext context,
                        int defaultValue)
        Description copied from interface: LDClientInterface
        Calculates the integer value of a feature flag for a given context.

        If the flag variation has a numeric value that is not an integer, it is rounded toward zero (truncated).

        If the flag variation does not have a numeric value, defaultValue is returned.

        If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

        Specified by:
        intVariation in interface LDClientInterface
        Parameters:
        featureKey - the unique key for the feature flag
        context - the evaluation context
        defaultValue - the default value of the flag
        Returns:
        the variation for the given context, or defaultValue if the flag cannot be evaluated

      • doubleVariation

        public double doubleVariation​(java.lang.String featureKey,
                              LDContext context,
                              double defaultValue)
        Description copied from interface: LDClientInterface
        Calculates the floating-point numeric value of a feature flag for a given context.

        If the flag variation does not have a numeric value, defaultValue is returned.

        If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

        Specified by:
        doubleVariation in interface LDClientInterface
        Parameters:
        featureKey - the unique key for the feature flag
        context - the evaluation context
        defaultValue - the default value of the flag
        Returns:
        the variation for the given context, or defaultValue if the flag cannot be evaluated

      • stringVariation

        public java.lang.String stringVariation​(java.lang.String featureKey,
                                        LDContext context,
                                        java.lang.String defaultValue)
        Description copied from interface: LDClientInterface
        Calculates the string value of a feature flag for a given context.

        If the flag variation does not have a string value, defaultValue is returned.

        If an error makes it impossible to evaluate the flag (for instance, the feature flag key does not match any existing flag), defaultValue is returned.

        Specified by:
        stringVariation in interface LDClientInterface
        Parameters:
        featureKey - the unique key for the feature flag
        context - the evaluation context
        defaultValue - the default value of the flag
        Returns:
        the variation for the given context, or defaultValue if the flag cannot be evaluated

      • jsonValueVariation

        public LDValue jsonValueVariation​(java.lang.String featureKey,
                                  LDContext context,
                                  LDValue defaultValue)
        Description copied from interface: LDClientInterface
        Calculates the value of a feature flag for a given context as any JSON value type.

        The type LDValue is used to represent any of the value types that can exist in JSON. Use LDValue methods to examine its type and value.

        Specified by:
        jsonValueVariation in interface LDClientInterface
        Parameters:
        featureKey - the unique key for the feature flag
        context - the evaluation context
        defaultValue - the default value of the flag
        Returns:
        the variation for the given context, or defaultValue if the flag cannot be evaluated

      • migrationVariation

        public MigrationVariation migrationVariation​(java.lang.String key,
                                             LDContext context,
                                             MigrationStage defaultStage)
        Description copied from interface: LDClientInterface
        Returns the migration stage of the migration feature flag for the given evaluation context.

        If the evaluated value of the flag cannot be converted to an LDMigrationStage, then the default value will be returned and error will be logged.

        Specified by:
        migrationVariation in interface LDClientInterface
        Parameters:
        key - the unique key for the feature flag
        context - the evaluation context
        defaultStage - the default stage of the migration
        Returns:
        the current stage and a tracker which can be used to track the migration operation

      • 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 interface LDClientInterface
        Parameters:
        featureKey - the unique key for the feature flag
        Returns:
        true if the flag exists

      • 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 interface LDClientInterface
        Returns:
        a DataStoreStatusProvider

      • getLogger

        public LDLogger getLogger()
        Description copied from interface: LDClientInterface
        Returns the logger instance used by this SDK instance.

        This allows for access to the logger by other LaunchDarkly components, such as the Migration class.

        It also allows for usage of the logger in wrapper implementations.

        It is not intended for general purpose application logging.

        Specified by:
        getLogger in interface LDClientInterface
        Returns:
        a LDLogger

      • close

        public void close()
           throws java.io.IOException
        Shuts down the client and releases any resources it is using.

        Unless it is offline, the client will attempt to deliver any pending analytics events before closing.

        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Specified by:
        close in interface LDClientInterface
        Throws:
        java.io.IOException - if an exception is thrown by one of the underlying network services

      • isOffline

        public boolean isOffline()
        Description copied from interface: LDClientInterface
        Returns true if the client is in offline mode.
        Specified by:
        isOffline in interface LDClientInterface
        Returns:
        whether the client is in offline mode

      • secureModeHash

        public java.lang.String secureModeHash​(LDContext context)
        Description copied from interface: LDClientInterface
        Creates a hash string that can be used by the JavaScript SDK to identify a context.

        See Secure mode in the JavaScript SDK Reference.

        Specified by:
        secureModeHash in interface LDClientInterface
        Parameters:
        context - the evaluation context
        Returns:
        the hash, or null if the hash could not be calculated

      • version

        public java.lang.String version()
        Returns the current version string of the client library.
        Specified by:
        version in interface LDClientInterface
        Returns:
        a version string conforming to Semantic Versioning (http://semver.org)