feat: add logic for offline mode in java (#141)

* Add logic for offline mode in java

* checkstyle fixes

* Remove unnecessary exception

* REmove unnecessary changes spotted in self review

* PR feedback

Author: matthewelwell

src/main/java/com/flagsmith/FlagsmithClient.java

@@ -72,7 +72,7 @@ public void updateEnvironment() {
    * @return
    */
   public Flags getEnvironmentFlags() throws FlagsmithClientError {
-    if (flagsmithSdk.getConfig().getEnableLocalEvaluation()) {
+    if (getShouldUseEnvironmentDocument()) {
       return getEnvironmentFlagsFromDocument();
     }
 
@@ -105,7 +105,7 @@ public Flags getIdentityFlags(String identifier)
    */
   public Flags getIdentityFlags(String identifier, Map<String, Object> traits)
       throws FlagsmithClientError {
-    if (flagsmithSdk.getConfig().getEnableLocalEvaluation()) {
+    if (getShouldUseEnvironmentDocument()) {
       return getIdentityFlagsFromDocument(identifier, traits);
     }
 
@@ -165,23 +165,23 @@ public void close() {
 
   private Flags getEnvironmentFlagsFromDocument() throws FlagsmithClientError {
     if (environment == null) {
-      if (flagsmithSdk.getConfig().getFlagsmithFlagDefaults() == null) {
+      if (getConfig().getFlagsmithFlagDefaults() == null) {
         throw new FlagsmithClientError("Unable to get flags. No environment present.");
       }
       return getDefaultFlags();
     }
 
     return Flags.fromFeatureStateModels(
         Engine.getEnvironmentFeatureStates(environment),
-        flagsmithSdk.getConfig().getAnalyticsProcessor(),
+        getConfig().getAnalyticsProcessor(),
         null,
-        flagsmithSdk.getConfig().getFlagsmithFlagDefaults());
+        getConfig().getFlagsmithFlagDefaults());
   }
 
   private Flags getIdentityFlagsFromDocument(String identifier, Map<String, Object> traits)
       throws FlagsmithClientError {
     if (environment == null) {
-      if (flagsmithSdk.getConfig().getFlagsmithFlagDefaults() == null) {
+      if (getConfig().getFlagsmithFlagDefaults() == null) {
         throw new FlagsmithClientError("Unable to get flags. No environment present.");
       }
       return getDefaultFlags();
@@ -192,17 +192,23 @@ private Flags getIdentityFlagsFromDocument(String identifier, Map<String, Object
 
     return Flags.fromFeatureStateModels(
         featureStates,
-        flagsmithSdk.getConfig().getAnalyticsProcessor(),
+        getConfig().getAnalyticsProcessor(),
         identity.getCompositeKey(),
-        flagsmithSdk.getConfig().getFlagsmithFlagDefaults());
+        getConfig().getFlagsmithFlagDefaults());
   }
 
   private Flags getEnvironmentFlagsFromApi() throws FlagsmithApiError {
     try {
       return flagsmithSdk.getFeatureFlags(Boolean.TRUE);
     } catch (Exception e) {
-      if (flagsmithSdk.getConfig().getFlagsmithFlagDefaults() != null) {
+      if (getConfig().getFlagsmithFlagDefaults() != null) {
         return getDefaultFlags();
+      } else if (environment != null) {
+        try {
+          return getEnvironmentFlagsFromDocument();
+        } catch (FlagsmithClientError ce) {
+          // Do nothing and fall through to FlagsmithApiError
+        }
       }
 
       throw new FlagsmithApiError("Failed to get feature flags.");
@@ -225,8 +231,14 @@ private Flags getIdentityFlagsFromApi(String identifier, Map<String, Object> tra
           traitsList,
           Boolean.TRUE);
     } catch (Exception e) {
-      if (flagsmithSdk.getConfig().getFlagsmithFlagDefaults() != null) {
+      if (getConfig().getFlagsmithFlagDefaults() != null) {
         return getDefaultFlags();
+      } else if (environment != null) {
+        try {
+          return getIdentityFlagsFromDocument(identifier, traits);
+        } catch (FlagsmithClientError ce) {
+          // Do nothing and fall through to FlagsmithApiError
+        }
       }
 
       throw new FlagsmithApiError("Failed to get feature flags.");
@@ -258,19 +270,23 @@ private IdentityModel buildIdentityModel(String identifier, Map<String, Object>
 
   private Flags getDefaultFlags() {
     Flags flags = new Flags();
-    flags.setDefaultFlagHandler(flagsmithSdk.getConfig().getFlagsmithFlagDefaults());
+    flags.setDefaultFlagHandler(getConfig().getFlagsmithFlagDefaults());
     return flags;
   }
 
   private String getEnvironmentUpdateErrorMessage() {
     if (this.environment == null) {
       return "Unable to update environment from API. "
-             + "No environment configured - using defaultHandler if configured.";
+        + "No environment configured - using defaultHandler if configured.";
     } else {
       return "Unable to update environment from API. Continuing to use previous copy.";
     }
   }
 
+  private FlagsmithConfig getConfig() {
+    return flagsmithSdk.getConfig();
+  }
+
   /**
    * Returns a FlagsmithCache cache object that encapsulates methods to manipulate
    * the cache.
@@ -281,6 +297,15 @@ public FlagsmithCache getCache() {
     return this.flagsmithSdk.getCache();
   }
 
+  /**
+   * Returns a boolean indicating whether the flags should be retrieved from a
+   * locally stored environment document instead of retrieved from the API.
+   */
+  private Boolean getShouldUseEnvironmentDocument() {
+    FlagsmithConfig config = getConfig();
+    return config.getEnableLocalEvaluation() | config.getOfflineMode();
+  }
+
   public static class Builder {
 
     private final FlagsmithClient client;
@@ -451,33 +476,40 @@ public Builder withFlagsmithApiWrapper(FlagsmithApiWrapper flagsmithApiWrapper)
      * @return a FlagsmithClient
      */
     public FlagsmithClient build() {
-      final FlagsmithApiWrapper flagsmithApiWrapper;
+      if (configuration.getOfflineMode()) {
+        if (configuration.getOfflineHandler() == null) {
+          throw new FlagsmithRuntimeError("Offline handler must be provided to use offline mode.");
+        }
+      }
 
       if (this.flagsmithApiWrapper != null) {
-        flagsmithApiWrapper = this.flagsmithApiWrapper;
+        client.flagsmithSdk = this.flagsmithApiWrapper;
       } else if (cacheConfig != null) {
-        flagsmithApiWrapper = new FlagsmithApiWrapper(
+        client.flagsmithSdk = new FlagsmithApiWrapper(
             cacheConfig.getCache(),
             this.configuration,
             this.customHeaders,
             client.logger,
             apiKey);
       } else {
-        flagsmithApiWrapper = new FlagsmithApiWrapper(
+        client.flagsmithSdk = new FlagsmithApiWrapper(
             this.configuration,
             this.customHeaders,
             client.logger,
             apiKey);
       }
 
-      client.flagsmithSdk = flagsmithApiWrapper;
-
       if (configuration.getAnalyticsProcessor() != null) {
-        configuration.getAnalyticsProcessor().setApi(flagsmithApiWrapper);
+        configuration.getAnalyticsProcessor().setApi(client.flagsmithSdk);
         configuration.getAnalyticsProcessor().setLogger(client.logger);
       }
 
       if (configuration.getEnableLocalEvaluation()) {
+        if (configuration.getOfflineHandler() != null) {
+          throw new FlagsmithRuntimeError(
+              "Local evaluation and offline handler cannot be used together.");
+        }
+
         if (!apiKey.startsWith("ser.")) {
           throw new FlagsmithRuntimeError(
               "In order to use local evaluation, please generate a server key "
@@ -495,6 +527,14 @@ public FlagsmithClient build() {
         client.pollingManager.startPolling();
       }
 
+      if (configuration.getOfflineHandler() != null) {
+        if (configuration.getFlagsmithFlagDefaults() != null) {
+          throw new FlagsmithRuntimeError(
+            "Cannot use both default flag handler and offline handler.");
+        }
+        client.environment = configuration.getOfflineHandler().getEnvironment();
+      }
+
       return this.client;
     }
   }

src/main/java/com/flagsmith/config/FlagsmithConfig.java

@@ -1,6 +1,7 @@
 package com.flagsmith.config;
 
 import com.flagsmith.FlagsmithFlagDefaults;
+import com.flagsmith.interfaces.IOfflineHandler;
 import com.flagsmith.threads.AnalyticsProcessor;
 
 import java.net.Proxy;
@@ -42,6 +43,8 @@ public final class FlagsmithConfig {
   private AnalyticsProcessor analyticsProcessor;
   private FlagsmithFlagDefaults flagsmithFlagDefaults = null;
   private Boolean raiseUpdateEnvironmentErrorsOnStartup = true;
+  private Boolean offlineMode = false;
+  private IOfflineHandler offlineHandler = null;
 
   protected FlagsmithConfig(Builder builder) {
     this.baseUri = builder.baseUri;
@@ -75,6 +78,9 @@ protected FlagsmithConfig(Builder builder) {
         analyticsProcessor = new AnalyticsProcessor(httpClient);
       }
     }
+
+    this.offlineMode = builder.offlineMode;
+    this.offlineHandler = builder.offlineHandler;
   }
 
   public static FlagsmithConfig.Builder newBuilder() {
@@ -103,6 +109,9 @@ public static class Builder {
     private Integer environmentRefreshIntervalSeconds = DEFAULT_ENVIRONMENT_REFRESH_SECONDS;
     private Boolean enableAnalytics = Boolean.FALSE;
 
+    private Boolean offlineMode = Boolean.FALSE;
+    private IOfflineHandler offlineHandler;
+
     private Builder() {
     }
 
@@ -211,8 +220,8 @@ public Builder withLocalEvaluation(Boolean localEvaluation) {
     }
 
     /**
-     * set environment refresh rate with polling manager. Only needed when local evaluation is
-     * true.
+     * set environment refresh rate with polling manager. Only needed when local
+     * evaluation is true.
      *
      * @param seconds seconds
      * @return
@@ -234,7 +243,6 @@ public Builder withAnalyticsProcessor(AnalyticsProcessor processor) {
       return this;
     }
 
-
     /**
      * Enable Analytics Processor.
      *
@@ -246,6 +254,28 @@ public Builder withEnableAnalytics(Boolean enable) {
       return this;
     }
 
+    /**
+     * Enable offline mode.
+     *
+     * @param offlineMode boolean to enable offline mode
+     * @return
+     */
+    public Builder withOfflineMode(Boolean offlineMode) {
+      this.offlineMode = offlineMode;
+      return this;
+    }
+
+    /**
+     * Set the offline handler (used as a fallback or with offlineMode).
+     *
+     * @param offlineHandler the offline handler
+     * @return
+     */
+    public Builder withOfflineHandler(IOfflineHandler offlineHandler) {
+      this.offlineHandler = offlineHandler;
+      return this;
+    }
+
     public FlagsmithConfig build() {
       return new FlagsmithConfig(this);
     }

src/main/java/com/flagsmith/interfaces/IOfflineHandler.java

@@ -0,0 +1,7 @@
+package com.flagsmith.interfaces;
+
+import com.flagsmith.flagengine.environments.EnvironmentModel;
+
+public interface IOfflineHandler {
+  EnvironmentModel getEnvironment();
+}

src/main/java/com/flagsmith/offline/LocalFileHandler.java

@@ -0,0 +1,35 @@
+package com.flagsmith.offline;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.flagsmith.MapperFactory;
+import com.flagsmith.exceptions.FlagsmithClientError;
+import com.flagsmith.flagengine.environments.EnvironmentModel;
+import com.flagsmith.interfaces.IOfflineHandler;
+
+import java.io.File;
+import java.io.IOException;
+
+public class LocalFileHandler implements IOfflineHandler {
+  private EnvironmentModel environmentModel;
+  private ObjectMapper objectMapper = MapperFactory.getMapper();
+
+  /**
+   * Instantiate a LocalFileHandler for use as an OfflineHandler.
+   *
+   * @param filePath - path to a json file containing the environment data.
+   * @throws FlagsmithClientError
+   *
+   */
+  public LocalFileHandler(String filePath) throws FlagsmithClientError {
+    File file = new File(filePath);
+    try {
+      environmentModel = objectMapper.readValue(file, EnvironmentModel.class);
+    } catch (IOException e) {
+      throw new FlagsmithClientError("Unable to read environment from file " + filePath);
+    }
+  }
+
+  public EnvironmentModel getEnvironment() {
+    return environmentModel;
+  }
+}

src/test/java/com/flagsmith/DummyOfflineHandler.java

@@ -0,0 +1,10 @@
+package com.flagsmith;
+
+import com.flagsmith.flagengine.environments.EnvironmentModel;
+import com.flagsmith.interfaces.IOfflineHandler;
+
+public class DummyOfflineHandler implements IOfflineHandler {
+    public EnvironmentModel getEnvironment() {
+        return FlagsmithTestHelper.environmentModel();
+    }
+}