chore: FDv2 Cache Initializer

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

@@ -207,6 +207,11 @@ public PersistentDataStoreWrapper.PerEnvironmentData getPerEnvironmentData() {
         return throwExceptionIfNull(perEnvironmentData);
     }
 
+    @Nullable
+    public PersistentDataStoreWrapper.PerEnvironmentData getPerEnvironmentDataIfAvailable() {
+        return perEnvironmentData;
+    }
+
     @Nullable
     public TransactionalDataStore getTransactionalDataStore() {
         return transactionalDataStore;

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

@@ -64,17 +64,39 @@ final class ContextDataManager implements TransactionalDataStore {
     /** Selector from the last applied changeset that carried one; in-memory only, not persisted. */
     @NonNull private Selector currentSelector = Selector.EMPTY;
 
+    /**
+     * @param skipCacheLoad true when an FDv2 cache initializer will handle loading cached
+     *                      flags as the first step in the initializer chain, making the
+     *                      cache load in {@link #switchToContext} redundant
+     */
     ContextDataManager(
             @NonNull ClientContext clientContext,
             @NonNull PersistentDataStoreWrapper.PerEnvironmentData environmentStore,
-            int maxCachedContexts
+            int maxCachedContexts,
+            boolean skipCacheLoad
     ) {
         this.environmentStore = environmentStore;
         this.index = environmentStore.getIndex();
         this.maxCachedContexts = maxCachedContexts;
         this.taskExecutor = ClientContextImpl.get(clientContext).getTaskExecutor();
         this.logger = clientContext.getBaseLogger();
-        switchToContext(clientContext.getEvaluationContext());
+        if (skipCacheLoad) {
+            setCurrentContext(clientContext.getEvaluationContext());
+        } else {
+            switchToContext(clientContext.getEvaluationContext());
+        }
+    }
+
+    /**
+     * Sets the current context without loading cached data. Used in the FDv2 path where
+     * the {@code FDv2CacheInitializer} handles cache loading as part of the initializer chain.
+     *
+     * @param context the context to switch to
+     */
+    public void setCurrentContext(@NonNull LDContext context) {
+        synchronized (lock) {
+            currentContext = context;
+        }
     }
 
     /**

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

@@ -7,6 +7,7 @@
 import com.launchdarkly.sdk.android.integrations.PollingSynchronizerBuilder;
 import com.launchdarkly.sdk.android.integrations.StreamingSynchronizerBuilder;
 import com.launchdarkly.sdk.android.interfaces.ServiceEndpoints;
+import com.launchdarkly.sdk.android.subsystems.CachedFlagStore;
 import com.launchdarkly.sdk.android.subsystems.DataSourceBuildInputs;
 import com.launchdarkly.sdk.android.subsystems.DataSourceBuilder;
 import com.launchdarkly.sdk.android.subsystems.Initializer;
@@ -138,6 +139,18 @@ public Synchronizer build(DataSourceBuildInputs inputs) {
         }
     }
 
+    static final class CacheInitializerBuilderImpl implements DataSourceBuilder<Initializer> {
+        @Override
+        public Initializer build(DataSourceBuildInputs inputs) {
+            return new FDv2CacheInitializer(
+                    inputs.getCachedFlagStore(),
+                    inputs.getEvaluationContext(),
+                    inputs.getSharedExecutor(),
+                    inputs.getBaseLogger()
+            );
+        }
+    }
+
     /**
      * Returns a builder for a polling initializer.
      * <p>
@@ -188,6 +201,7 @@ public static StreamingSynchronizerBuilder streamingSynchronizer() {
      */
     @NonNull
     public static Map<ConnectionMode, ModeDefinition> makeDefaultModeTable() {
+        DataSourceBuilder<Initializer> cacheInitializer = new CacheInitializerBuilderImpl();
         DataSourceBuilder<Initializer> pollingInitializer = pollingInitializer();
         DataSourceBuilder<Synchronizer> pollingSynchronizer = pollingSynchronizer();
         DataSourceBuilder<Synchronizer> streamingSynchronizer = streamingSynchronizer();
@@ -202,32 +216,28 @@ public static Map<ConnectionMode, ModeDefinition> makeDefaultModeTable() {
 
         Map<ConnectionMode, ModeDefinition> table = new LinkedHashMap<>();
         table.put(ConnectionMode.STREAMING, new ModeDefinition(
-                // TODO: cacheInitializer — add once implemented
-                Arrays.asList(/* cacheInitializer, */ pollingInitializer),
+                Arrays.asList(cacheInitializer, pollingInitializer),
                 Arrays.asList(streamingSynchronizer, pollingSynchronizer),
                 fdv1FallbackPollingSynchronizerForeground
         ));
         table.put(ConnectionMode.POLLING, new ModeDefinition(
-                // TODO: Arrays.asList(cacheInitializer) — add once implemented
-                Collections.<DataSourceBuilder<Initializer>>emptyList(),
+                Collections.singletonList(cacheInitializer),
                 Collections.singletonList(pollingSynchronizer),
                 fdv1FallbackPollingSynchronizerForeground
         ));
         table.put(ConnectionMode.OFFLINE, new ModeDefinition(
-                // TODO: Arrays.asList(cacheInitializer) — add once implemented
-                Collections.<DataSourceBuilder<Initializer>>emptyList(),
+                Collections.singletonList(cacheInitializer),
                 Collections.<DataSourceBuilder<Synchronizer>>emptyList(),
                 null
         ));
         table.put(ConnectionMode.ONE_SHOT, new ModeDefinition(
-                // TODO: cacheInitializer and streamingInitializer — add once implemented
-                Arrays.asList(/* cacheInitializer, */ pollingInitializer /*, streamingInitializer, */),
+                // TODO: streamingInitializer — add once implemented
+                Arrays.asList(cacheInitializer, pollingInitializer /*, streamingInitializer */),
                 Collections.<DataSourceBuilder<Synchronizer>>emptyList(),
                 null
         ));
         table.put(ConnectionMode.BACKGROUND, new ModeDefinition(
-                // TODO: Arrays.asList(cacheInitializer) — add once implemented
-                Collections.<DataSourceBuilder<Initializer>>emptyList(),
+                Collections.singletonList(cacheInitializer),
                 Collections.singletonList(backgroundPollingSynchronizer),
                 fdv1FallbackPollingSynchronizerBackground
         ));

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

@@ -0,0 +1,99 @@
+package com.launchdarkly.sdk.android;
+
+import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
+
+import com.launchdarkly.logging.LDLogger;
+import com.launchdarkly.sdk.LDContext;
+import com.launchdarkly.sdk.android.DataModel.Flag;
+import com.launchdarkly.sdk.android.subsystems.CachedFlagStore;
+import com.launchdarkly.sdk.android.subsystems.FDv2SourceResult;
+import com.launchdarkly.sdk.android.subsystems.Initializer;
+import com.launchdarkly.sdk.fdv2.ChangeSet;
+import com.launchdarkly.sdk.fdv2.ChangeSetType;
+import com.launchdarkly.sdk.fdv2.Selector;
+
+import java.util.Map;
+import java.util.concurrent.Executor;
+import java.util.concurrent.Future;
+
+/**
+ * FDv2 cache initializer: loads persisted flag data from the local cache as the first
+ * step in the initializer chain.
+ * <p>
+ * Per CONNMODE 4.1.2, the cache initializer returns data with {@code persist=false}
+ * and {@link Selector#EMPTY} (no selector), so the orchestrator continues to the next
+ * initializer (polling) to obtain a verified selector from the server. This provides
+ * immediate flag values from cache while the network initializer fetches fresh data.
+ * <p>
+ * A cache miss is reported as an {@link FDv2SourceResult.Status#interrupted} status,
+ * causing the orchestrator to move to the next initializer without delay.
+ */
+final class FDv2CacheInitializer implements Initializer {
+
+    @Nullable
+    private final CachedFlagStore cachedFlagStore;
+    private final LDContext context;
+    private final Executor executor;
+    private final LDLogger logger;
+    private final LDAwaitFuture<FDv2SourceResult> shutdownFuture = new LDAwaitFuture<>();
+
+    FDv2CacheInitializer(
+            @Nullable CachedFlagStore cachedFlagStore,
+            @NonNull LDContext context,
+            @NonNull Executor executor,
+            @NonNull LDLogger logger
+    ) {
+        this.cachedFlagStore = cachedFlagStore;
+        this.context = context;
+        this.executor = executor;
+        this.logger = logger;
+    }
+
+    @Override
+    @NonNull
+    public Future<FDv2SourceResult> run() {
+        LDAwaitFuture<FDv2SourceResult> resultFuture = new LDAwaitFuture<>();
+
+        executor.execute(() -> {
+            try {
+                if (cachedFlagStore == null) {
+                    logger.debug("No persistent store configured; skipping cache");
+                    resultFuture.set(FDv2SourceResult.status(
+                            FDv2SourceResult.Status.interrupted(
+                                    new LDFailure("No persistent store", LDFailure.FailureType.UNKNOWN_ERROR)),
+                            false));
+                    return;
+                }
+                Map<String, Flag> flags = cachedFlagStore.getCachedFlags(context);
+                if (flags == null) {
+                    logger.debug("Cache miss for context");
+                    resultFuture.set(FDv2SourceResult.status(
+                            FDv2SourceResult.Status.interrupted(
+                                    new LDFailure("No cached data", LDFailure.FailureType.UNKNOWN_ERROR)),
+                            false));
+                    return;
+                }
+                ChangeSet<Map<String, Flag>> changeSet = new ChangeSet<>(
+                        ChangeSetType.Full,
+                        Selector.EMPTY,
+                        flags,
+                        null,
+                        false);
+                logger.debug("Cache hit: loaded {} flags for context", flags.size());
+                resultFuture.set(FDv2SourceResult.changeSet(changeSet, false));
+            } catch (Exception e) {
+                logger.warn("Cache initializer failed: {}", e.toString());
+                resultFuture.set(FDv2SourceResult.status(
+                        FDv2SourceResult.Status.interrupted(e), false));
+            }
+        });
+
+        return LDFutures.anyOf(shutdownFuture, resultFuture);
+    }
+
+    @Override
+    public void close() {
+        shutdownFuture.set(FDv2SourceResult.status(FDv2SourceResult.Status.shutdown(), false));
+    }
+}

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

@@ -2,6 +2,7 @@
 
 import androidx.annotation.NonNull;
 
+import com.launchdarkly.sdk.android.subsystems.CachedFlagStore;
 import com.launchdarkly.sdk.android.subsystems.ClientContext;
 import com.launchdarkly.sdk.android.subsystems.ComponentConfigurer;
 import com.launchdarkly.sdk.android.subsystems.DataSource;
@@ -149,18 +150,30 @@ public void close() {
     }
 
     private DataSourceBuildInputs makeInputs(ClientContext clientContext) {
-        TransactionalDataStore store = ClientContextImpl.get(clientContext).getTransactionalDataStore();
+        ClientContextImpl impl = ClientContextImpl.get(clientContext);
+        TransactionalDataStore store = impl.getTransactionalDataStore();
         SelectorSource selectorSource = store != null
                 ? new SelectorSourceFacade(store)
                 : () -> com.launchdarkly.sdk.fdv2.Selector.EMPTY;
+
+        PersistentDataStoreWrapper.PerEnvironmentData envData = impl.getPerEnvironmentDataIfAvailable();
+        CachedFlagStore cachedFlagStore = envData != null
+                ? context -> {
+                    String hashedId = LDUtil.urlSafeBase64HashedContextId(context);
+                    EnvironmentData stored = envData.getContextData(hashedId);
+                    return stored != null ? stored.getAll() : null;
+                }
+                : null;
+
         return new DataSourceBuildInputs(
                 clientContext.getEvaluationContext(),
                 clientContext.getServiceEndpoints(),
                 clientContext.getHttp(),
                 clientContext.isEvaluationReasons(),
                 selectorSource,
                 sharedExecutor,
-                ClientContextImpl.get(clientContext).getPlatformState().getCacheDir(),
+                impl.getPlatformState().getCacheDir(),
+                cachedFlagStore,
                 clientContext.getBaseLogger()
         );
     }

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

@@ -421,10 +421,12 @@ protected LDClient(
                 taskExecutor
         );
 
+        boolean usingFDv2 = config.dataSource instanceof FDv2DataSourceBuilder;
         this.contextDataManager = new ContextDataManager(
                 clientContextImpl,
                 environmentStore,
-                config.getMaxCachedContexts()
+                config.getMaxCachedContexts(),
+                usingFDv2
         );
 
         eventProcessor = config.events.build(clientContextImpl);
@@ -497,11 +499,17 @@ private void identifyInternal(@NonNull LDContext context,
 
         clientContextImpl = clientContextImpl.setEvaluationContext(context);
 
-        // Calling initFromStoredData updates the current flag state *if* stored flags exist for
-        // this context. If they don't, it has no effect. Currently we do *not* return early from
-        // initialization just because stored flags exist; we're just making them available in case
-        // initialization times out or otherwise fails.
-        contextDataManager.switchToContext(context);
+        // Load cached flags for the new context so they're available in case initialization
+        // times out or otherwise fails. This does not short-circuit initialization — the data
+        // source still performs its network request regardless.
+        if (config.dataSource instanceof FDv2DataSourceBuilder) {
+            // FDv2: just set the context; the FDv2CacheInitializer handles cache loading
+            // as the first step in the initializer chain.
+            contextDataManager.setCurrentContext(context);
+        } else {
+            // FDv1: load cached flags immediately while the data source fetches from the network.
+            contextDataManager.switchToContext(context);
+        }
         connectivityManager.switchToContext(context, onCompleteListener);
         eventProcessor.recordIdentifyEvent(context);
     }

launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/CachedFlagStore.java

@@ -0,0 +1,27 @@
+package com.launchdarkly.sdk.android.subsystems;
+
+import androidx.annotation.Nullable;
+
+import com.launchdarkly.sdk.LDContext;
+import com.launchdarkly.sdk.android.DataModel;
+
+import java.util.Map;
+
+/**
+ * Provides read access to cached flag data for a specific evaluation context.
+ * <p>
+ * This interface bridges the persistence layer with FDv2 data source builders,
+ * allowing the cache initializer to load stored flags without depending on
+ * package-private types.
+ */
+public interface CachedFlagStore {
+    /**
+     * Returns the cached flag data for the given context, or null if no
+     * cached data exists.
+     *
+     * @param context the evaluation context to look up
+     * @return the cached flags, or null on cache miss
+     */
+    @Nullable
+    Map<String, DataModel.Flag> getCachedFlags(LDContext context);
+}

launchdarkly-android-client-sdk/src/main/java/com/launchdarkly/sdk/android/subsystems/DataSourceBuildInputs.java

@@ -1,6 +1,7 @@
 package com.launchdarkly.sdk.android.subsystems;
 
 import androidx.annotation.NonNull;
+import androidx.annotation.Nullable;
 
 import com.launchdarkly.logging.LDLogger;
 import com.launchdarkly.sdk.LDContext;
@@ -31,6 +32,8 @@ public final class DataSourceBuildInputs {
     private final SelectorSource selectorSource;
     private final ScheduledExecutorService sharedExecutor;
     private final File cacheDir;
+    @Nullable
+    private final CachedFlagStore cachedFlagStore;
     private final LDLogger baseLogger;
 
     /**
@@ -44,6 +47,8 @@ public final class DataSourceBuildInputs {
      * @param sharedExecutor    shared executor for scheduling tasks; owned and shut down by
      *                          the calling data source, so components must not shut it down
      * @param cacheDir          the platform's cache directory for HTTP-level caching
+     * @param cachedFlagStore   read access to cached flag data, or null if no persistent
+     *                          store is configured
      * @param baseLogger        the base logger instance
      */
     public DataSourceBuildInputs(
@@ -54,6 +59,7 @@ public DataSourceBuildInputs(
             SelectorSource selectorSource,
             ScheduledExecutorService sharedExecutor,
             @NonNull File cacheDir,
+            @Nullable CachedFlagStore cachedFlagStore,
             LDLogger baseLogger
     ) {
         this.evaluationContext = evaluationContext;
@@ -63,6 +69,7 @@ public DataSourceBuildInputs(
         this.selectorSource = selectorSource;
         this.sharedExecutor = sharedExecutor;
         this.cacheDir = cacheDir;
+        this.cachedFlagStore = cachedFlagStore;
         this.baseLogger = baseLogger;
     }
 
@@ -133,6 +140,17 @@ public File getCacheDir() {
         return cacheDir;
     }
 
+    /**
+     * Returns read access to cached flag data, or null if no persistent store
+     * is configured. Used by the cache initializer to load stored flags.
+     *
+     * @return the cached flag store, or null
+     */
+    @Nullable
+    public CachedFlagStore getCachedFlagStore() {
+        return cachedFlagStore;
+    }
+
     /**
      * Returns the base logger instance.
      *