+ * The reason for using this mechanism, instead of just passing those objects directly as constructor + * parameters, is that some SDK components are pluggable-- that is, they are implementations of a + * public interface that a customer could implement themselves, and they are instantiated via a + * standard factory method, which always takes a {@link ClientContext} parameter. Customer code can + * only see the public properties of {@link ClientContext}, but our own code can see the + * package-private properties, which they can do by calling {@code ClientContextImpl.get(ClientContext)} + * to make sure that what they have is really a {@code ClientContextImpl} (as opposed to some other + * implementation of {@link ClientContext}, which might have been created for instance in application + * test code). + *
+ * Any attempt by SDK components to access an object that would normally be provided by the SDK, + * but that has not been set, will cause an immediate unchecked exception. This would only happen if + * components were being used outside of the SDK client in test code that did not correctly set + * these properties. + */ +final class ClientContextImpl extends ClientContext { + private final DiagnosticStore diagnosticStore; + private final OkHttpClient sharedEventClient; + private final SummaryEventStore summaryEventStore; + + ClientContextImpl( + ClientContext base, + DiagnosticStore diagnosticStore, + OkHttpClient sharedEventClient, + SummaryEventStore summaryEventStore + ) { + super(base); + this.diagnosticStore = diagnosticStore; + this.sharedEventClient = sharedEventClient; + this.summaryEventStore = summaryEventStore; + } + + static ClientContextImpl fromConfig( + Application application, + LDConfig config, + String mobileKey, + String environmentName, + DiagnosticStore diagnosticStore, + OkHttpClient sharedEventClient, + SummaryEventStore summaryEventStore, + LDLogger logger + ) { + ClientContext minimalContext = new ClientContext(null, mobileKey, logger, config, + environmentName, config.isEvaluationReasons(), null, config.isOffline(), + config.serviceEndpoints); + HttpConfiguration httpConfig = config.http.build(minimalContext); + ClientContext baseClientContext = new ClientContext( + application, + mobileKey, + logger, + config, + environmentName, + config.isEvaluationReasons(), + httpConfig, + config.isOffline(), + config.serviceEndpoints + ); + return new ClientContextImpl(baseClientContext, diagnosticStore, sharedEventClient, summaryEventStore); + } + + public static ClientContextImpl get(ClientContext context) { + if (context instanceof ClientContextImpl) { + return (ClientContextImpl)context; + } + return new ClientContextImpl(context, null, null, null); + } + + public DiagnosticStore getDiagnosticStore() { + return diagnosticStore; + } + + public OkHttpClient getSharedEventClient() { + throwExceptionIfNull(sharedEventClient); + return sharedEventClient; + } + + public SummaryEventStore getSummaryEventStore() { + throwExceptionIfNull(summaryEventStore); + return summaryEventStore; + } + + private static void throwExceptionIfNull(Object o) { + if (o == null) { + throw new IllegalStateException( + "Attempted to use an SDK component without the necessary dependencies from LDClient; " + + " this should never happen unless an application has tried to construct the" + + " component directly outside of normal SDK usage" + ); + } + } +} \ No newline at end of file diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/Components.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/Components.java new file mode 100644 index 00000000..771a18a0 --- /dev/null +++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/Components.java @@ -0,0 +1,160 @@ +package com.launchdarkly.sdk.android; + +import static com.launchdarkly.sdk.android.ComponentsImpl.NULL_EVENT_PROCESSOR_FACTORY; + +import com.launchdarkly.sdk.android.integrations.EventProcessorBuilder; +import com.launchdarkly.sdk.android.integrations.HttpConfigurationBuilder; +import com.launchdarkly.sdk.android.integrations.PollingDataSourceBuilder; +import com.launchdarkly.sdk.android.integrations.ServiceEndpointsBuilder; +import com.launchdarkly.sdk.android.integrations.StreamingDataSourceBuilder; +import com.launchdarkly.sdk.android.subsystems.ComponentConfigurer; +import com.launchdarkly.sdk.android.subsystems.EventProcessor; + +/** + * Provides configurable factories for the standard implementations of LaunchDarkly component interfaces. + *
+ * Some of the configuration options in {@link LDConfig.Builder} affect the entire SDK, but others are + * specific to one area of functionality, such as how the SDK receives feature flag updates or processes + * analytics events. For the latter, the standard way to specify a configuration is to call one of the + * static methods in {@link Components}, apply any desired configuration change to the object that that + * method returns, and then use the corresponding method in {@link LDConfig.Builder} to use that + * configured component in the SDK. + * + * @since 3.3.0 + */ +public abstract class Components { + private Components() {} + + /** + * Returns a configuration builder for the SDK's networking configuration. + *
+ * Passing this to {@link LDConfig.Builder#http(ComponentConfigurer)} applies this configuration + * to all HTTP/HTTPS requests made by the SDK. + *
+ * LDConfig config = new LDConfig.Builder()
+ * .http(
+ * Components.httpConfiguration()
+ * .connectTimeoutMillis(3000)
+ * .proxyHostAndPort("my-proxy", 8080)
+ * )
+ * .build();
+ * + * Passing this to {@link LDConfig.Builder#events(ComponentConfigurer)} causes the SDK + * to discard all analytics events and not send them to LaunchDarkly, regardless of any other configuration. + *
+ * LDConfig config = new LDConfig.Builder()
+ * .events(Components.noEvents())
+ * .build();
+ * + * By default, the SDK uses a streaming connection to receive feature flag data from LaunchDarkly. To use the + * default behavior, you do not need to call this method. However, if you want to customize the behavior of + * the connection, call this method to obtain a builder, change its properties with the + * {@link PollingDataSourceBuilder} methods, and pass it to {@link LDConfig.Builder#dataSource(ComponentConfigurer)}: + *
+ * LDConfig config = new LDConfig.Builder()
+ * .dataSource(Components.pollingDataSource().initialReconnectDelayMillis(500))
+ * .build();
+ * + * Setting {@link LDConfig.Builder#offline(boolean)} to {@code true} will supersede this setting + * and completely disable network requests. + * + * @return a builder for setting streaming connection properties + * @see LDConfig.Builder#dataSource(ComponentConfigurer) + */ + public static PollingDataSourceBuilder pollingDataSource() { + return new ComponentsImpl.PollingDataSourceBuilderImpl(); + } + + /** + * Returns a configuration builder for analytics event delivery. + *
+ * The default configuration has events enabled with default settings. If you want to + * customize this behavior, call this method to obtain a builder, change its properties + * with the {@link EventProcessorBuilder} properties, and pass it to {@link LDConfig.Builder#events(ComponentConfigurer)}: + *
+ * LDConfig config = new LDConfig.Builder()
+ * .events(Components.sendEvents().capacity(500).flushIntervalMillis(2000))
+ * .build();
+ * + * Setting {@link LDConfig.Builder#offline(boolean)} to {@code true} will supersede this setting + * and completely disable network requests. + * + * @return a builder for setting event-related options + * @see #noEvents() + * @see LDConfig.Builder#events(ComponentConfigurer) + */ + public static EventProcessorBuilder sendEvents() { + return new ComponentsImpl.EventProcessorBuilderImpl(); + } + + /** + * Returns a builder for configuring custom service URIs. + *
+ * Passing this to {@link LDConfig.Builder#serviceEndpoints(com.launchdarkly.sdk.android.integrations.ServiceEndpointsBuilder)}, + * after setting any desired properties on the builder, applies this configuration to the SDK. + *
+ * LDConfig config = new LDConfig.Builder()
+ * .serviceEndpoints(
+ * Components.serviceEndpoints()
+ * .relayProxy("http://my-relay-hostname:80")
+ * )
+ * .build();
+ * + * By default, the SDK uses a streaming connection to receive feature flag data from LaunchDarkly. To use the + * default behavior, you do not need to call this method. However, if you want to customize the behavior of + * the connection, call this method to obtain a builder, change its properties with the + * {@link StreamingDataSourceBuilder} methods, and pass it to {@link LDConfig.Builder#dataSource(ComponentConfigurer)}: + *
+ * LDConfig config = new LDConfig.Builder()
+ * .dataSource(Components.streamingDataSource().initialReconnectDelayMillis(500))
+ * .build();
+ *
+ * Setting {@link LDConfig.Builder#offline(boolean)} to {@code true} will supersede this setting
+ * and completely disable network requests.
+ *
+ * @return a builder for setting streaming connection properties
+ * @see LDConfig.Builder#dataSource(ComponentConfigurer)
+ */
+ public static StreamingDataSourceBuilder streamingDataSource() {
+ return new ComponentsImpl.StreamingDataSourceBuilderImpl();
+ }
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/ComponentsImpl.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/ComponentsImpl.java
new file mode 100644
index 00000000..ca19f5bf
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/ComponentsImpl.java
@@ -0,0 +1,250 @@
+package com.launchdarkly.sdk.android;
+
+import android.net.Uri;
+
+import com.launchdarkly.logging.LDLogger;
+import com.launchdarkly.sdk.EvaluationReason;
+import com.launchdarkly.sdk.LDUser;
+import com.launchdarkly.sdk.LDValue;
+import com.launchdarkly.sdk.android.integrations.EventProcessorBuilder;
+import com.launchdarkly.sdk.android.integrations.HttpConfigurationBuilder;
+import com.launchdarkly.sdk.android.integrations.PollingDataSourceBuilder;
+import com.launchdarkly.sdk.android.integrations.ServiceEndpointsBuilder;
+import com.launchdarkly.sdk.android.integrations.StreamingDataSourceBuilder;
+import com.launchdarkly.sdk.android.subsystems.ClientContext;
+import com.launchdarkly.sdk.android.subsystems.ComponentConfigurer;
+import com.launchdarkly.sdk.android.subsystems.DataSource;
+import com.launchdarkly.sdk.android.subsystems.DiagnosticDescription;
+import com.launchdarkly.sdk.android.subsystems.EventProcessor;
+import com.launchdarkly.sdk.android.subsystems.HttpConfiguration;
+import com.launchdarkly.sdk.android.subsystems.ServiceEndpoints;
+
+import java.net.URI;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.Set;
+
+/**
+ * This class contains the package-private implementations of component factories and builders whose
+ * public factory methods are in {@link Components}.
+ */
+abstract class ComponentsImpl {
+ private ComponentsImpl() {
+ }
+
+ static final ComponentConfigurer
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#serviceEndpoints(ServiceEndpointsBuilder)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual base URI properties
+ * are removed from the top-level configuration.
*/
+ @Deprecated
public Uri getPollUri() {
return pollUri;
}
+ /**
+ * Returns the setting of {@link Builder#eventsUri(Uri)}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#serviceEndpoints(ServiceEndpointsBuilder)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual base URI properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public Uri getEventsUri() {
return eventsUri;
}
+ /**
+ * Returns the setting of {@link Builder#eventsCapacity(int)}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#events(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual event-related properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public int getEventsCapacity() {
return eventsCapacity;
}
+ /**
+ * Returns the setting of {@link Builder#eventsFlushIntervalMillis(int)}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#events(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual event-related properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public int getEventsFlushIntervalMillis() {
return eventsFlushIntervalMillis;
}
+ /**
+ * Returns the setting of {@link Builder#connectionTimeoutMillis(int)}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#http(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual HTTP-related properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public int getConnectionTimeoutMillis() {
return connectionTimeoutMillis;
}
+ /**
+ * Returns the setting of {@link Builder#streamUri(Uri)}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#serviceEndpoints(ServiceEndpointsBuilder)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual base URI properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public Uri getStreamUri() {
return streamUri;
}
@@ -225,18 +291,58 @@ public boolean isOffline() {
return offline;
}
+ /**
+ * Returns the setting of {@link Builder#stream(boolean)}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#dataSource(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual data source properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public boolean isStream() {
return stream;
}
+ /**
+ * Returns the setting of {@link Builder#useReport(boolean)}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#http(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual HTTP-related properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public boolean isUseReport() {
return useReport;
}
+ /**
+ * Returns the setting of {@link Builder#pollingIntervalMillis(int)} ()}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#dataSource(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual data source properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public int getPollingIntervalMillis() {
return pollingIntervalMillis;
}
+ /**
+ * Returns the setting of {@link Builder#backgroundPollingIntervalMillis(int)} ()}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#dataSource(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual data source properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public int getBackgroundPollingIntervalMillis() {
return backgroundPollingIntervalMillis;
}
@@ -245,18 +351,56 @@ public boolean isDisableBackgroundPolling() {
return disableBackgroundUpdating;
}
+ /**
+ * Returns the setting of {@link Builder#allAttributesPrivate()}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#events(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual event-related properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public boolean allAttributesPrivate() {
return allAttributesPrivate;
}
+ /**
+ * Returns the setting of {@link Builder#privateAttributes(UserAttribute...)}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#events(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual event-related properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public Set
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#events(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual event-related properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public boolean inlineUsersInEvents() {
return inlineUsersInEvents;
}
@@ -285,6 +429,16 @@ int getMaxCachedUsers() {
return maxCachedUsers;
}
+ /**
+ * Returns the setting of {@link Builder#headerTransform(LDHeaderUpdater)}.
+ *
+ * This is only applicable if you have used the deprecated builder method rather than
+ * {@link Builder#http(ComponentConfigurer)}.
+ * @return the property value
+ * @deprecated This method will be removed in the future when individual HTTP-related properties
+ * are removed from the top-level configuration.
+ */
+ @Deprecated
public LDHeaderUpdater getHeaderTransform() {
return headerTransform;
}
@@ -315,12 +469,18 @@ public static class Builder {
private Uri eventsUri = DEFAULT_EVENTS_URI;
private Uri streamUri = DEFAULT_STREAM_URI;
- private int eventsCapacity = DEFAULT_EVENTS_CAPACITY;
+ private ComponentConfigurer
+ * The preferred way to set this option now is with {@link EventProcessorBuilder}. Any
+ * settings there will override this deprecated method.
+ *
* @return the builder
+ * @deprecated Use {@link #events(ComponentConfigurer)} and
+ * {@link EventProcessorBuilder#allAttributesPrivate(boolean)} instead.
*/
+ @Deprecated
public Builder allAttributesPrivate() {
this.allAttributesPrivate = true;
return this;
}
/**
- * Marks a set of attributes private. Any users sent to LaunchDarkly with this configuration
- * active will have attributes with these names removed.
- *
+ * Deprecated method for marking a set of attributes as private.
+ *
+ * The preferred way to set this option now is with {@link EventProcessorBuilder}. Any
+ * settings there will override this deprecated method.
+ *
* This can also be specified on a per-user basis with {@link LDUser.Builder} methods like
* {@link LDUser.Builder#privateName(String)}.
*
* @param privateAttributes a set of names that will be removed from user data sent to LaunchDarkly
* @return the builder
+ * @deprecated Use {@link Builder#events(ComponentConfigurer)} and
+ * {@link EventProcessorBuilder#privateAttributes(String...)} instead.
*/
+ @Deprecated
public Builder privateAttributes(UserAttribute... privateAttributes) {
this.privateAttributes = new HashSet<>(Arrays.asList(privateAttributes));
return this;
@@ -415,132 +585,303 @@ public LDConfig.Builder secondaryMobileKeys(Map
+ * The preferred way to set this option now is with {@link HttpConfigurationBuilder}. Any
+ * settings there will override this deprecated method.
*
* @param useReport true if HTTP requests should use the REPORT verb
* @return the builder
+ * @deprecated Use {@link Builder#http(ComponentConfigurer)} and
+ * {@link HttpConfigurationBuilder#useReport(boolean)} instead.
*/
+ @Deprecated
public LDConfig.Builder useReport(boolean useReport) {
this.useReport = useReport;
return this;
}
/**
- * Set the base URI for polling requests to LaunchDarkly. You probably don't need to set this unless instructed by LaunchDarkly.
+ * Deprecated method for setting the base URI of the polling service.
+ *
+ * The preferred way to set this option now is with {@link ServiceEndpointsBuilder}. Any
+ * settings there will override this deprecated method.
*
- * @param pollUri the URI of the main LaunchDarkly service
+ * @param pollUri the URI of the LaunchDarkly polling service
* @return the builder
+ * @deprecated Use {@link Builder#serviceEndpoints(ServiceEndpointsBuilder)} and
+ * {@link ServiceEndpointsBuilder#polling(URI)} instead.
*/
+ @Deprecated
public LDConfig.Builder pollUri(Uri pollUri) {
this.pollUri = pollUri;
return this;
}
/**
- * Set the events URI for sending analytics to LaunchDarkly. You probably don't need to set this unless instructed by LaunchDarkly.
+ * Deprecated method for setting the base URI of the events service.
+ *
+ * The preferred way to set this option now is with {@link ServiceEndpointsBuilder}. Any
+ * settings there will override this deprecated method.
*
- * @param eventsUri the URI of the LaunchDarkly analytics event service
+ * @param eventsUri the URI of the LaunchDarkly events service
* @return the builder
+ * @deprecated Use {@link Builder#serviceEndpoints(ServiceEndpointsBuilder)} and
+ * {@link ServiceEndpointsBuilder#events(URI)} instead.
*/
+ @Deprecated
public LDConfig.Builder eventsUri(Uri eventsUri) {
this.eventsUri = eventsUri;
return this;
}
/**
- * Set the stream URI for connecting to the flag update stream. You probably don't need to set this unless instructed by LaunchDarkly.
+ * Deprecated method for setting the base URI of the streaming service.
+ *
+ * The preferred way to set this option now is with {@link ServiceEndpointsBuilder}. Any
+ * settings there will override this deprecated method.
*
* @param streamUri the URI of the LaunchDarkly streaming service
* @return the builder
+ * @deprecated Use {@link Builder#serviceEndpoints(ServiceEndpointsBuilder)} and
+ * {@link ServiceEndpointsBuilder#streaming(URI)} instead.
*/
+ @Deprecated
public LDConfig.Builder streamUri(Uri streamUri) {
this.streamUri = streamUri;
return this;
}
/**
- * Set the capacity of the event buffer. The client buffers up to this many events in memory before flushing.
- * If the capacity is exceeded before the buffer is flushed, events will be discarded. Increasing the capacity
- * means that events are less likely to be discarded, at the cost of consuming more memory.
+ * Sets the configuration of the component that receives feature flag data from LaunchDarkly.
+ *
+ * The default is {@link Components#streamingDataSource()}; you may instead use
+ * {@link Components#pollingDataSource()}. See those methods for details on how to configure
+ * them with options that are specific to streaming or polling mode.
+ *
+ * Setting {@link LDConfig.Builder#offline(boolean)} to {@code true} will supersede this setting
+ * and completely disable network requests.
+ *
+ * The default is {@link Components#sendEvents()} with no custom options. You may instead call
+ * {@link Components#sendEvents()} and then set custom options for event processing; or, disable
+ * events with {@link Components#noEvents()}; or, choose to use a custom implementation (for
+ * instance, a test fixture).
+ *
+ * Setting {@link LDConfig.Builder#offline(boolean)} to {@code true} will supersede this setting
+ * and completely disable network requests.
+ *
+ * This object is a configuration builder obtained from {@link Components#serviceEndpoints()},
+ * which has methods for setting each external endpoint to a custom URI.
+ *
- * The default value is {@link #DEFAULT_EVENTS_CAPACITY}.
+ * The preferred way to set this option now is with {@link EventProcessorBuilder}. Any
+ * settings there will override this deprecated method.
+ *
+ * The default value is {@link EventProcessorBuilder#DEFAULT_CAPACITY}.
*
* @param eventsCapacity the capacity of the event buffer
* @return the builder
* @see #eventsFlushIntervalMillis(int)
+ * @deprecated Use {@link Builder#events(ComponentConfigurer)} and
+ * {@link EventProcessorBuilder#capacity(int)} instead.
*/
+ @Deprecated
public LDConfig.Builder eventsCapacity(int eventsCapacity) {
this.eventsCapacity = eventsCapacity;
return this;
}
/**
- * Sets the maximum amount of time to wait in between sending analytics events to LaunchDarkly.
+ * Deprecated method for setting the maximum amount of time to wait in between sending
+ * analytics events to LaunchDarkly.
+ *
+ * The preferred way to set this option now is with {@link EventProcessorBuilder}. Any
+ * settings there will override this deprecated method.
*
- * The default value is {@link #DEFAULT_FLUSH_INTERVAL_MILLIS}.
+ * The default value is {@link EventProcessorBuilder#DEFAULT_FLUSH_INTERVAL_MILLIS}.
*
* @param eventsFlushIntervalMillis the interval between event flushes, in milliseconds
* @return the builder
* @see #eventsCapacity(int)
+ * @deprecated Use {@link Builder#events(ComponentConfigurer)} and
+ * {@link EventProcessorBuilder#flushIntervalMillis(int)} instead.
*/
+ @Deprecated
public LDConfig.Builder eventsFlushIntervalMillis(int eventsFlushIntervalMillis) {
this.eventsFlushIntervalMillis = eventsFlushIntervalMillis;
return this;
}
-
/**
- * Sets the timeout when connecting to LaunchDarkly.
+ * Deprecated method for setting the connection timeout.
*
- * The default value is {@link #DEFAULT_CONNECTION_TIMEOUT_MILLIS}.
+ * The preferred way to set this option now is with {@link HttpConfigurationBuilder}. Any
+ * settings there will override this deprecated method.
*
* @param connectionTimeoutMillis the connection timeout, in milliseconds
* @return the builder
+ * @deprecated Use {@link Builder#http(ComponentConfigurer)} and
+ * {@link HttpConfigurationBuilder#connectTimeoutMillis(int)} instead.
*/
+ @Deprecated
public LDConfig.Builder connectionTimeoutMillis(int connectionTimeoutMillis) {
this.connectionTimeoutMillis = connectionTimeoutMillis;
return this;
}
-
/**
- * Enables or disables real-time streaming flag updates. By default, streaming is enabled.
- * When disabled, an efficient caching polling mechanism is used.
+ * Deprecated method for enabling or disabling real-time streaming flag updates.
+ *
+ * The preferred way to set this option now is with {@link StreamingDataSourceBuilder}. Any
+ * settings there will override this deprecated method. Setting this option to {@code false}
+ * is equivalent to calling {@code builder.dataSource(Components.pollingDataSource())}.
+ *
+ * By default, streaming is enabled.
*
* @param enabled true if streaming should be enabled
* @return the builder
+ * @deprecated Use {@link Builder#dataSource(ComponentConfigurer)} with either
+ * {@link Components#streamingDataSource()} or {@link Components#pollingDataSource()}
+ * instead.
*/
+ @Deprecated
public LDConfig.Builder stream(boolean enabled) {
this.stream = enabled;
return this;
}
/**
- * Sets the interval in between feature flag updates, when streaming mode is disabled.
- * This is ignored unless {@link #stream(boolean)} is set to {@code true}. When set, it
- * will also change the default value for {@link #eventsFlushIntervalMillis(int)} to the
- * same value.
+ * Deprecated method for setting the interval in between feature flag updates, when
+ * streaming mode is disabled.
*
- * The default value is {@link LDConfig#DEFAULT_POLLING_INTERVAL_MILLIS}.
+ * The preferred way to set this option now is with {@link PollingDataSourceBuilder}. Any
+ * settings there will override this deprecated method.
+ *
+ * The default value is {@link PollingDataSourceBuilder#DEFAULT_POLL_INTERVAL_MILLIS}.
*
* @param pollingIntervalMillis the feature flag polling interval, in milliseconds
* @return the builder
+ * @deprecated Use {@link Builder#dataSource(ComponentConfigurer)} and
+ * {@link PollingDataSourceBuilder#pollIntervalMillis(int)} instead.
*/
+ @Deprecated
public LDConfig.Builder pollingIntervalMillis(int pollingIntervalMillis) {
this.pollingIntervalMillis = pollingIntervalMillis;
return this;
}
/**
- * Sets how often the client will poll for flag updates when your application is in the background.
+ * Deprecated method for setting how often the client will poll for flag updates when your
+ * application is in the background.
+ *
+ * The preferred way to set this option now is with {@link StreamingDataSourceBuilder} or
+ * {@link PollingDataSourceBuilder} (depending on whether you want the SDK to use streaming
+ * or polling when it is in the foreground). Any settings there will override this
+ * deprecated method.
*
- * The default value is {@link LDConfig#DEFAULT_BACKGROUND_POLLING_INTERVAL_MILLIS}.
+ * The default value is {@link LDConfig#DEFAULT_BACKGROUND_POLL_INTERVAL_MILLIS}.
*
* @param backgroundPollingIntervalMillis the feature flag polling interval when in the background,
* in milliseconds
* @return the builder
+ * @deprecated Use {@link Builder#dataSource(ComponentConfigurer)} and either
+ * {@link StreamingDataSourceBuilder#backgroundPollIntervalMillis(int)} or
+ * {@link PollingDataSourceBuilder#backgroundPollIntervalMillis(int)} instead.
*/
+ @Deprecated
public LDConfig.Builder backgroundPollingIntervalMillis(int backgroundPollingIntervalMillis) {
this.backgroundPollingIntervalMillis = backgroundPollingIntervalMillis;
return this;
@@ -576,15 +917,20 @@ public LDConfig.Builder offline(boolean offline) {
}
/**
- * If enabled, events to the server will be created containing the entire User object.
- * If disabled, events to the server will be created without the entire User object, including only the user key instead;
- * the rest of the user properties will still be included in Identify events.
+ * Deprecated method for specifying whether events sent to the server will always include
+ * the full user object.
+ *
+ * The preferred way to set this option now is with {@link EventProcessorBuilder}. Any
+ * settings there will override this deprecated method.
*
- * Defaults to false in order to reduce network bandwidth.
+ * This defaults to false in order to reduce network bandwidth.
*
* @param inlineUsersInEvents true if all user properties should be included in events
* @return the builder
+ * @deprecated Use {@link Builder#events(ComponentConfigurer)} and
+ * {@link EventProcessorBuilder#inlineUsers(boolean)} instead.
*/
+ @Deprecated
public LDConfig.Builder inlineUsersInEvents(boolean inlineUsersInEvents) {
this.inlineUsersInEvents = inlineUsersInEvents;
return this;
@@ -624,41 +970,52 @@ public LDConfig.Builder diagnosticOptOut(boolean diagnosticOptOut) {
}
/**
- * Sets the interval at which periodic diagnostic data is sent. The default is every 15 minutes (900,000
- * milliseconds) and the minimum value is 300,000 (5 minutes).
- *
- * @see #diagnosticOptOut(boolean) for more information on the diagnostics data being sent.
+ * Deprecatd method for setting the interval at which periodic diagnostic data is sent.
+ *
+ * The preferred way to set this option now is with {@link EventProcessorBuilder}. Any
+ * settings there will override this deprecated method.
*
* @param diagnosticRecordingIntervalMillis the diagnostics interval in milliseconds
* @return the builder
+ * @deprecated Use {@link Builder#events(ComponentConfigurer)} and
+ * {@link EventProcessorBuilder#diagnosticRecordingIntervalMillis(int)} instead.
+ * @see #diagnosticOptOut(boolean)
*/
+ @Deprecated
public LDConfig.Builder diagnosticRecordingIntervalMillis(int diagnosticRecordingIntervalMillis) {
this.diagnosticRecordingIntervalMillis = diagnosticRecordingIntervalMillis;
return this;
}
/**
- * For use by wrapper libraries to set an identifying name for the wrapper being used. This will be sent in
- * User-Agent headers during requests to the LaunchDarkly servers to allow recording metrics on the usage of
- * these wrapper libraries.
+ * Deprecated method for setting a wrapper library name to include in User-Agent headers.
+ *
+ * The preferred way to set this option now is with {@link HttpConfigurationBuilder}. Any
+ * settings there will override this deprecated method.
*
- * @param wrapperName An identifying name for the wrapper library
+ * @param wrapperName an identifying name for the wrapper library
* @return the builder
+ * @deprecated Use {@link Builder#http(ComponentConfigurer)} and
+ * {@link HttpConfigurationBuilder#wrapper(String, String)} instead.
*/
+ @Deprecated
public LDConfig.Builder wrapperName(String wrapperName) {
this.wrapperName = wrapperName;
return this;
}
/**
- * For use by wrapper libraries to report the version of the library in use. If the wrapper
- * name has not been set with {@link #wrapperName(String)} this field will be ignored.
- * Otherwise the version string will be included in the User-Agent headers along with the
- * wrapperName during requests to the LaunchDarkly servers.
+ * Deprecated method for setting a wrapper library version to include in User-Agent headers.
+ *
+ * The preferred way to set this option now is with {@link HttpConfigurationBuilder}. Any
+ * settings there will override this deprecated method.
*
- * @param wrapperVersion Version string for the wrapper library
+ * @param wrapperVersion a version string for the wrapper library
* @return the builder
+ * @deprecated Use {@link Builder#http(ComponentConfigurer)} and
+ * {@link HttpConfigurationBuilder#wrapper(String, String)} instead.
*/
+ @Deprecated
public LDConfig.Builder wrapperVersion(String wrapperVersion) {
this.wrapperVersion = wrapperVersion;
return this;
@@ -693,11 +1050,17 @@ public LDConfig.Builder autoAliasingOptOut(boolean autoAliasingOptOut) {
}
/**
- * Provides a callback for dynamically modifying headers used on requests to the LaunchDarkly service.
+ * Deprecated method for dynamically modifying request headers.
+ *
+ * The preferred way to set this option now is with {@link HttpConfigurationBuilder}. Any
+ * settings there will override this deprecated method.
*
* @param headerTransform the transformation to apply to requests
* @return the builder
+ * @deprecated Use {@link Builder#http(ComponentConfigurer)} and
+ * {@link HttpConfigurationBuilder#headerTransform(LDHeaderUpdater)} instead.
*/
+ @Deprecated
public LDConfig.Builder headerTransform(LDHeaderUpdater headerTransform) {
this.headerTransform = headerTransform;
return this;
@@ -812,61 +1175,114 @@ public LDConfig build() {
LDLogger logger = LDLogger.withAdapter(actualLogAdapter, loggerName);
- if (!stream) {
- if (pollingIntervalMillis < MIN_POLLING_INTERVAL_MILLIS) {
- logger.warn(
- "setPollingIntervalMillis: {} was set below the allowed minimum of: {}. Ignoring and using minimum value.",
- pollingIntervalMillis, MIN_POLLING_INTERVAL_MILLIS);
- pollingIntervalMillis = MIN_POLLING_INTERVAL_MILLIS;
- }
+ if (diagnosticRecordingIntervalMillis < EventProcessorBuilder.MIN_DIAGNOSTIC_RECORDING_INTERVAL_MILLIS) {
+ logger.warn(
+ "diagnosticRecordingIntervalMillis was set to %s, lower than the minimum allowed (%s). Ignoring and using minimum value.",
+ diagnosticRecordingIntervalMillis, EventProcessorBuilder.MIN_DIAGNOSTIC_RECORDING_INTERVAL_MILLIS);
+ diagnosticRecordingIntervalMillis = EventProcessorBuilder.MIN_DIAGNOSTIC_RECORDING_INTERVAL_MILLIS;
+ }
- if (!disableBackgroundUpdating && backgroundPollingIntervalMillis < pollingIntervalMillis) {
- logger.warn(
- "BackgroundPollingIntervalMillis: {} was set below the foreground polling interval: {}. Ignoring and using minimum value for background polling.",
- backgroundPollingIntervalMillis, pollingIntervalMillis);
- backgroundPollingIntervalMillis = MIN_BACKGROUND_POLLING_INTERVAL_MILLIS;
- }
+ HashMap
+ * Always returns some URI, falling back on the default if necessary, but logs a warning if we detect that the application
+ * set some custom endpoints but not this one.
+ *
+ * @param serviceEndpointsValue the value set in ServiceEndpoints (this is either the default URI, a custom URI, or null)
+ * @param defaultValue the constant default URI value defined in StandardEndpoints
+ * @param description a human-readable string for the type of endpoint being selected, for logging purposes
+ * @param logger the logger to which we should print the warning, if needed
+ * @return the base URI we should connect to
+ */
+ static URI selectBaseUri(URI serviceEndpointsValue, URI defaultValue, String description, LDLogger logger) {
+ if (serviceEndpointsValue != null) {
+ return serviceEndpointsValue;
+ }
+ logger.warn("You have set custom ServiceEndpoints without specifying the {} base URI; connections may not work properly", description);
+ return defaultValue;
+ }
+
+ /**
+ * Internal method to determine whether a given base URI was set to a custom value or not.
+ *
+ * This boolean value is only used for our diagnostic events. We only check if the value
+ * differs from the default; if the base URI was "overridden" in configuration, but
+ * happens to be equal to the default URI, we don't count that as custom
+ * for the purposes of this diagnostic.
+ *
+ * @param serviceEndpointsValue the value set in ServiceEndpoints
+ * @param defaultValue the constant default URI value defined in StandardEndpoints
+ * @return true iff the base URI was customized
+ */
+ static boolean isCustomBaseUri(URI serviceEndpointsValue, URI defaultValue) {
+ return serviceEndpointsValue != null && !serviceEndpointsValue.equals(defaultValue);
+ }
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/StreamUpdateProcessor.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/StreamUpdateProcessor.java
index 238023e2..4bf367a5 100644
--- a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/StreamUpdateProcessor.java
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/StreamUpdateProcessor.java
@@ -8,8 +8,10 @@
import com.launchdarkly.eventsource.MessageEvent;
import com.launchdarkly.eventsource.UnsuccessfulResponseException;
import com.launchdarkly.logging.LDLogger;
-import com.launchdarkly.logging.LogValues;
import com.launchdarkly.sdk.LDUser;
+import com.launchdarkly.sdk.android.subsystems.DataSource;
+import com.launchdarkly.sdk.android.subsystems.HttpConfiguration;
+import com.launchdarkly.sdk.android.subsystems.ServiceEndpoints;
import java.net.URI;
import java.util.HashMap;
@@ -35,8 +37,11 @@ class StreamUpdateProcessor {
private static final long MAX_RECONNECT_TIME_MS = 3_600_000; // 1 hour
private EventSource es;
+ private final DataSource dataSourceConfig;
+ private final HttpConfiguration httpConfig;
private final LDConfig config;
private final UserManager userManager;
+ private final Uri streamUri;
private volatile boolean running = false;
private final Debounce queue;
private boolean connection401Error = false;
@@ -47,10 +52,22 @@ class StreamUpdateProcessor {
private long eventSourceStarted;
private final LDLogger logger;
- StreamUpdateProcessor(LDConfig config, UserManager userManager, String environmentName, DiagnosticStore diagnosticStore,
- LDUtil.ResultCallback
+ * The SDK normally buffers analytics events and sends them to LaunchDarkly at intervals. If you want
+ * to customize this behavior, create a builder with {@link Components#sendEvents()}, change its
+ * properties with the methods of this class, and pass it to {@link Builder#events(ComponentConfigurer)}:
+ *
+ * Note that this class is abstract; the actual implementation is created by calling {@link Components#sendEvents()}.
+ *
+ * @since 3.3.0
+ */
+public abstract class EventProcessorBuilder implements ComponentConfigurer
+ * If this is {@code true}, all user attribute values (other than the key) will be private, not just
+ * the attributes specified in {@link #privateAttributes(String...)} or on a per-user basis with
+ * {@link com.launchdarkly.sdk.LDUser.Builder} methods. By default, it is {@code false}.
+ *
+ * @param allAttributesPrivate true if all user attributes should be private
+ * @return the builder
+ * @see #privateAttributes(String...)
+ * @see com.launchdarkly.sdk.LDUser.Builder
+ */
+ public EventProcessorBuilder allAttributesPrivate(boolean allAttributesPrivate) {
+ this.allAttributesPrivate = allAttributesPrivate;
+ return this;
+ }
+
+ /**
+ * Set the capacity of the events buffer.
+ *
+ * The client buffers up to this many events in memory before flushing. If the capacity is exceeded before
+ * the buffer is flushed (see {@link #flushIntervalMillis(int)}, events will be discarded. Increasing the
+ * capacity means that events are less likely to be discarded, at the cost of consuming more memory.
+ *
+ * The default value is {@link #DEFAULT_CAPACITY}.
+ *
+ * @param capacity the capacity of the event buffer
+ * @return the builder
+ */
+ public EventProcessorBuilder capacity(int capacity) {
+ this.capacity = capacity;
+ return this;
+ }
+
+ /**
+ * Sets the interval at which periodic diagnostic data is sent.
+ *
+ * The default value is {@link #DEFAULT_DIAGNOSTIC_RECORDING_INTERVAL_MILLIS}; the minimum value is
+ * {@link #MIN_DIAGNOSTIC_RECORDING_INTERVAL_MILLIS}. This property is ignored if
+ * {@link Builder#diagnosticOptOut(boolean)} is set to {@code true}.
+ *
+ * @param diagnosticRecordingIntervalMillis the diagnostics interval in milliseconds
+ * @return the builder
+ */
+ public EventProcessorBuilder diagnosticRecordingIntervalMillis(int diagnosticRecordingIntervalMillis) {
+ this.diagnosticRecordingIntervalMillis = diagnosticRecordingIntervalMillis < MIN_DIAGNOSTIC_RECORDING_INTERVAL_MILLIS ?
+ MIN_DIAGNOSTIC_RECORDING_INTERVAL_MILLIS : diagnosticRecordingIntervalMillis;
+ return this;
+ }
+
+ /**
+ * Sets the interval between flushes of the event buffer.
+ *
+ * Decreasing the flush interval means that the event buffer is less likely to reach capacity.
+ *
+ * The default value is {@link #DEFAULT_FLUSH_INTERVAL_MILLIS}.
+ *
+ * @param flushIntervalMillis the flush interval in milliseconds
+ * @return the builder
+ */
+ public EventProcessorBuilder flushIntervalMillis(int flushIntervalMillis) {
+ this.flushIntervalMillis = flushIntervalMillis <= 0 ? DEFAULT_FLUSH_INTERVAL_MILLIS : flushIntervalMillis;
+ return this;
+ }
+
+ /**
+ * If enabled, events to the server will be created containing the entire LDUser object.
+ * If disabled, events to the server will be created without the entire LDUser object, including
+ * only the user key instead; the rest of the user properties will still be included in Identify
+ * events.
+ *
+ * Defaults to false in order to reduce network bandwidth.
+ *
+ * @param inlineUsers true if all user properties should be included in events
+ * @return the builder
+ */
+ public EventProcessorBuilder inlineUsers(boolean inlineUsers) {
+ this.inlineUsers = inlineUsers;
+ return this;
+ }
+
+ /**
+ * Marks a set of attribute names or subproperties as private.
+ *
+ * Any contexts sent to LaunchDarkly with this configuration active will have attributes with these
+ * names removed. This is in addition to any attributes that were marked as private for an
+ * individual context with {@link com.launchdarkly.sdk.LDUser.Builder} methods.
+ *
+ * This method replaces any previous private attributes that were set on the same builder, rather
+ * than adding to them.
+ *
+ * @param attributeNames a set of attribute names that will be removed from context data set to LaunchDarkly
+ * @return the builder
+ * @see #allAttributesPrivate(boolean)
+ * @see com.launchdarkly.sdk.LDUser.Builder
+ */
+ public EventProcessorBuilder privateAttributes(String... attributeNames) {
+ privateAttributes = new HashSet<>();
+ for (String a: attributeNames) {
+ privateAttributes.add(a);
+ }
+ return this;
+ }
+
+ /**
+ * Marks a set of attribute names or subproperties as private.
+ *
+ * This is the same as {@link #privateAttributes(String...)}, but uses the
+ * {@link UserAttribute} type.
+ *
+ * @param attributeNames a set of attribute names that will be removed from context data set to LaunchDarkly
+ * @return the builder
+ * @see #allAttributesPrivate(boolean)
+ * @see com.launchdarkly.sdk.LDUser.Builder
+ */
+ public EventProcessorBuilder privateAttributes(UserAttribute... attributeNames) {
+ privateAttributes = new HashSet<>();
+ for (UserAttribute a: attributeNames) {
+ privateAttributes.add(a.getName());
+ }
+ return this;
+ }
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/HttpConfigurationBuilder.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/HttpConfigurationBuilder.java
new file mode 100644
index 00000000..66bf25e1
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/HttpConfigurationBuilder.java
@@ -0,0 +1,99 @@
+package com.launchdarkly.sdk.android.integrations;
+
+import com.launchdarkly.sdk.android.Components;
+import com.launchdarkly.sdk.android.LDHeaderUpdater;
+import com.launchdarkly.sdk.android.subsystems.ComponentConfigurer;
+import com.launchdarkly.sdk.android.subsystems.HttpConfiguration;
+
+/**
+ * Contains methods for configuring the SDK's networking behavior.
+ *
+ * If you want to set non-default values for any of these properties, create a builder with
+ * {@link Components#httpConfiguration()}, change its properties with the methods of this class,
+ * and pass it to {@link com.launchdarkly.sdk.android.LDConfig.Builder#http(ComponentConfigurer)}:
+ *
+ * Note that this class is abstract; the actual implementation is created by calling {@link Components#httpConfiguration()}.
+ *
+ * @since 3.3.0
+ */
+public abstract class HttpConfigurationBuilder implements ComponentConfigurer
+ * The default is {@link #DEFAULT_CONNECT_TIMEOUT_MILLIS}.
+ *
+ * @param connectTimeoutMillis the connection timeout in milliseconds
+ * @return the builder
+ */
+ public HttpConfigurationBuilder connectTimeoutMillis(int connectTimeoutMillis) {
+ this.connectTimeoutMillis = connectTimeoutMillis <= 0 ? DEFAULT_CONNECT_TIMEOUT_MILLIS :
+ connectTimeoutMillis;
+ return this;
+ }
+
+ /**
+ * Provides a callback for dynamically modifying headers used on requests to LaunchDarkly services.
+ *
+ * @param headerTransform the transformation to apply to requests
+ * @return the builder
+ */
+ public HttpConfigurationBuilder headerTransform(LDHeaderUpdater headerTransform) {
+ this.headerTransform = headerTransform;
+ return this;
+ }
+
+ /**
+ * Sets whether to use the HTTP REPORT method for feature flag requests.
+ *
+ * By default, polling and streaming connections are made with the GET method, with the context
+ * data encoded into the request URI. Using REPORT allows the user data to be sent in the request
+ * body instead, which is somewhat more secure and efficient.
+ *
+ * However, the REPORT method is not always supported by operating systems or network gateways.
+ * Therefore it is disabled in the SDK by default. You can enable it if you know your code will
+ * not be running in an environment that disallows REPORT.
+ *
+ * @param useReport true to enable the REPORT method
+ * @return the builder
+ */
+ public HttpConfigurationBuilder useReport(boolean useReport) {
+ this.useReport = useReport;
+ return this;
+ }
+
+ /**
+ * For use by wrapper libraries to set an identifying name for the wrapper being used. This will be included in a
+ * header during requests to the LaunchDarkly servers to allow recording metrics on the usage of
+ * these wrapper libraries.
+ *
+ * @param wrapperName an identifying name for the wrapper library
+ * @param wrapperVersion version string for the wrapper library
+ * @return the builder
+ */
+ public HttpConfigurationBuilder wrapper(String wrapperName, String wrapperVersion) {
+ this.wrapperName = wrapperName;
+ this.wrapperVersion = wrapperVersion;
+ return this;
+ }
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/PollingDataSourceBuilder.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/PollingDataSourceBuilder.java
new file mode 100644
index 00000000..f8cf01ee
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/PollingDataSourceBuilder.java
@@ -0,0 +1,77 @@
+package com.launchdarkly.sdk.android.integrations;
+
+import com.launchdarkly.sdk.android.Components;
+import com.launchdarkly.sdk.android.LDConfig;
+import com.launchdarkly.sdk.android.LDConfig.Builder;
+import com.launchdarkly.sdk.android.subsystems.ComponentConfigurer;
+import com.launchdarkly.sdk.android.subsystems.DataSource;
+
+/**
+ * Contains methods for configuring the polling data source.
+ *
+ * Polling is not the default behavior; by default, the SDK uses a streaming connection to receive
+ * feature flag data from LaunchDarkly whenever the application is in the foreground. In polling
+ * mode, the SDK instead makes a new HTTP request to LaunchDarkly at regular intervals. HTTP
+ * caching allows it to avoid redundantly downloading data if there have been no changes, but
+ * polling is still less efficient than streaming and should only be used on the advice of
+ * LaunchDarkly support.
+ *
+ * To use polling mode, create a builder with {@link Components#pollingDataSource()}, set any custom
+ * options if desired with the methods of this class, and pass it to
+ * {@link Builder#dataSource(ComponentConfigurer)}:
+ *
+ * Note that this class is abstract; the actual implementation is created by calling
+ * {@link Components#pollingDataSource()}.
+ *
+ * @since 3.3.0
+ */
+public abstract class PollingDataSourceBuilder implements ComponentConfigurer
+ * This is normally a longer interval than the foreground polling interval ({@link #pollIntervalMillis(int)}).
+ * It is ignored if you have turned off background polling entirely by setting
+ * {@link Builder#disableBackgroundUpdating(boolean)}.
+ *
+ * The default value is {@link LDConfig#DEFAULT_BACKGROUND_POLL_INTERVAL_MILLIS}; the minimum
+ * is {@link LDConfig#MIN_BACKGROUND_POLL_INTERVAL_MILLIS}.
+ *
+ * @param backgroundPollIntervalMillis the background polling interval in milliseconds
+ * @return the builder
+ * @see #pollIntervalMillis(int)
+ */
+ public PollingDataSourceBuilder backgroundPollIntervalMillis(int backgroundPollIntervalMillis) {
+ this.backgroundPollIntervalMillis = backgroundPollIntervalMillis < LDConfig.MIN_BACKGROUND_POLL_INTERVAL_MILLIS ?
+ LDConfig.MIN_BACKGROUND_POLL_INTERVAL_MILLIS : backgroundPollIntervalMillis;
+ return this;
+ }
+
+ /**
+ * Sets the interval between feature flag updates when the application is running in the foreground.
+ *
+ * The default value is {@link LDConfig#DEFAULT_BACKGROUND_POLL_INTERVAL_MILLIS}. That is also
+ * the minimum value.
+ *
+ * @param pollIntervalMillis the reconnect time base value in milliseconds
+ * @return the builder
+ * @see #backgroundPollIntervalMillis(int)
+ */
+ public PollingDataSourceBuilder pollIntervalMillis(int pollIntervalMillis) {
+ this.pollIntervalMillis = pollIntervalMillis <= DEFAULT_POLL_INTERVAL_MILLIS ?
+ DEFAULT_POLL_INTERVAL_MILLIS : pollIntervalMillis;
+ return this;
+ }
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/ServiceEndpointsBuilder.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/ServiceEndpointsBuilder.java
new file mode 100644
index 00000000..db032135
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/ServiceEndpointsBuilder.java
@@ -0,0 +1,242 @@
+package com.launchdarkly.sdk.android.integrations;
+
+import android.net.Uri;
+
+import com.launchdarkly.sdk.android.Components;
+import com.launchdarkly.sdk.android.LDConfig;
+import com.launchdarkly.sdk.android.subsystems.ServiceEndpoints;
+
+import java.net.URI;
+
+/**
+ * Contains methods for configuring the SDK's service URIs.
+ *
+ * If you want to set non-default values for any of these properties, create a builder with {@link Components#serviceEndpoints()},
+ * change its properties with the methods of this class, and pass it to {@link LDConfig.Builder#serviceEndpoints(ServiceEndpointsBuilder)}.
+ *
+ * The default behavior, if you do not change any of these properties, is that the SDK will connect to the standard endpoints
+ * in the LaunchDarkly production service. There are several use cases for changing these properties:
+ *
+ * Each of the setter methods can be called with either a {@link URI} or an equivalent string.
+ * Passing a string that is not a valid URI will cause an immediate {@link IllegalArgumentException}.
+ *
+ * If you are using a private instance and you set some of the base URIs, but not all of them, the SDK
+ * will log an error and may not work properly. The only exception is if you have explicitly disabled
+ * the SDK's use of one of the services: for instance, if you have disabled analytics events, you do
+ * not have to set {@link #events(URI)}.
+ *
+ *
+ * You should only call this method if you are using a private instance or test fixture
+ * (see {@link ServiceEndpointsBuilder}). If you are using the LaunchDarkly Relay Proxy,
+ * call {@link #relayProxy(URI)} instead.
+ *
+ * You should only call this method if you are using a private instance or test fixture
+ * (see {@link ServiceEndpointsBuilder}). If you are using the LaunchDarkly Relay Proxy,
+ * call {@link #relayProxy(URI)} instead.
+ *
+ * When using the LaunchDarkly Relay Proxy, the SDK only needs to know the single base URI
+ * of the Relay Proxy, which will provide all the proxied service endpoints.
+ *
+ * You should only call this method if you are using a private instance or test fixture
+ * (see {@link ServiceEndpointsBuilder}). If you are using the LaunchDarkly Relay Proxy,
+ * call {@link #relayProxy(URI)} instead.
+ *
+ * By default, the SDK uses a streaming connection to receive feature flag data from LaunchDarkly. If you want
+ * to customize the behavior of the connection, create a builder with {@link Components#streamingDataSource()},
+ * change its properties with the methods of this class, and pass it to {@link Builder#dataSource(ComponentConfigurer)}:
+ *
+ * Note that this class is abstract; the actual implementation is created by calling {@link Components#streamingDataSource()}.
+ *
+ * @since 3.3.0
+ */
+public abstract class StreamingDataSourceBuilder implements ComponentConfigurer
+ * Even when configured to use streaming, the SDK will switch to polling when in the background
+ * (unless {@link Builder#disableBackgroundUpdating(boolean)} is set). This property determines
+ * how often polling will happen.
+ *
+ * The default value is {@link LDConfig#DEFAULT_BACKGROUND_POLL_INTERVAL_MILLIS}; the minimum
+ * is {@link LDConfig#MIN_BACKGROUND_POLL_INTERVAL_MILLIS}.
+ *
+ * @param backgroundPollIntervalMillis the reconnect time base value in milliseconds
+ * @return the builder
+ */
+ public StreamingDataSourceBuilder backgroundPollIntervalMillis(int backgroundPollIntervalMillis) {
+ this.backgroundPollIntervalMillis = backgroundPollIntervalMillis < LDConfig.MIN_BACKGROUND_POLL_INTERVAL_MILLIS ?
+ LDConfig.MIN_BACKGROUND_POLL_INTERVAL_MILLIS : backgroundPollIntervalMillis;
+ return this;
+ }
+
+ /**
+ * Sets the initial reconnect delay for the streaming connection.
+ *
+ * The streaming service uses a backoff algorithm (with jitter) every time the connection needs
+ * to be reestablished. The delay for the first reconnection will start near this value, and then
+ * increase exponentially for any subsequent connection failures.
+ *
+ * The default value is {@link #DEFAULT_INITIAL_RECONNECT_DELAY_MILLIS}.
+ *
+ * @param initialReconnectDelayMillis the reconnect time base value in milliseconds
+ * @return the builder
+ */
+ public StreamingDataSourceBuilder initialReconnectDelayMillis(int initialReconnectDelayMillis) {
+ this.initialReconnectDelayMillis = initialReconnectDelayMillis <= 0 ? 0 :
+ initialReconnectDelayMillis;
+ return this;
+ }
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/ClientContext.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/ClientContext.java
new file mode 100644
index 00000000..7d99e00b
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/ClientContext.java
@@ -0,0 +1,151 @@
+package com.launchdarkly.sdk.android.subsystems;
+
+import android.app.Application;
+
+import com.launchdarkly.logging.LDLogger;
+import com.launchdarkly.sdk.android.LDClient;
+import com.launchdarkly.sdk.android.LDConfig;
+
+/**
+ * Configuration information provided by the {@link com.launchdarkly.sdk.android.LDClient} when
+ * creating components.
+ *
+ * The getter methods in this class provide information about the initial configuration of the
+ * client. This includes properties from {@link LDConfig}, and also values that are computed
+ * during initialization. It is preferable for components to copy properties from this class rather
+ * than to retain a reference to the entire {@link LDConfig} object.
+ *
+ * The actual implementation class may contain other properties that are only relevant to the built-in
+ * SDK components and are therefore not part of this base class; this allows the SDK to add its own
+ * context information as needed without disturbing the public API.
+ *
+ * All properties of this object are immutable; they are set at initialization time and do not
+ * reflect any later state changes in the client.
+ *
+ * @since 3.3.0
+ */
+public class ClientContext {
+ private final Application application;
+ private final LDLogger baseLogger;
+ private final LDConfig config;
+ private final boolean evaluationReasons;
+ private final String environmentName;
+ private final HttpConfiguration http;
+ private final boolean initiallySetOffline;
+ private final String mobileKey;
+ private final ServiceEndpoints serviceEndpoints;
+
+ public ClientContext(
+ Application application,
+ String mobileKey,
+ LDLogger baseLogger,
+ LDConfig config,
+ String environmentName,
+ boolean evaluationReasons,
+ HttpConfiguration http,
+ boolean initiallySetOffline,
+ ServiceEndpoints serviceEndpoints
+ ) {
+ this.application = application;
+ this.mobileKey = mobileKey;
+ this.baseLogger = baseLogger;
+ this.config = config;
+ this.environmentName = environmentName;
+ this.evaluationReasons = evaluationReasons;
+ this.http = http;
+ this.initiallySetOffline = initiallySetOffline;
+ this.serviceEndpoints = serviceEndpoints;
+ }
+
+ protected ClientContext(ClientContext copyFrom) {
+ this(
+ copyFrom.application,
+ copyFrom.mobileKey,
+ copyFrom.baseLogger,
+ copyFrom.config,
+ copyFrom.environmentName,
+ copyFrom.evaluationReasons,
+ copyFrom.http,
+ copyFrom.initiallySetOffline,
+ copyFrom.serviceEndpoints
+ );
+ }
+
+ /**
+ * The Android application object.
+ * @return the application
+ */
+ public Application getApplication() {
+ return application;
+ }
+
+ /**
+ * The base logger for the SDK.
+ * @return a logger instance
+ */
+ public LDLogger getBaseLogger() {
+ return baseLogger;
+ }
+
+ /**
+ * Returns the full configuration object. THIS IS A TEMPORARY METHOD that will be removed prior
+ * to release-- the goal is to NOT retain the full LDConfig in these components, but until we
+ * have moved more of the config properties into subconfiguration builders, this is necessary.
+ * @return the configuration object
+ */
+ public LDConfig getConfig() {
+ return config;
+ }
+
+ /**
+ * Returns the configured environment name.
+ * @return the environment name
+ */
+ public String getEnvironmentName() {
+ return environmentName;
+ }
+
+ /**
+ * Returns true if evaluation reasons are enabled.
+ * @return true if evaluation reasons are enabled
+ */
+ public boolean isEvaluationReasons() {
+ return evaluationReasons;
+ }
+
+ /**
+ * Returns the HTTP configuration.
+ * @return the HTTP configuration
+ */
+ public HttpConfiguration getHttp() {
+ return http;
+ }
+
+ /**
+ * Returns true if the initial configuration specified that the SDK should be offline.
+ * @return true if initially set to be offline
+ */
+ public boolean isInitiallySetOffline() {
+ return initiallySetOffline;
+ }
+
+ /**
+ * Returns the configured mobile key.
+ *
+ * In multi-environment mode, there is a separate {@link ClientContext} for each environment,
+ * corresponding to the {@link LDClient} instance for that environment.
+ *
+ * @return the mobile key
+ */
+ public String getMobileKey() {
+ return mobileKey;
+ }
+
+ /**
+ * Returns the base service URIs used by SDK components.
+ * @return the service endpoint URIs
+ */
+ public ServiceEndpoints getServiceEndpoints() {
+ return serviceEndpoints;
+ }
+}
\ No newline at end of file
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/ComponentConfigurer.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/ComponentConfigurer.java
new file mode 100644
index 00000000..7a25e5de
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/ComponentConfigurer.java
@@ -0,0 +1,20 @@
+package com.launchdarkly.sdk.android.subsystems;
+
+/**
+ * The common interface for SDK component factories and configuration builders. Applications should not
+ * need to implement this interface.
+ *
+ * @param
+ * Currently, this is a simple container for configuration properties. In the future, it will become
+ * a real component interface allowing for custom behavior, as it is in the server-side Java SDK.
+ *
+ * @since 3.3.0
+ * @see Components#streamingDataSource()
+ * @see Components#pollingDataSource()
+ * @see LDConfig.Builder#dataSource(ComponentConfigurer)
+ */
+public interface DataSource {
+ /**
+ * Returns true if streaming is disabled.
+ * @return true if streaming is disabled
+ */
+ boolean isStreamingDisabled();
+
+ /**
+ * Returns the configured background polling interval.
+ * @return the background polling interval in milliseconds
+ */
+ int getBackgroundPollIntervalMillis();
+
+ /**
+ * Returns the configured initial stream reconnect delay.
+ * @return the initial stream reconnect delay in milliseconds, or zero if streaming is disabled
+ */
+ int getInitialReconnectDelayMillis();
+
+ /**
+ * Returns the configured foreground polling interval.
+ * @return the foreground polling interval in milliseconds, or zero if streaming is enabled
+ */
+ int getPollIntervalMillis();
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/DiagnosticDescription.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/DiagnosticDescription.java
new file mode 100644
index 00000000..601693a8
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/DiagnosticDescription.java
@@ -0,0 +1,27 @@
+package com.launchdarkly.sdk.android.subsystems;
+
+import com.launchdarkly.sdk.LDValue;
+
+/**
+ * Optional interface for components to describe their own configuration.
+ *
+ * The SDK uses a simplified JSON representation of its configuration when recording diagnostics data.
+ * Any class that implements {@link ComponentConfigurer} may choose to contribute
+ * values to this representation, although the SDK may or may not use them. For components that do not
+ * implement this interface, the SDK may instead describe them using {@code getClass().getSimpleName()}.
+ *
+ * The {@link #describeConfiguration(ClientContext)} method should return either null or a JSON value. For
+ * custom components, the value must be a string that describes the basic nature of this component
+ * implementation (e.g. "Redis"). Built-in LaunchDarkly components may instead return a JSON object
+ * containing multiple properties specific to the LaunchDarkly diagnostic schema.
+ *
+ * @since 3.3.0
+ */
+public interface DiagnosticDescription {
+ /**
+ * Used internally by the SDK to inspect the configuration.
+ * @param clientContext allows access to the client configuration
+ * @return an {@link LDValue} or null
+ */
+ LDValue describeConfiguration(ClientContext clientContext);
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/EventProcessor.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/EventProcessor.java
new file mode 100644
index 00000000..4a093e6e
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/EventProcessor.java
@@ -0,0 +1,116 @@
+package com.launchdarkly.sdk.android.subsystems;
+
+import com.launchdarkly.sdk.EvaluationDetail;
+import com.launchdarkly.sdk.EvaluationReason;
+import com.launchdarkly.sdk.LDUser;
+import com.launchdarkly.sdk.LDValue;
+
+import java.io.Closeable;
+
+/**
+ * Interface for an object that can send or store analytics events.
+ *
+ * Application code normally does not need to interact with this interface. It is provided
+ * to allow a custom implementation or test fixture to be substituted for the SDK's normal
+ * analytics event logic.
+ *
+ * @since 3.3.0
+ */
+public interface EventProcessor extends Closeable {
+ /**
+ * Constant used with {@link #recordEvaluationEvent}.
+ */
+ public static final int NO_VERSION = -1;
+
+ /**
+ * Records the action of evaluating a feature flag.
+ *
+ * Depending on the feature flag properties and event properties, this may be transmitted to
+ * the events service as an individual event, or may only be added into summary data.
+ *
+ * @param user the current user
+ * @param flagKey key of the feature flag that was evaluated
+ * @param flagVersion the version of the flag, or {@link #NO_VERSION} if the flag was not found
+ * @param variation the result variation index, or {@link EvaluationDetail#NO_VARIATION} if evaluation failed
+ * @param value the result value
+ * @param reason the evaluation reason, or null if the reason was not requested
+ * @param defaultValue the default value parameter for the evaluation
+ * @param requireFullEvent true if full-fidelity analytics events should be sent for this flag
+ * @param debugEventsUntilDate if non-null, debug events are to be generated until this millisecond time
+ */
+ void recordEvaluationEvent(
+ LDUser user,
+ String flagKey,
+ int flagVersion,
+ int variation,
+ LDValue value,
+ EvaluationReason reason,
+ LDValue defaultValue,
+ boolean requireFullEvent,
+ Long debugEventsUntilDate
+ );
+
+ /**
+ * Registers an evaluation context, as when the SDK's {@code identify} method is called.
+ *
+ * @param user the current user
+ */
+ void recordIdentifyEvent(
+ LDUser user
+ );
+
+ /**
+ * Creates a custom event, as when the SDK's {@code track} method is called.
+ *
+ * @param user the current user
+ * @param eventKey the event key
+ * @param data optional custom data provided for the event, may be null or {@link LDValue#ofNull()} if not used
+ * @param metricValue optional numeric metric value provided for the event, or null
+ */
+ void recordCustomEvent(
+ LDUser user,
+ String eventKey,
+ LDValue data,
+ Double metricValue
+ );
+
+ /**
+ * Creates an alias event, as when the SDK's {@code alias} method is called.
+ *
+ * @param user the current user
+ * @param previousUser the previous user
+ */
+ void recordAliasEvent(
+ LDUser user,
+ LDUser previousUser
+ );
+
+ /**
+ * Starts any periodic tasks used by the event processor.
+ */
+ void start();
+
+ /**
+ * Stops any periodic tasks used by the event processor.
+ */
+ void stop();
+
+ /**
+ * Puts the event processor into offline mode if appropriate
+ * @param offline true if the SDK has been put offline
+ */
+ void setOffline(boolean offline);
+
+ /**
+ * Specifies that any buffered events should be sent as soon as possible, rather than waiting
+ * for the next flush interval. This method is asynchronous, so events still may not be sent
+ * until a later time. However, calling {@link Closeable#close()} will synchronously deliver
+ * any events that were not yet delivered prior to shutting down.
+ */
+ void flush();
+
+ /**
+ * Specifies that any buffered events should be sent immediately, blocking until done.
+ */
+ void blockingFlush();
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/HttpConfiguration.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/HttpConfiguration.java
new file mode 100644
index 00000000..a0257cc2
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/HttpConfiguration.java
@@ -0,0 +1,87 @@
+package com.launchdarkly.sdk.android.subsystems;
+
+import com.launchdarkly.sdk.android.LDHeaderUpdater;
+import com.launchdarkly.sdk.android.integrations.HttpConfigurationBuilder;
+
+import java.util.HashMap;
+import java.util.Map;
+
+import static java.util.Collections.emptyMap;
+
+/**
+ * Encapsulates top-level HTTP configuration that applies to all SDK components.
+ *
+ * Use {@link HttpConfigurationBuilder} to construct an instance.
+ *
+ * The SDK's built-in components use OkHttp as the HTTP client implementation, but since OkHttp types
+ * are not surfaced in the public API and custom components might use some other implementation, this
+ * class only provides the properties that would be used to create an HTTP client; it does not create
+ * the client itself. SDK implementation code uses its own helper methods to do so.
+ *
+ * @since 3.3.0
+ */
+public final class HttpConfiguration {
+ private final int connectTimeoutMillis;
+ private final Map
+ * See {@link ServiceEndpointsBuilder} for more details on these properties.
+ *
+ * @since 3.3.0
+ */
+public final class ServiceEndpoints {
+ private final URI streamingBaseUri;
+ private final URI pollingBaseUri;
+ private final URI eventsBaseUri;
+
+ /**
+ * Used internally by the SDK to store service endpoints.
+ * @param streamingBaseUri the base URI for the streaming service
+ * @param pollingBaseUri the base URI for the polling service
+ * @param eventsBaseUri the base URI for the events service
+ */
+ public ServiceEndpoints(URI streamingBaseUri, URI pollingBaseUri, URI eventsBaseUri) {
+ this.streamingBaseUri = streamingBaseUri;
+ this.pollingBaseUri = pollingBaseUri;
+ this.eventsBaseUri = eventsBaseUri;
+ }
+
+ /**
+ * The base URI for the streaming service.
+ * @return the base URI, or null
+ */
+ public URI getStreamingBaseUri() {
+ return streamingBaseUri;
+ }
+
+ /**
+ * The base URI for the polling service.
+ * @return the base URI, or null
+ */
+ public URI getPollingBaseUri() {
+ return pollingBaseUri;
+ }
+
+ /**
+ * The base URI for the events service.
+ * @return the base URI, or null
+ */
+ public URI getEventsBaseUri() {
+ return eventsBaseUri;
+ }
+}
+ *
+ * @param dataSourceConfigurer the data source configuration builder
+ * @return the main configuration builder
+ * @see Components#streamingDataSource()
+ * @see Components#pollingDataSource()
+ * @since 3.3.0
+ */
+ public LDConfig.Builder dataSource(ComponentConfigurer
+ * // Setting custom options when using streaming mode
+ * LDConfig config = new LDConfig.Builder()
+ * .dataSource(
+ * Components.streamingDataSource()
+ * .initialReconnectDelayMillis(100)
+ * )
+ * .build();
+ *
+ * // Using polling mode instead of streaming, and setting custom options for polling
+ * LDConfig config = new LDConfig.Builder()
+ * .dataSource(
+ * Components.pollingDataSource()
+ * .pollingIntervalMillis(60_000)
+ * )
+ * .build();
+ *
+ *
+ * @param eventsConfigurer the events configuration builder
+ * @return the main configuration builder
+ * @since 3.3.0
+ * @see Components#sendEvents()
+ * @see Components#noEvents()
+ */
+ public LDConfig.Builder events(ComponentConfigurer
+ * // Setting custom event processing options
+ * LDConfig config = new LDConfig.Builder()
+ * .events(Components.sendEvents().capacity(100))
+ * .build();
+ *
+ * // Disabling events
+ * LDConfig config = new LDConfig.Builder()
+ * .events(Components.noEvents())
+ * .build();
+ *
+ *
+ * @param httpConfigurer the HTTP configuration builder
+ * @return the main configuration builder
+ * @since 3.3.0
+ * @see Components#httpConfiguration()
+ */
+ public Builder http(ComponentConfigurer
+ * LDConfig config = new LDConfig.Builder()
+ * .http(Components.httpConfiguration().connectTimeoutMillis(5000))
+ * .build();
+ *
+ *
+ * @param serviceEndpointsBuilder a configuration builder object returned by {@link Components#serviceEndpoints()}
+ * @return the builder
+ * @since 3.3.0
+ */
+ public Builder serviceEndpoints(ServiceEndpointsBuilder serviceEndpointsBuilder) {
+ this.serviceEndpointsBuilder = serviceEndpointsBuilder;
+ return this;
+ }
+
+ /**
+ * Deprecated method for setting the capacity of the event buffer.
*
+ * LDConfig config = new LDConfig.Builder().mobileKey("key")
+ * .serviceEndpoints(
+ * Components.serviceEndpoints().relayProxy("http://my-relay-proxy-host")
+ * );
+ *
+ *
+ * LDConfig config = new LDConfig.Builder()
+ * .events(Components.sendEvents().capacity(500).flushIntervalMillis(2000))
+ * .build();
+ *
+ *
+ * LDConfig config = new LDConfig.Builder()
+ * .http(
+ * Components.httpConfiguration()
+ * .connectTimeoutMillis(3000)
+ * .proxyHostAndPort("my-proxy", 8080)
+ * )
+ * .build();
+ *
+ *
+ * LDConfig config = new LDConfig.Builder()
+ * .dataSource(Components.pollingDataSource().pollIntervalMillis(30000))
+ * .build();
+ *
+ *
+ *
+ *
+ * @since 3.3.0
+ */
+public abstract class ServiceEndpointsBuilder {
+ protected URI streamingBaseUri;
+ protected URI pollingBaseUri;
+ protected URI eventsBaseUri;
+
+ /**
+ * Sets a custom base URI for the events service.
+ *
+ * // Example of specifying a Relay Proxy instance
+ * LDConfig config = new LDConfig.Builder()
+ * .serviceEndpoints(
+ * Components.serviceEndpoints()
+ * .relayProxy("http://my-relay-hostname:80")
+ * )
+ * .build();
+ *
+ * // Example of specifying a private LaunchDarkly instance
+ * LDConfig config = new LDConfig.Builder()
+ * .serviceEndpoints(
+ * Components.serviceEndpoints()
+ * .streaming("https://stream.mycompany.launchdarkly.com")
+ * .polling("https://app.mycompany.launchdarkly.com")
+ * .events("https://events.mycompany.launchdarkly.com"))
+ * )
+ * .build();
+ *
+ *
+ * @param eventsBaseUri the base URI of the events service; null to use the default
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder events(URI eventsBaseUri) {
+ this.eventsBaseUri = eventsBaseUri;
+ return this;
+ }
+
+ /**
+ * Equivalent to {@link #events(URI)}, specifying the URI as a string.
+ * @param eventsBaseUri the base URI of the events service; null to use the default
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder events(String eventsBaseUri) {
+ return events(eventsBaseUri == null ? null : URI.create(eventsBaseUri));
+ }
+
+ /**
+ * Equivalent to {@link #events(URI)}, specifying the URI as an {@code android.net.Uri}.
+ * @param eventsBaseUri the base URI of the events service; null to use the default
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder events(Uri eventsBaseUri) {
+ return events(eventsBaseUri == null ? null : URI.create(eventsBaseUri.toString()));
+ }
+
+ /**
+ * Sets a custom base URI for the polling service.
+ *
+ * LDConfig config = new LDConfig.Builder()
+ * .serviceEndpoints(
+ * Components.serviceEndpoints()
+ * .streaming("https://stream.mycompany.launchdarkly.com")
+ * .polling("https://app.mycompany.launchdarkly.com")
+ * .events("https://events.mycompany.launchdarkly.com")
+ * )
+ * .build();
+ *
+ *
+ * @param pollingBaseUri the base URI of the polling service; null to use the default
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder polling(URI pollingBaseUri) {
+ this.pollingBaseUri = pollingBaseUri;
+ return this;
+ }
+
+ /**
+ * Equivalent to {@link #polling(URI)}, specifying the URI as a string.
+ * @param pollingBaseUri the base URI of the events service; null to use the default
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder polling(String pollingBaseUri) {
+ return polling(pollingBaseUri == null ? null : URI.create(pollingBaseUri));
+ }
+
+ /**
+ * Equivalent to {@link #polling(URI)}, specifying the URI as an {@code android.net.Uri}.
+ * @param pollingBaseUri the base URI of the events service; null to use the default
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder polling(Uri pollingBaseUri) {
+ return polling(pollingBaseUri == null ? null : URI.create(pollingBaseUri.toString()));
+ }
+
+ /**
+ * Specifies a single base URI for a Relay Proxy instance.
+ *
+ * LDConfig config = new LDConfig.Builder()
+ * .serviceEndpoints(
+ * Components.serviceEndpoints()
+ * .streaming("https://stream.mycompany.launchdarkly.com")
+ * .polling("https://app.mycompany.launchdarkly.com")
+ * .events("https://events.mycompany.launchdarkly.com")
+ * )
+ * .build();
+ *
+ *
+ * @param relayProxyBaseUri the Relay Proxy base URI, or null to reset to default endpoints
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder relayProxy(URI relayProxyBaseUri) {
+ this.eventsBaseUri = relayProxyBaseUri;
+ this.pollingBaseUri = relayProxyBaseUri;
+ this.streamingBaseUri = relayProxyBaseUri;
+ return this;
+ }
+
+ /**
+ * Equivalent to {@link #relayProxy(URI)}, specifying the URI as a string.
+ * @param relayProxyBaseUri the Relay Proxy base URI, or null to reset to default endpoints
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder relayProxy(String relayProxyBaseUri) {
+ return relayProxy(relayProxyBaseUri == null ? null : URI.create(relayProxyBaseUri));
+ }
+
+ /**
+ * Equivalent to {@link #relayProxy(URI)}, specifying the URI as an {@code android.net.Uri}.
+ * @param relayProxyBaseUri the Relay Proxy base URI, or null to reset to default endpoints
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder relayProxy(Uri relayProxyBaseUri) {
+ return relayProxy(relayProxyBaseUri == null ? null : URI.create(relayProxyBaseUri.toString()));
+ }
+
+ /**
+ * Sets a custom base URI for the streaming service.
+ *
+ * LDConfig config = new LDConfig.Builder()
+ * .serviceEndpoints(
+ * Components.serviceEndpoints()
+ * .relayProxy("http://my-relay-hostname:8080")
+ * )
+ * .build();
+ *
+ *
+ * @param streamingBaseUri the base URI of the streaming service; null to use the default
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder streaming(URI streamingBaseUri) {
+ this.streamingBaseUri = streamingBaseUri;
+ return this;
+ }
+
+ /**
+ * Equivalent to {@link #streaming(URI)}, specifying the URI as a string.
+ * @param streamingBaseUri the base URI of the events service; null to use the default
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder streaming(String streamingBaseUri) {
+ return streaming(streamingBaseUri == null ? null : URI.create(streamingBaseUri));
+ }
+
+ /**
+ * Equivalent to {@link #streaming(URI)}, specifying the URI as an {@code android.net.Uri}.
+ * @param streamingBaseUri the base URI of the events service; null to use the default
+ * @return the builder
+ */
+ public ServiceEndpointsBuilder streaming(Uri streamingBaseUri) {
+ return streaming(streamingBaseUri == null ? null : URI.create(streamingBaseUri.toString()));
+ }
+
+ /**
+ * Called internally by the SDK to create a configuration instance. Applications do not need
+ * to call this method.
+ * @return the configuration object
+ */
+ abstract public ServiceEndpoints build();
+}
diff --git a/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/StreamingDataSourceBuilder.java b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/StreamingDataSourceBuilder.java
new file mode 100644
index 00000000..e969dcce
--- /dev/null
+++ b/launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/integrations/StreamingDataSourceBuilder.java
@@ -0,0 +1,70 @@
+package com.launchdarkly.sdk.android.integrations;
+
+import com.launchdarkly.sdk.android.Components;
+import com.launchdarkly.sdk.android.LDConfig;
+import com.launchdarkly.sdk.android.LDConfig.Builder;
+import com.launchdarkly.sdk.android.subsystems.ComponentConfigurer;
+import com.launchdarkly.sdk.android.subsystems.DataSource;
+
+/**
+ * Contains methods for configuring the streaming data source.
+ *
+ * LDConfig config = new LDConfig.Builder()
+ * .serviceEndpoints(
+ * Components.serviceEndpoints()
+ * .streaming("https://stream.mycompany.launchdarkly.com")
+ * .polling("https://app.mycompany.launchdarkly.com")
+ * .events("https://events.mycompany.launchdarkly.com")
+ * )
+ * .build();
+ *
+ *
+ * LDConfig config = new LDConfig.Builder()
+ * .dataSource(Components.streamingDataSource().initialReconnectDelayMillis(500))
+ * .build();
+ *