fix: ScheduledExecutorService for Feature Refresh, Cache updates and evalPath Optimization (#168)

* feat: introduce CacheMode, factory, and safe cache fallbacks

* add missing methods

* support nullable cache manager

* handle null case for cache manager

* support null for cache manager

* add in-memory cache manager

* fix warnings and formatting

* remove serialization churn & feature refresh patch

* remove attr overrides

* add polling task

* add tests for polling

* add cache and refresh strategies

Author: madhuchavva

README.md

@@ -131,6 +131,29 @@ growthBook.isOn("featureKey");
 ```
 
 ## Usage
+## Caching & Refresh Strategy
+
+### Cache modes
+
+The SDK supports multiple cache modes for persisting feature payloads:
+
+- FILE: persist to a writable directory (configurable). Defaults to a safe OS-specific cache dir (or `java.io.tmpdir`).
+- MEMORY: in-process cache only (no filesystem writes).
+- NONE: no cache I/O. Runtime still holds the latest fetched features.
+- CUSTOM: supply your own `GbCacheManager` implementation.
+
+You can configure these through `Options` when using `GrowthBookClient`, or via the repository builder’s `cacheManager` directly. When cache is disabled (`isCacheDisabled=true`), the repository won’t attempt any persistence.
+
+### STALE_WHILE_REVALIDATE (default)
+
+With the SWR strategy, the repository will:
+
+- Perform an initial synchronous fetch during `initialize()`.
+- Start a lightweight background poller that revalidates features on a fixed delay (by default equal to the TTL). The poller is protected against overlapping runs and logs start/end of each polling cycle.
+- Keep the latest features in memory and invoke registered `FeatureRefreshCallback`s when updated so the `GlobalContext` stays fresh.
+
+For SSE connections, the repository establishes a server‑sent events stream and updates as changes arrive; the SWR poller is not used.
+
 
 - The `evalFeature()` method evaluates a feature based on the provided parameters.
 It takes three arguments: a string representing the unique identifier of the feature,

lib/src/main/java/growthbook/sdk/java/multiusermode/GrowthBookClient.java

@@ -3,6 +3,7 @@
 import java.util.*;
 
 import com.google.gson.JsonElement;
+import com.google.gson.JsonObject;
 import growthbook.sdk.java.callback.ExperimentRunCallback;
 import growthbook.sdk.java.callback.FeatureRefreshCallback;
 import growthbook.sdk.java.evaluators.ExperimentEvaluator;
@@ -17,8 +18,10 @@
 import growthbook.sdk.java.multiusermode.configurations.GlobalContext;
 import growthbook.sdk.java.multiusermode.configurations.Options;
 import growthbook.sdk.java.multiusermode.configurations.UserContext;
-import growthbook.sdk.java.multiusermode.util.TransformationUtil;
 import growthbook.sdk.java.repository.GBFeaturesRepository;
+import growthbook.sdk.java.sandbox.CacheManagerFactory;
+import growthbook.sdk.java.sandbox.CacheMode;
+import growthbook.sdk.java.sandbox.GbCacheManager;
 import growthbook.sdk.java.util.GrowthBookJsonUtils;
 import lombok.extern.slf4j.Slf4j;
 
@@ -58,14 +61,20 @@ public boolean initialize() {
         try {
 
             if (repository == null) {
+                GbCacheManager cm = this.options.getCacheManager() != null
+                        ? this.options.getCacheManager()
+                        : CacheManagerFactory.create(this.options.getCacheMode(), this.options.getCacheDirectory()
+                        );
+
                 repository = GBFeaturesRepository.builder()
                         .apiHost(this.options.getApiHost())
                         .clientKey(this.options.getClientKey())
                         .decryptionKey(this.options.getDecryptionKey())
                         .refreshStrategy(this.options.getRefreshStrategy())
-                        .isCacheDisabled(this.options.getIsCacheDisabled())
-                        .cacheManager(this.options.getCacheManager())
-                        .requestBodyForRemoteEval(configurePayloadForRemoteEval(this.options)) // if we don't want to pre-fetch for remote eval we can delete this line
+                        .isCacheDisabled(this.options.getIsCacheDisabled() || this.options.getCacheMode() == CacheMode.NONE)
+                        .cacheManager(cm)
+                        // if we don't want to pre-fetch for remote eval we can delete this line
+                        .requestBodyForRemoteEval(configurePayloadForRemoteEval(this.options))
                         .build();
 
                 // Add featureRefreshCallback
@@ -227,31 +236,19 @@ public void onError(Throwable throwable) {
     }
 
     private EvaluationContext getEvalContext(UserContext userContext) {
-        // Refresh features on each evaluation to ensure cache refresh is triggered
-        this.globalContext.setFeatures(repository.getParsedFeatures());
-        
-        HashMap<String, JsonElement> globalAttributes = null;
+        // Merge attributes using JsonObject to avoid parse/serialize churn
+        JsonObject merged = new JsonObject();
         if (this.options.getGlobalAttributes() != null) {
-            globalAttributes = GrowthBookJsonUtils.getInstance().gson.fromJson(this.options.getGlobalAttributes(), HashMap.class);
-        }
-
-        HashMap<String, JsonElement> userAttributes = null;
-        if (userContext.getAttributes() != null) {
-            userAttributes = GrowthBookJsonUtils.getInstance().gson.fromJson(userContext.getAttributes(), HashMap.class);
+            merged = GrowthBookJsonUtils.getInstance().gson.fromJson(this.options.getGlobalAttributes(), JsonObject.class);
+            if (merged == null) merged = new JsonObject();
         }
-
-        if (globalAttributes != null) {
-            if (userAttributes != null) {
-                globalAttributes.putAll(userAttributes);
+        JsonObject userAttrs = userContext.getAttributes();
+        if (userAttrs != null) {
+            for (Map.Entry<String, JsonElement> e : userAttrs.entrySet()) {
+                merged.add(e.getKey(), e.getValue());
             }
-        } else {
-            globalAttributes = userAttributes;
         }
-
-        String attributesJson = GrowthBookJsonUtils.getInstance().gson.toJson(globalAttributes);
-
-        UserContext updatedUserContext = userContext.witAttributesJson(attributesJson);
-
+        UserContext updatedUserContext = userContext.withAttributes(merged);
         return new EvaluationContext(this.globalContext, updatedUserContext, new EvaluationContext.StackContext(), this.options);
     }
 

lib/src/main/java/growthbook/sdk/java/multiusermode/configurations/Options.java

@@ -10,6 +10,7 @@
 import growthbook.sdk.java.multiusermode.util.TransformationUtil;
 import growthbook.sdk.java.repository.FeatureRefreshStrategy;
 import growthbook.sdk.java.sandbox.GbCacheManager;
+import growthbook.sdk.java.sandbox.CacheMode;
 import growthbook.sdk.java.stickyBucketing.InMemoryStickyBucketServiceImpl;
 import growthbook.sdk.java.stickyBucketing.StickyBucketService;
 import lombok.Builder;
@@ -43,7 +44,9 @@ public Options(@Nullable Boolean enabled,
                    @Nullable JsonObject globalAttributes,
                    @Nullable Map<String, Object> globalForcedFeatureValues,
                    @Nullable Map<String, Integer> globalForcedVariationsMap,
-                   @Nullable GbCacheManager cacheManager
+                    @Nullable GbCacheManager cacheManager,
+                    @Nullable CacheMode cacheMode,
+                    @Nullable String cacheDirectory
 
     ) {
         this.enabled = enabled == null || enabled;
@@ -64,6 +67,8 @@ public Options(@Nullable Boolean enabled,
         this.globalForcedFeatureValues = globalForcedFeatureValues;
         this.globalForcedVariationsMap = globalForcedVariationsMap;
         this.cacheManager = cacheManager;
+        this.cacheMode = cacheMode == null ? CacheMode.AUTO : cacheMode;
+        this.cacheDirectory = cacheDirectory;
     }
 
     /**
@@ -178,6 +183,16 @@ public FeatureRefreshStrategy getRefreshingStrategy() {
     @Nullable
     private GbCacheManager cacheManager;
 
+    // New cache configuration
+    private CacheMode cacheMode;
+
+    @Nullable
+    private String cacheDirectory;
+
+    public CacheMode getCacheMode() { return cacheMode == null ? CacheMode.AUTO : cacheMode; }
+    @Nullable
+    public String getCacheDirectory() { return cacheDirectory; }
+
     @Nullable
     public StickyBucketService getStickyBucketService() {
         return stickyBucketService;

lib/src/main/java/growthbook/sdk/java/multiusermode/configurations/UserContext.java

@@ -42,9 +42,19 @@ private UserContext(UserContextBuilder userContextBuilder) {
     }
 
     public UserContext witAttributesJson(String attributesJson) {
+        // Build a new context using only the provided attributesJson for attributes
         return new UserContextBuilder()
                 .attributesJson(attributesJson)
-                .attributes(this.attributes)
+                .forcedVariationsMap(this.forcedVariationsMap)
+                .forcedFeatureValues(this.forcedFeatureValues)
+                .url(this.url)
+                .stickyBucketAssignmentDocs(this.stickyBucketAssignmentDocs)
+                .build();
+    }
+
+    public UserContext withAttributes(JsonObject attributes) {
+        return new UserContextBuilder()
+                .attributes(attributes == null ? new JsonObject() : attributes)
                 .forcedVariationsMap(this.forcedVariationsMap)
                 .forcedFeatureValues(this.forcedFeatureValues)
                 .url(this.url)
@@ -105,7 +115,10 @@ public static class UserContextBuilder {
 
         public UserContextBuilder attributesJson(String attributesJson) {
             this.attributesJson = attributesJson;
-            this.attributes = TransformationUtil.transformAttributes(attributesJson);
+            // Only transform if attributes not explicitly provided
+            if (this.attributes == null) {
+                this.attributes = TransformationUtil.transformAttributes(attributesJson);
+            }
             return this;
         }