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