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 helpful in test scenarios (mocking) or for some dependency injection frameworks.

    • 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

      • trackData

        void trackData​(java.lang.String eventName,
               LDContext context,
               LDValue data)
        Tracks that an application-defined event occurred.

        This method creates a "custom" analytics event containing the specified event name (key), context properties, and optional data. If you do not need custom data, pass LDValue.ofNull() for the last parameter or simply omit the parameter. You may attach a metric value to the event by calling trackMetric(String, LDContext, LDValue, double) instead.

        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 - additional data associated with the event, if any
        Since:
        6.0.0
        See Also:
        track(String, LDContext), trackMetric(String, LDContext, LDValue, double)

      • 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)

      • trackMigration

        void trackMigration​(MigrationOpTracker tracker)
        Track the details of a migration.
        Parameters:
        tracker - Migration tracker which was used to track details of the migration operation.
        Since:
        7.0.0

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

        Parameters:
        context - the context to register
        Since:
        6.0.0

      • 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

      • 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

      • 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

      • 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

      • 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

      • 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

      • boolVariationDetail

        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.

        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 boolVariation(String, LDContext, boolean).

        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

      • 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

      • doubleVariationDetail

        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.

        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 doubleVariation(String, LDContext, double).

        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

      • 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

      • jsonValueVariationDetail

        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.

        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 jsonValueVariation(String, LDContext, LDValue).

        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

      • migrationVariation

        MigrationVariation migrationVariation​(java.lang.String key,
                                      LDContext context,
                                      MigrationStage defaultStage)
        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.

        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
        Since:
        7.0.0

      • 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

      • getLogger

        LDLogger getLogger()
        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.

        Returns:
        a LDLogger
        Since:
        7.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

      • version

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