Package com.launchdarkly.sdk.server.interfaces

Interface LDClientInterface

  • All Superinterfaces:
    java.lang.AutoCloseable, java.io.Closeable
    All Known Implementing Classes:
    LDClient
    public interface LDClientInterface
extends java.io.Closeable
    This interface defines the public methods of LDClient.

    Applications will normally interact directly with LDClient, and must use its constructor to initialize the SDK, but being able to refer to it indirectly via an interface may be helpul in test scenarios (mocking) or for some dependency injection frameworks.

    • Method Summary

      All Methods Instance Methods Abstract Methods Default 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.
      default FeatureFlagsState allFlagsState​(LDUser user, FlagsStateOption... options)
      Returns an object that encapsulates the state of all feature flags for a given user, which can be passed to front-end code.
      boolean boolVariation​(java.lang.String key, LDContext context, boolean defaultValue)
      Calculates the boolean value of a feature flag for a given context.
      default boolean boolVariation​(java.lang.String key, LDUser user, boolean defaultValue)
      Calculates the boolean value of a feature flag for a given user.
      EvaluationDetail<java.lang.Boolean> boolVariationDetail​(java.lang.String key, 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.
      default EvaluationDetail<java.lang.Boolean> boolVariationDetail​(java.lang.String key, LDUser user, 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()
      Closes the LaunchDarkly client event processing thread.
      double doubleVariation​(java.lang.String key, LDContext context, double defaultValue)
      Calculates the floating-point numeric value of a feature flag for a given context.
      default double doubleVariation​(java.lang.String key, LDUser user, double defaultValue)
      Calculates the floating-point numeric value of a feature flag for a given context.
      EvaluationDetail<java.lang.Double> doubleVariationDetail​(java.lang.String key, 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.
      default EvaluationDetail<java.lang.Double> doubleVariationDetail​(java.lang.String key, LDUser user, 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.
      void identify​(LDContext context)
      Reports details about an evaluation context.
      default void identify​(LDUser user)
      Reports details about a user.
      int intVariation​(java.lang.String key, LDContext context, int defaultValue)
      Calculates the integer value of a feature flag for a given context.
      default int intVariation​(java.lang.String key, LDUser user, int defaultValue)
      Calculates the integer value of a feature flag for a given user.
      EvaluationDetail<java.lang.Integer> intVariationDetail​(java.lang.String key, 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.
      default EvaluationDetail<java.lang.Integer> intVariationDetail​(java.lang.String key, LDUser user, 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 key, LDContext context, LDValue defaultValue)
      Calculates the value of a feature flag for a given context as any JSON value type.
      default LDValue jsonValueVariation​(java.lang.String key, LDUser user, LDValue defaultValue)
      Calculates the value of a feature flag for a given context as any JSON value type.
      EvaluationDetail<LDValue> jsonValueVariationDetail​(java.lang.String key, 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.
      default EvaluationDetail<LDValue> jsonValueVariationDetail​(java.lang.String key, LDUser user, 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.
      java.lang.String secureModeHash​(LDContext context)
      Creates a hash string that can be used by the JavaScript SDK to identify a context.
      default java.lang.String secureModeHash​(LDUser user)
      Creates a hash string that can be used by the JavaScript SDK to identify a context.
      java.lang.String stringVariation​(java.lang.String key, LDContext context, java.lang.String defaultValue)
      Calculates the string value of a feature flag for a given context.
      default java.lang.String stringVariation​(java.lang.String key, LDUser user, java.lang.String defaultValue)
      Calculates the string value of a feature flag for a given context.
      EvaluationDetail<java.lang.String> stringVariationDetail​(java.lang.String key, 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.
      default EvaluationDetail<java.lang.String> stringVariationDetail​(java.lang.String key, LDUser user, 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.
      default void track​(java.lang.String eventName, LDUser user)
      Tracks that an application-defined event occurred.
      void trackData​(java.lang.String eventName, LDContext context, LDValue data)
      Tracks that an application-defined event occurred.
      default void trackData​(java.lang.String eventName, LDUser user, 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.
      default void trackMetric​(java.lang.String eventName, LDUser user, LDValue data, double metricValue)
      Tracks that an application-defined event occurred, and provides an additional numeric value for custom metrics.
      java.lang.String version()
      The current version string of the SDK.

    • Method Detail

      • isInitialized

        boolean isInitialized()
        Tests whether the client is ready to be used.
        Returns:
        true if the client is ready, or false if it is still initializing

      • trackMetric

        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.

        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 flush().

        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
        Since:
        4.9.0
        See Also:
        track(String, LDContext), trackData(String, LDContext, LDValue)

      • identify

        void identify​(LDContext context)
        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 boolVariation(String, LDContext, boolean), also sends the context information to LaunchDarkly (if events are enabled), so you only need to use identify(LDContext) 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 flush().

        Parameters:
        context - the context to register
        Since:
        6.0.0
        See Also:
        identify(LDUser)

      • allFlagsState

        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.

        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.

        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()
        Since:
        6.0.0
        See Also:
        allFlagsState(LDUser, FlagsStateOption...)

      • boolVariation

        boolean boolVariation​(java.lang.String key,
                      LDContext context,
                      boolean defaultValue)
        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.

        Parameters:
        key - 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
        Since:
        6.0.0
        See Also:
        boolVariation(String, LDUser, boolean)

      • boolVariation

        default boolean boolVariation​(java.lang.String key,
                              LDUser user,
                              boolean defaultValue)
        Calculates the boolean value of a feature flag for a given user.

        This is equivalent to boolVariation(String, LDContext, boolean), but using the LDUser type instead of LDContext.

        Parameters:
        key - the unique key for the feature flag
        user - the user attributes
        defaultValue - the default value of the flag
        Returns:
        the variation for the given context, or defaultValue if the flag cannot be evaluated
        See Also:
        boolVariation(String, LDContext, boolean)

      • intVariation

        int intVariation​(java.lang.String key,
                 LDContext context,
                 int defaultValue)
        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.

        Parameters:
        key - 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
        Since:
        6.0.0
        See Also:
        intVariation(String, LDUser, int)

      • intVariation

        default int intVariation​(java.lang.String key,
                         LDUser user,
                         int defaultValue)
        Calculates the integer value of a feature flag for a given user.

        This is equivalent to intVariation(String, LDContext, int), but using the LDUser type instead of LDContext.

        Parameters:
        key - the unique key for the feature flag
        user - the user attributes
        defaultValue - the default value of the flag
        Returns:
        the variation for the given context, or defaultValue if the flag cannot be evaluated
        See Also:
        intVariation(String, LDContext, int)

      • doubleVariation

        double doubleVariation​(java.lang.String key,
                       LDContext context,
                       double defaultValue)
        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.

        Parameters:
        key - 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
        Since:
        6.0.0
        See Also:
        doubleVariation(String, LDUser, double)

      • doubleVariation

        default double doubleVariation​(java.lang.String key,
                               LDUser user,
                               double defaultValue)
        Calculates the floating-point numeric value of a feature flag for a given context.

        This is equivalent to doubleVariation(String, LDContext, double), but using the LDUser type instead of LDContext.

        Parameters:
        key - the unique key for the feature flag
        user - the user attributes
        defaultValue - the default value of the flag
        Returns:
        the variation for the given context, or defaultValue if the flag cannot be evaluated
        See Also:
        doubleVariation(String, LDContext, double)

      • stringVariation

        java.lang.String stringVariation​(java.lang.String key,
                                 LDContext context,
                                 java.lang.String defaultValue)
        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.

        Parameters:
        key - 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
        Since:
        6.0.0
        See Also:
        stringVariation(String, LDUser, String)

      • stringVariation

        default java.lang.String stringVariation​(java.lang.String key,
                                         LDUser user,
                                         java.lang.String defaultValue)
        Calculates the string value of a feature flag for a given context.

        This is equivalent to stringVariation(String, LDContext, String), but using the LDUser type instead of LDContext.

        Parameters:
        key - the unique key for the feature flag
        user - the user attributes
        defaultValue - the default value of the flag
        Returns:
        the variation for the given context, or defaultValue if the flag cannot be evaluated
        See Also:
        stringVariation(String, LDContext, String)

      • jsonValueVariation

        LDValue jsonValueVariation​(java.lang.String key,
                           LDContext context,
                           LDValue defaultValue)
        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.

        Parameters:
        key - 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
        Since:
        6.0.0
        See Also:
        jsonValueVariation(String, LDUser, LDValue)

      • intVariationDetail

        EvaluationDetail<java.lang.Integer> intVariationDetail​(java.lang.String key,
                                                       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.

        The EvaluationDetail.getReason() property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

        The behavior is otherwise identical to intVariation(String, LDContext, int).

        Parameters:
        key - the unique key for the feature flag
        context - the evaluation context
        defaultValue - the default value of the flag
        Returns:
        an EvaluationDetail object
        Since:
        6.0.0
        See Also:
        intVariationDetail(String, LDUser, int)

      • stringVariationDetail

        EvaluationDetail<java.lang.String> stringVariationDetail​(java.lang.String key,
                                                         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.

        The EvaluationDetail.getReason() property in the result will also be included in analytics events, if you are capturing detailed event data for this flag.

        The behavior is otherwise identical to stringVariation(String, LDContext, String).

        Parameters:
        key - the unique key for the feature flag
        context - the evaluation context
        defaultValue - the default value of the flag
        Returns:
        an EvaluationDetail object
        Since:
        6.0.0
        See Also:
        stringVariation(String, LDUser, String)

      • isFlagKnown

        boolean isFlagKnown​(java.lang.String featureKey)
        Returns true if the specified feature flag currently exists.
        Parameters:
        featureKey - the unique key for the feature flag
        Returns:
        true if the flag exists

      • close

        void close()
    throws java.io.IOException
        Closes the LaunchDarkly client event processing thread. This should only be called on application shutdown.
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException - if an exception is thrown by one of the underlying network services

      • flush

        void flush()
        Flushes all pending events.

      • isOffline

        boolean isOffline()
        Returns true if the client is in offline mode.
        Returns:
        whether the client is in offline mode

      • getFlagTracker

        FlagTracker getFlagTracker()
        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.

        Returns:
        a FlagTracker
        Since:
        5.0.0

      • getBigSegmentStoreStatusProvider

        BigSegmentStoreStatusProvider getBigSegmentStoreStatusProvider()
        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.

        Returns:
        a BigSegmentStoreStatusProvider
        Since:
        5.7.0

      • getDataSourceStatusProvider

        DataSourceStatusProvider getDataSourceStatusProvider()
        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.

        Returns:
        a DataSourceStatusProvider
        Since:
        5.0.0

      • getDataStoreStatusProvider

        DataStoreStatusProvider getDataStoreStatusProvider()
        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.

        Returns:
        a DataStoreStatusProvider
        Since:
        5.0.0

      • secureModeHash

        java.lang.String secureModeHash​(LDContext context)
        Creates a hash string that can be used by the JavaScript SDK to identify a context.

        See Secure mode in the JavaScript SDK Reference.

        Parameters:
        context - the evaluation context
        Returns:
        the hash, or null if the hash could not be calculated
        Since:
        6.0.0
        See Also:
        secureModeHash(LDUser)

      • secureModeHash

        default java.lang.String secureModeHash​(LDUser user)
        Creates a hash string that can be used by the JavaScript SDK to identify a context.

        This is equivalent to secureModeHash(LDContext), but using the LDUser type instead of LDContext.

        Parameters:
        user - the user attributes
        Returns:
        the hash, or null if the hash could not be calculated
        See Also:
        secureModeHash(LDContext)

      • version

        java.lang.String version()
        The current version string of the SDK.
        Returns:
        a string in Semantic Versioning 2.0.0 format