[SDK-1956] Replace internal switchMode() with teardown/rebuild at ConnectivityManager level

Per updated CSFDV2 spec and JS implementation, mode switching now tears
down the old data source and builds a new one rather than swapping
internal synchronizers. Delete ModeAware interface, remove switchMode()
from FDv2DataSource and switchSynchronizers() from SourceManager.
FDv2DataSourceBuilder becomes the sole owner of mode resolution via
setActiveMode()/build(), with ConnectivityManager using a
useFDv2ModeResolution flag to route FDv2 through the new path while
preserving FDv1 behavior. Implements CSFDV2 5.3.8 (retain data source
when old and new modes share the same ModeDefinition).

Made-with: Cursor

Author: aaron-zeisler

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

@@ -72,7 +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 final boolean useFDv2ModeResolution;
     private volatile ConnectionMode currentFDv2Mode;
 
     // The DataSourceUpdateSinkImpl receives flag updates and status updates from the DataSource.
@@ -150,6 +150,7 @@ public void shutDown() {
         connectionInformation = new ConnectionInformationState();
         readStoredConnectionState();
         this.backgroundUpdatingDisabled = ldConfig.isDisableBackgroundPolling();
+        this.useFDv2ModeResolution = (dataSourceFactory instanceof FDv2DataSourceBuilder);
 
         connectivityChangeListener = networkAvailable -> handleModeStateChange();
         platformState.addConnectivityChangeListener(connectivityChangeListener);
@@ -190,13 +191,27 @@ private synchronized boolean updateDataSource(
         }
 
         DataSource existingDataSource = currentDataSource.get();
+        boolean isFDv2ModeSwitch = false;
 
-        // FDv2 ModeAware data sources handle all state transitions (including
-        // offline/background) via mode resolution rather than teardown/rebuild.
-        if (!mustReinitializeDataSource && existingDataSource instanceof ModeAware) {
-            resolveAndSwitchMode((ModeAware) existingDataSource);
-            onCompletion.onSuccess(null);
-            return false;
+        // FDv2 path: resolve mode and determine if a teardown/rebuild is needed.
+        if (useFDv2ModeResolution && !mustReinitializeDataSource) {
+            ConnectionMode newMode = resolveMode();
+            if (newMode == currentFDv2Mode) {
+                onCompletion.onSuccess(null);
+                return false;
+            }
+            // CSFDV2 5.3.8: retain active data source if old and new modes have equivalent config.
+            FDv2DataSourceBuilder fdv2Builder = (FDv2DataSourceBuilder) dataSourceFactory;
+            ModeDefinition oldDef = fdv2Builder.getModeDefinition(currentFDv2Mode);
+            ModeDefinition newDef = fdv2Builder.getModeDefinition(newMode);
+            if (oldDef != null && oldDef == newDef) {
+                currentFDv2Mode = newMode;
+                onCompletion.onSuccess(null);
+                return false;
+            }
+            currentFDv2Mode = newMode;
+            isFDv2ModeSwitch = true;
+            mustReinitializeDataSource = true;
         }
 
         // FDv1 path: check whether the data source needs a full rebuild.
@@ -215,7 +230,12 @@ private synchronized boolean updateDataSource(
         boolean shouldStopExistingDataSource = true,
                 shouldStartDataSourceIfStopped = false;
 
-        if (forceOffline) {
+        if (useFDv2ModeResolution) {
+            // FDv2 mode resolution already accounts for offline/background states via
+            // the ModeResolutionTable, so we always rebuild when the mode changed.
+            shouldStopExistingDataSource = mustReinitializeDataSource;
+            shouldStartDataSourceIfStopped = true;
+        } else if (forceOffline) {
             logger.debug("Initialized in offline mode");
             initialized = true;
             dataSourceUpdateSink.setStatus(ConnectionInformation.ConnectionMode.SET_OFFLINE, null);
@@ -249,41 +269,32 @@ private synchronized boolean updateDataSource(
                 previouslyInBackground.get(),
                 transactionalDataStore
         );
-        DataSource dataSource = dataSourceFactory.build(clientContext);
-        currentDataSource.set(dataSource);
-        previouslyInBackground.set(Boolean.valueOf(inBackground));
 
-        if (dataSourceFactory instanceof FDv2DataSourceBuilder) {
+        if (useFDv2ModeResolution) {
             FDv2DataSourceBuilder fdv2Builder = (FDv2DataSourceBuilder) dataSourceFactory;
-            resolvedModeTable = fdv2Builder.getResolvedModeTable();
-            currentFDv2Mode = fdv2Builder.getStartingMode();
+            // CONNMODE 2.0.1: mode switches only transition synchronizers, not initializers.
+            fdv2Builder.setActiveMode(currentFDv2Mode, !isFDv2ModeSwitch);
         }
 
+        DataSource dataSource = dataSourceFactory.build(clientContext);
+        currentDataSource.set(dataSource);
+        previouslyInBackground.set(Boolean.valueOf(inBackground));
+
         dataSource.start(new Callback<Boolean>() {
             @Override
             public void onSuccess(Boolean result) {
                 initialized = true;
-                // passing the current connection mode since we don't want to change the mode, just trigger
-                // the logic to update the last connection success.
                 updateConnectionInfoForSuccess(connectionInformation.getConnectionMode());
                 onCompletion.onSuccess(null);
             }
 
             @Override
             public void onError(Throwable error) {
-                // passing the current connection mode since we don't want to change the mode, just trigger
-                // the logic to update the last connection failure.
                 updateConnectionInfoForError(connectionInformation.getConnectionMode(), error);
                 onCompletion.onSuccess(null);
             }
         });
 
-        // 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) {
-            resolveAndSwitchMode((ModeAware) dataSource);
-        }
-
         return true;
     }
 
@@ -425,6 +436,13 @@ synchronized boolean startUp(@NonNull Callback<Void> onCompletion) {
             return false;
         }
         initialized = false;
+
+        if (useFDv2ModeResolution) {
+            currentFDv2Mode = resolveMode();
+            FDv2DataSourceBuilder fdv2Builder = (FDv2DataSourceBuilder) dataSourceFactory;
+            fdv2Builder.setActiveMode(currentFDv2Mode, true);
+        }
+
         updateEventProcessor(forcedOffline.get(), platformState.isNetworkAvailable(), platformState.isForeground());
         return updateDataSource(true, onCompletion);
     }
@@ -476,34 +494,18 @@ private void handleModeStateChange() {
     }
 
     /**
-     * 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.
+     * Resolves the current platform state to a {@link ConnectionMode} via the
+     * {@link ModeResolutionTable}.
      */
-    private void resolveAndSwitchMode(@NonNull ModeAware modeAware) {
-        Map<ConnectionMode, ResolvedModeDefinition> table = resolvedModeTable;
-        if (table == null) {
-            return;
-        }
+    private ConnectionMode resolveMode() {
         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);
+        return ModeResolutionTable.MOBILE.resolve(state);
     }
 
     synchronized ConnectionInformation getConnectionInformation() {

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

@@ -30,7 +30,7 @@
  * switch to next synchronizer) and recovery (when on non-prime synchronizer, try
  * to return to the first after timeout).
  */
-final class FDv2DataSource implements DataSource, ModeAware {
+final class FDv2DataSource implements DataSource {
 
     /**
      * Factory for creating Initializer or Synchronizer instances.
@@ -50,8 +50,6 @@ public interface DataSourceFactory<T> {
     private final AtomicBoolean started = new AtomicBoolean(false);
     private final AtomicBoolean startCompleted = new AtomicBoolean(false);
     private final AtomicBoolean stopped = new AtomicBoolean(false);
-    private final AtomicBoolean executionLoopRunning = new AtomicBoolean(false);
-
     /** Result of the first start (null = not yet completed). Used so second start() gets the same result. */
     private volatile Boolean startResult = null;
     private volatile Throwable startError = null;
@@ -140,7 +138,6 @@ public void start(@NonNull Callback<Boolean> resultCallback) {
         LDContext context = evaluationContext;
 
         sharedExecutor.execute(() -> {
-            executionLoopRunning.set(true);
             try {
                 if (!sourceManager.hasAvailableSources()) {
                     logger.info("No initializers or synchronizers; data source will not connect.");
@@ -167,8 +164,6 @@ public void start(@NonNull Callback<Boolean> resultCallback) {
             } catch (Throwable t) {
                 logger.warn("FDv2DataSource error: {}", t.toString());
                 tryCompleteStart(false, t);
-            } finally {
-                executionLoopRunning.set(false);
             }
         });
     }
@@ -221,32 +216,11 @@ public void stop(@NonNull Callback<Void> completionCallback) {
 
     @Override
     public boolean needsRefresh(boolean newInBackground, @NonNull LDContext newEvaluationContext) {
-        // Mode-aware data sources handle background/foreground transitions via switchMode(),
-        // so only request a full rebuild when the evaluation context changes.
+        // FDv2 background/foreground transitions are handled externally by ConnectivityManager
+        // via teardown/rebuild, so only request a rebuild when the evaluation context changes.
         return !evaluationContext.equals(newEvaluationContext);
     }
 
-    @Override
-    public void switchMode(@NonNull ResolvedModeDefinition newDefinition) {
-        List<SynchronizerFactoryWithState> newSyncFactories = new ArrayList<>();
-        for (DataSourceFactory<Synchronizer> factory : newDefinition.getSynchronizerFactories()) {
-            newSyncFactories.add(new SynchronizerFactoryWithState(factory));
-        }
-        // Per CONNMODE 2.0.1: mode switches only transition synchronizers, no initializers.
-        sourceManager.switchSynchronizers(newSyncFactories);
-
-        sharedExecutor.execute(() -> {
-            if (!executionLoopRunning.compareAndSet(false, true)) {
-                return;
-            }
-            try {
-                runSynchronizers(evaluationContext, dataSourceUpdateSink);
-            } finally {
-                executionLoopRunning.set(false);
-            }
-        });
-    }
-
     private void runInitializers(
             @NonNull LDContext context,
             @NonNull DataSourceUpdateSinkV2 sink

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

@@ -25,13 +25,10 @@
 import java.util.concurrent.ScheduledExecutorService;
 
 /**
- * Builds an {@link FDv2DataSource} and resolves the mode table from
- * {@link ComponentConfigurer} factories into zero-arg {@link FDv2DataSource.DataSourceFactory}
- * instances. The resolved table is stored and exposed via {@link #getResolvedModeTable()}
- * so that {@link ConnectivityManager} can perform mode→definition lookups when switching modes.
- * <p>
- * This is the key architectural difference in Approach 2: the builder owns the resolved
- * table rather than the data source itself.
+ * Builds an {@link FDv2DataSource} by resolving {@link ComponentConfigurer} factories
+ * into zero-arg {@link FDv2DataSource.DataSourceFactory} instances. The builder is the
+ * sole owner of mode resolution; {@link ConnectivityManager} configures the target mode
+ * via {@link #setActiveMode} before calling the standard {@link #build}.
  * <p>
  * Package-private — not part of the public SDK API.
  */
@@ -40,7 +37,9 @@ class FDv2DataSourceBuilder implements ComponentConfigurer<DataSource> {
     private final Map<ConnectionMode, ModeDefinition> modeTable;
     private final ConnectionMode startingMode;
 
-    private Map<ConnectionMode, ResolvedModeDefinition> resolvedModeTable;
+    private ConnectionMode activeMode;
+    private boolean includeInitializers = true; // false during mode switches to skip initializers (CONNMODE 2.0.1)
+    private ScheduledExecutorService sharedExecutor;
 
     FDv2DataSourceBuilder() {
         this(makeDefaultModeTable(), ConnectionMode.STREAMING);
@@ -175,53 +174,64 @@ private static Map<ConnectionMode, ModeDefinition> makeDefaultModeTable() {
         this.startingMode = startingMode;
     }
 
-    /**
-     * Returns the resolved mode table after {@link #build} has been called.
-     * Each entry maps a {@link ConnectionMode} to a {@link ResolvedModeDefinition}
-     * containing zero-arg factories that capture the {@link ClientContext}.
-     *
-     * @return unmodifiable map of resolved mode definitions
-     * @throws IllegalStateException if called before {@link #build}
-     */
     @NonNull
     ConnectionMode getStartingMode() {
         return startingMode;
     }
 
-    @NonNull
-    Map<ConnectionMode, ResolvedModeDefinition> getResolvedModeTable() {
-        if (resolvedModeTable == null) {
-            throw new IllegalStateException("build() must be called before getResolvedModeTable()");
-        }
-        return resolvedModeTable;
+    /**
+     * Configures the mode to build for and whether to include initializers.
+     * Called by {@link ConnectivityManager} before each {@link #build} call.
+     *
+     * @param mode               the target connection mode
+     * @param includeInitializers true for initial startup / identify, false for mode switches
+     *                           (per CONNMODE 2.0.1: mode switches only transition synchronizers)
+     */
+    void setActiveMode(@NonNull ConnectionMode mode, boolean includeInitializers) {
+        this.activeMode = mode;
+        this.includeInitializers = includeInitializers;
+    }
+
+    /**
+     * Returns the raw {@link ModeDefinition} for the given mode, used by
+     * {@link ConnectivityManager} for the CSFDV2 5.3.8 equivalence check.
+     */
+    ModeDefinition getModeDefinition(@NonNull ConnectionMode mode) {
+        return modeTable.get(mode);
     }
 
     @Override
     public DataSource build(ClientContext clientContext) {
-        Map<ConnectionMode, ResolvedModeDefinition> resolved = new LinkedHashMap<>();
-        for (Map.Entry<ConnectionMode, ModeDefinition> entry : modeTable.entrySet()) {
-            resolved.put(entry.getKey(), resolve(entry.getValue(), clientContext));
-        }
-        this.resolvedModeTable = Collections.unmodifiableMap(resolved);
+        ConnectionMode mode = activeMode != null ? activeMode : startingMode;
 
-        ResolvedModeDefinition startDef = resolvedModeTable.get(startingMode);
-        if (startDef == null) {
+        ModeDefinition modeDef = modeTable.get(mode);
+        if (modeDef == null) {
             throw new IllegalStateException(
-                    "Starting mode " + startingMode + " not found in mode table");
+                    "Mode " + mode + " not found in mode table");
         }
 
+        ResolvedModeDefinition resolved = resolve(modeDef, clientContext);
+
         DataSourceUpdateSink baseSink = clientContext.getDataSourceUpdateSink();
         if (!(baseSink instanceof DataSourceUpdateSinkV2)) {
             throw new IllegalStateException(
                     "FDv2DataSource requires a DataSourceUpdateSinkV2 implementation");
         }
 
-        ScheduledExecutorService sharedExecutor = Executors.newScheduledThreadPool(2);
+        if (sharedExecutor == null) {
+            sharedExecutor = Executors.newScheduledThreadPool(2);
+        }
+
+        List<FDv2DataSource.DataSourceFactory<Initializer>> initFactories =
+                includeInitializers ? resolved.getInitializerFactories() : Collections.<FDv2DataSource.DataSourceFactory<Initializer>>emptyList();
+
+        // Reset includeInitializers to default after each build to prevent stale state.
+        includeInitializers = true;
 
         return new FDv2DataSource(
                 clientContext.getEvaluationContext(),
-                startDef.getInitializerFactories(),
-                startDef.getSynchronizerFactories(),
+                initFactories,
+                resolved.getSynchronizerFactories(),
                 (DataSourceUpdateSinkV2) baseSink,
                 sharedExecutor,
                 clientContext.getBaseLogger()