refactor: switch to Approach 2 for FDv2 mode resolution and switching

Replace Approach 1 implementation with Approach 2, which the team
preferred for its cleaner architecture:

- ConnectivityManager owns the resolved mode table and performs
  ModeState -> ConnectionMode -> ResolvedModeDefinition lookup
- FDv2DataSource receives ResolvedModeDefinition via switchMode()
  and has no internal mode table
- FDv2DataSourceBuilder uses a unified ComponentConfigurer-based
  code path for both production and test mode tables
- ResolvedModeDefinition is a top-level class rather than an inner
  class of FDv2DataSource
- ConnectionMode is a final class with static instances instead of
  a Java enum

Made-with: Cursor

Author: aaron-zeisler

docs/SDK-1956-development-plan.md

@@ -1,16 +1,16 @@
 package com.launchdarkly.sdk.android;
 
-import androidx.annotation.Nullable;
-
 import com.launchdarkly.logging.LDLogger;
 import com.launchdarkly.sdk.LDContext;
 import com.launchdarkly.sdk.android.env.IEnvironmentReporter;
 import com.launchdarkly.sdk.android.subsystems.ClientContext;
-import com.launchdarkly.sdk.android.subsystems.HttpConfiguration;
 import com.launchdarkly.sdk.android.subsystems.DataSourceUpdateSink;
+import com.launchdarkly.sdk.android.subsystems.HttpConfiguration;
 import com.launchdarkly.sdk.android.subsystems.TransactionalDataStore;
 import com.launchdarkly.sdk.internal.events.DiagnosticStore;
 
+import androidx.annotation.Nullable;
+
 /**
  * This package-private subclass of {@link ClientContext} contains additional non-public SDK objects
  * that may be used by our internal components.
@@ -36,6 +36,7 @@ final class ClientContextImpl extends ClientContext {
     private final PlatformState platformState;
     private final TaskExecutor taskExecutor;
     private final PersistentDataStoreWrapper.PerEnvironmentData perEnvironmentData;
+    @Nullable
     private final TransactionalDataStore transactionalDataStore;
 
     ClientContextImpl(
@@ -56,7 +57,7 @@ final class ClientContextImpl extends ClientContext {
             PlatformState platformState,
             TaskExecutor taskExecutor,
             PersistentDataStoreWrapper.PerEnvironmentData perEnvironmentData,
-            TransactionalDataStore transactionalDataStore
+            @Nullable TransactionalDataStore transactionalDataStore
     ) {
         super(base);
         this.diagnosticStore = diagnosticStore;
@@ -119,22 +120,19 @@ public static ClientContextImpl forDataSource(
             boolean newInBackground,
             Boolean previouslyInBackground
     ) {
-        return forDataSource(baseClientContext, dataSourceUpdateSink, null,
-                newEvaluationContext, newInBackground, previouslyInBackground);
+        return forDataSource(baseClientContext, dataSourceUpdateSink, newEvaluationContext,
+                newInBackground, previouslyInBackground, null);
     }
 
     public static ClientContextImpl forDataSource(
             ClientContext baseClientContext,
             DataSourceUpdateSink dataSourceUpdateSink,
-            @Nullable TransactionalDataStore transactionalDataStore,
             LDContext newEvaluationContext,
             boolean newInBackground,
-            Boolean previouslyInBackground
+            Boolean previouslyInBackground,
+            @Nullable TransactionalDataStore transactionalDataStore
     ) {
         ClientContextImpl baseContextImpl = ClientContextImpl.get(baseClientContext);
-        TransactionalDataStore store = transactionalDataStore != null
-                ? transactionalDataStore
-                : baseContextImpl.transactionalDataStore;
         return new ClientContextImpl(
                 new ClientContext(
                         baseClientContext.getMobileKey(),
@@ -156,7 +154,7 @@ public static ClientContextImpl forDataSource(
                 baseContextImpl.getPlatformState(),
                 baseContextImpl.getTaskExecutor(),
                 baseContextImpl.getPerEnvironmentData(),
-                store
+                transactionalDataStore
         );
     }
 
@@ -197,6 +195,7 @@ public PersistentDataStoreWrapper.PerEnvironmentData getPerEnvironmentData() {
         return throwExceptionIfNull(perEnvironmentData);
     }
 
+    @Nullable
     public TransactionalDataStore getTransactionalDataStore() {
         return transactionalDataStore;
     }

launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/ClientContextImpl.java

@@ -1,17 +1,34 @@
 package com.launchdarkly.sdk.android;
 
 /**
- * Named connection modes for the FDv2 data system. Each mode maps to a
- * {@link ModeDefinition} that specifies which initializers and synchronizers to run.
+ * Enumerates the built-in FDv2 connection modes. Each mode maps to a
+ * {@link ModeDefinition} that specifies which initializers and synchronizers
+ * are active when the SDK is operating in that mode.
+ * <p>
+ * This is a closed enum — custom connection modes (spec 5.3.5 TBD) are not
+ * supported in this release.
  * <p>
  * Package-private — not part of the public SDK API.
  *
  * @see ModeDefinition
+ * @see ModeResolutionTable
  */
-enum ConnectionMode {
-    STREAMING,
-    POLLING,
-    OFFLINE,
-    ONE_SHOT,
-    BACKGROUND
+final class ConnectionMode {
+
+    static final ConnectionMode STREAMING = new ConnectionMode("STREAMING");
+    static final ConnectionMode POLLING = new ConnectionMode("POLLING");
+    static final ConnectionMode OFFLINE = new ConnectionMode("OFFLINE");
+    static final ConnectionMode ONE_SHOT = new ConnectionMode("ONE_SHOT");
+    static final ConnectionMode BACKGROUND = new ConnectionMode("BACKGROUND");
+
+    private final String name;
+
+    private ConnectionMode(String name) {
+        this.name = name;
+    }
+
+    @Override
+    public String toString() {
+        return name;
+    }
 }

launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/ConnectionMode.java

@@ -53,11 +53,11 @@ class ConnectivityManager {
     private final ClientContext baseClientContext;
     private final PlatformState platformState;
     private final ComponentConfigurer<DataSource> dataSourceFactory;
-    private final TransactionalDataStore transactionalDataStore;
     private final DataSourceUpdateSink dataSourceUpdateSink;
     private final ConnectionInformationState connectionInformation;
     private final PersistentDataStoreWrapper.PerEnvironmentData environmentStore;
     private final EventProcessor eventProcessor;
+    private final TransactionalDataStore transactionalDataStore;
     private final PlatformState.ForegroundChangeListener foregroundListener;
     private final PlatformState.ConnectivityChangeListener connectivityChangeListener;
     private final TaskExecutor taskExecutor;
@@ -72,6 +72,7 @@ class ConnectivityManager {
     private final AtomicReference<Boolean> previouslyInBackground = new AtomicReference<>();
     private final LDLogger logger;
     private volatile boolean initialized = false;
+    private volatile Map<ConnectionMode, ResolvedModeDefinition> resolvedModeTable;
     private volatile ConnectionMode currentFDv2Mode;
 
     // The DataSourceUpdateSinkImpl receives flag updates and status updates from the DataSource.
@@ -134,11 +135,11 @@ public void shutDown() {
     ) {
         this.baseClientContext = clientContext;
         this.dataSourceFactory = dataSourceFactory;
-        this.transactionalDataStore = contextDataManager;
         this.dataSourceUpdateSink = new DataSourceUpdateSinkImpl(contextDataManager);
         this.platformState = ClientContextImpl.get(clientContext).getPlatformState();
         this.eventProcessor = eventProcessor;
         this.environmentStore = environmentStore;
+        this.transactionalDataStore = contextDataManager;
         this.taskExecutor = ClientContextImpl.get(clientContext).getTaskExecutor();
         this.logger = clientContext.getBaseLogger();
 
@@ -153,7 +154,7 @@ public void shutDown() {
         connectivityChangeListener = networkAvailable -> {
             DataSource dataSource = currentDataSource.get();
             if (dataSource instanceof ModeAware) {
-                eventProcessor.setOffline(forcedOffline.get() || !networkAvailable);
+                eventProcessor.setOffline(!networkAvailable);
                 resolveAndSwitchMode((ModeAware) dataSource);
             } else {
                 updateDataSource(false, LDUtil.noOpCallback());
@@ -244,15 +245,21 @@ private synchronized boolean updateDataSource(
         ClientContext clientContext = ClientContextImpl.forDataSource(
                 baseClientContext,
                 dataSourceUpdateSink,
-                transactionalDataStore,
                 context,
                 inBackground,
-                previouslyInBackground.get()
+                previouslyInBackground.get(),
+                transactionalDataStore
         );
         DataSource dataSource = dataSourceFactory.build(clientContext);
         currentDataSource.set(dataSource);
         previouslyInBackground.set(Boolean.valueOf(inBackground));
 
+        if (dataSourceFactory instanceof FDv2DataSourceBuilder) {
+            FDv2DataSourceBuilder fdv2Builder = (FDv2DataSourceBuilder) dataSourceFactory;
+            resolvedModeTable = fdv2Builder.getResolvedModeTable();
+            currentFDv2Mode = fdv2Builder.getStartingMode();
+        }
+
         dataSource.start(new Callback<Boolean>() {
             @Override
             public void onSuccess(Boolean result) {
@@ -272,10 +279,9 @@ public void onError(Throwable error) {
             }
         });
 
-        // Resolve the initial mode after start() so that switchMode() can safely replace
-        // the source manager without conflicting with the start() task submission.
+        // If the app starts in the background, the builder creates the data source with
+        // STREAMING as the starting mode. Perform an initial mode resolution to correct this.
         if (dataSource instanceof ModeAware) {
-            currentFDv2Mode = ConnectionMode.STREAMING;
             resolveAndSwitchMode((ModeAware) dataSource);
         }
 
@@ -423,31 +429,6 @@ synchronized boolean startUp(@NonNull Callback<Void> onCompletion) {
         return updateDataSource(true, onCompletion);
     }
 
-    /**
-     * Resolves the current platform state to a {@link ConnectionMode} using the mode resolution
-     * table, and calls {@link ModeAware#switchMode} if the resolved mode differs from the current
-     * mode. This replaces the legacy teardown/rebuild cycle for FDv2 data sources.
-     */
-    private void resolveAndSwitchMode(ModeAware modeAware) {
-        ConnectionMode resolvedMode;
-        if (forcedOffline.get()) {
-            resolvedMode = ConnectionMode.OFFLINE;
-        } else {
-            ModeState state = new ModeState(
-                    platformState.isForeground(),
-                    platformState.isNetworkAvailable()
-            );
-            resolvedMode = ModeResolutionTable.MOBILE.resolve(state);
-        }
-
-        ConnectionMode previousMode = currentFDv2Mode;
-        if (previousMode != resolvedMode) {
-            logger.debug("Switching FDv2 data source mode: {} -> {}", previousMode, resolvedMode);
-            currentFDv2Mode = resolvedMode;
-            modeAware.switchMode(resolvedMode);
-        }
-    }
-
     /**
      * Permanently stops data updating for the current client instance. We call this if the client
      * is being closed, or if we receive an error that indicates the mobile key is invalid.
@@ -481,6 +462,37 @@ boolean isForcedOffline() {
         return forcedOffline.get();
     }
 
+    /**
+     * Resolves the current platform state to a ConnectionMode via the ModeResolutionTable,
+     * looks up the ResolvedModeDefinition from the resolved mode table, and calls
+     * switchMode() on the data source if the mode has changed.
+     */
+    private void resolveAndSwitchMode(@NonNull ModeAware modeAware) {
+        Map<ConnectionMode, ResolvedModeDefinition> table = resolvedModeTable;
+        if (table == null) {
+            return;
+        }
+        boolean forceOffline = forcedOffline.get();
+        boolean networkAvailable = platformState.isNetworkAvailable();
+        boolean foreground = platformState.isForeground();
+        ModeState state = new ModeState(
+                foreground && !forceOffline,
+                networkAvailable && !forceOffline
+        );
+        ConnectionMode newMode = ModeResolutionTable.MOBILE.resolve(state);
+        if (newMode == currentFDv2Mode) {
+            return;
+        }
+        currentFDv2Mode = newMode;
+        ResolvedModeDefinition def = table.get(newMode);
+        if (def == null) {
+            logger.warn("No resolved definition for mode {}; skipping switchMode", newMode);
+            return;
+        }
+        logger.debug("Switching FDv2 mode to {}", newMode);
+        modeAware.switchMode(def);
+    }
+
     synchronized ConnectionInformation getConnectionInformation() {
         return connectionInformation;
     }