prepare 4.5.0 release (#147)

Author: eli-darkly

README.md

@@ -53,6 +53,10 @@ Be aware of two considerations when enabling the DEBUG log level:
 1. Debug-level logs can be very verbose. It is not recommended that you turn on debug logging in high-volume environments.
 1. Potentially sensitive information is logged including LaunchDarkly users created by you in your usage of this SDK.
 
+Using flag data from a file
+---------------------------
+For testing purposes, the SDK can be made to read feature flag state from a file or files instead of connecting to LaunchDarkly. See <a href="http://javadoc.io/page/com.launchdarkly/launchdarkly-client/latest/com/launchdarkly/client/files/FileComponents.html">FileComponents</a> for more details.
+
 Learn more
 ----------
 

build.gradle

@@ -32,6 +32,7 @@ libraries.internal = [
     "com.google.guava:guava:19.0",
     "joda-time:joda-time:2.9.3",
     "com.launchdarkly:okhttp-eventsource:1.7.1",
+    "org.yaml:snakeyaml:1.19",
     "redis.clients:jedis:2.9.0"
 ]
 

src/main/java/com/launchdarkly/client/files/DataBuilder.java

@@ -0,0 +1,32 @@
+package com.launchdarkly.client.files;
+
+import com.launchdarkly.client.VersionedData;
+import com.launchdarkly.client.VersionedDataKind;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Internal data structure that organizes flag/segment data into the format that the feature store
+ * expects. Will throw an exception if we try to add the same flag or segment key more than once.
+ */
+class DataBuilder {
+  private final Map<VersionedDataKind<?>, Map<String, ? extends VersionedData>> allData = new HashMap<>();
+  
+  public Map<VersionedDataKind<?>, Map<String, ? extends VersionedData>> build() {
+    return allData;
+  }
+  
+  public void add(VersionedDataKind<?> kind, VersionedData item) throws DataLoaderException {
+    @SuppressWarnings("unchecked")
+    Map<String, VersionedData> items = (Map<String, VersionedData>)allData.get(kind);
+    if (items == null) {
+      items = new HashMap<String, VersionedData>();
+      allData.put(kind, items);
+    }
+    if (items.containsKey(item.getKey())) {
+      throw new DataLoaderException("in " + kind.getNamespace() + ", key \"" + item.getKey() + "\" was already defined", null, null);
+    }
+    items.put(item.getKey(), item);
+  }
+}

src/main/java/com/launchdarkly/client/files/DataLoader.java

@@ -0,0 +1,58 @@
+package com.launchdarkly.client.files;
+
+import com.google.gson.JsonElement;
+import com.launchdarkly.client.VersionedDataKind;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * Implements the loading of flag data from one or more files. Will throw an exception if any file can't
+ * be read or parsed, or if any flag or segment keys are duplicates.
+ */
+final class DataLoader {
+  private final List<Path> files;
+
+  public DataLoader(List<Path> files) {
+    this.files = new ArrayList<Path>(files);
+  }
+  
+  public Iterable<Path> getFiles() {
+    return files;
+  }
+  
+  public void load(DataBuilder builder) throws DataLoaderException
+  {
+    for (Path p: files) {
+      try {
+        byte[] data = Files.readAllBytes(p);
+        FlagFileParser parser = FlagFileParser.selectForContent(data);
+        FlagFileRep fileContents = parser.parse(new ByteArrayInputStream(data));
+        if (fileContents.flags != null) {
+          for (Map.Entry<String, JsonElement> e: fileContents.flags.entrySet()) {
+            builder.add(VersionedDataKind.FEATURES, FlagFactory.flagFromJson(e.getValue()));
+          }
+        }
+        if (fileContents.flagValues != null) {
+          for (Map.Entry<String, JsonElement> e: fileContents.flagValues.entrySet()) {
+            builder.add(VersionedDataKind.FEATURES, FlagFactory.flagWithValue(e.getKey(), e.getValue()));
+          }
+        }
+        if (fileContents.segments != null) {
+          for (Map.Entry<String, JsonElement> e: fileContents.segments.entrySet()) {
+            builder.add(VersionedDataKind.SEGMENTS, FlagFactory.segmentFromJson(e.getValue()));
+          }
+        }
+      } catch (DataLoaderException e) {
+        throw new DataLoaderException(e.getMessage(), e.getCause(), p);
+      } catch (IOException e) {
+        throw new DataLoaderException(null, e, p);
+      }
+    }
+  }
+}

src/main/java/com/launchdarkly/client/files/DataLoaderException.java

@@ -0,0 +1,43 @@
+package com.launchdarkly.client.files;
+
+import java.nio.file.Path;
+
+/**
+ * Indicates that the file processor encountered an error in one of the input files. This exception is
+ * not surfaced to the host application, it is only logged, and we don't do anything different programmatically
+ * with different kinds of exceptions, therefore it has no subclasses.
+ */
+@SuppressWarnings("serial")
+class DataLoaderException extends Exception {
+  private final Path filePath;
+  
+  public DataLoaderException(String message, Throwable cause, Path filePath) {
+    super(message, cause);
+    this.filePath = filePath;
+  }
+
+  public DataLoaderException(String message, Throwable cause) {
+    this(message, cause, null);
+  }
+
+  public Path getFilePath() {
+    return filePath;
+  }
+  
+  public String getDescription() {
+    StringBuilder s = new StringBuilder();
+    if (getMessage() != null) {
+      s.append(getMessage());
+      if (getCause() != null) {
+        s.append(" ");
+      }
+    }
+    if (getCause() != null) {
+      s.append(" [").append(getCause().toString()).append("]");
+    }
+    if (filePath != null) {
+      s.append(": ").append(filePath);
+    }
+    return s.toString();
+  }
+}

src/main/java/com/launchdarkly/client/files/FileComponents.java

@@ -0,0 +1,107 @@
+package com.launchdarkly.client.files;
+
+/**
+ * The entry point for the file data source, which allows you to use local files as a source of
+ * feature flag state. This would typically be used in a test environment, to operate using a
+ * predetermined feature flag state without an actual LaunchDarkly connection.
+ * <p>
+ * To use this component, call {@link #fileDataSource()} to obtain a factory object, call one or
+ * methods to configure it, and then add it to your LaunchDarkly client configuration. At a
+ * minimum, you will want to call {@link FileDataSourceFactory#filePaths(String...)} to specify
+ * your data file(s); you can also use {@link FileDataSourceFactory#autoUpdate(boolean)} to
+ * specify that flags should be reloaded when a file is modified. See {@link FileDataSourceFactory}
+ * for all configuration options.
+ * <pre>
+ *     FileDataSourceFactory f = FileComponents.fileDataSource()
+ *         .filePaths("./testData/flags.json")
+ *         .autoUpdate(true);
+ *     LDConfig config = new LDConfig.Builder()
+ *         .updateProcessorFactory(f)
+ *         .build();
+ * </pre>
+ * <p>
+ * This will cause the client <i>not</i> to connect to LaunchDarkly to get feature flags. The
+ * client may still make network connections to send analytics events, unless you have disabled
+ * this with {@link com.launchdarkly.client.LDConfig.Builder#sendEvents(boolean)} or
+ * {@link com.launchdarkly.client.LDConfig.Builder#offline(boolean)}.
+ * <p>
+ * Flag data files can be either JSON or YAML. They contain an object with three possible
+ * properties:
+ * <ul>
+ * <li> {@code flags}: Feature flag definitions.
+ * <li> {@code flagVersions}: Simplified feature flags that contain only a value.
+ * <li> {@code segments}: User segment definitions.
+ * </ul>
+ * <p>
+ * The format of the data in {@code flags} and {@code segments} is defined by the LaunchDarkly application
+ * and is subject to change. Rather than trying to construct these objects yourself, it is simpler
+ * to request existing flags directly from the LaunchDarkly server in JSON format, and use this
+ * output as the starting point for your file. In Linux you would do this:
+ * <pre>
+ *     curl -H "Authorization: {your sdk key}" https://app.launchdarkly.com/sdk/latest-all
+ * </pre>
+ * <p>
+ * The output will look something like this (but with many more properties):
+ * <pre>
+ * {
+ *     "flags": {
+ *         "flag-key-1": {
+ *             "key": "flag-key-1",
+ *             "on": true,
+ *             "variations": [ "a", "b" ]
+ *         },
+ *         "flag-key-2": {
+ *             "key": "flag-key-2",
+ *             "on": true,
+ *             "variations": [ "c", "d" ]
+ *         }
+ *     },
+ *     "segments": {
+ *         "segment-key-1": {
+ *             "key": "segment-key-1",
+ *             "includes": [ "user-key-1" ]
+ *         }
+ *     }
+ * }
+ * </pre>
+ * <p>
+ * Data in this format allows the SDK to exactly duplicate all the kinds of flag behavior supported
+ * by LaunchDarkly. However, in many cases you will not need this complexity, but will just want to
+ * set specific flag keys to specific values. For that, you can use a much simpler format:
+ * <pre>
+ * {
+ *     "flagValues": {
+ *         "my-string-flag-key": "value-1",
+ *         "my-boolean-flag-key": true,
+ *         "my-integer-flag-key": 3
+ *     }
+ * }
+ * </pre>
+ * <p>
+ * Or, in YAML:
+ * <pre>
+ * flagValues:
+ *   my-string-flag-key: "value-1"
+ *   my-boolean-flag-key: true
+ *   my-integer-flag-key: 3
+ * </pre>
+ * <p>
+ * It is also possible to specify both {@code flags} and {@code flagValues}, if you want some flags
+ * to have simple values and others to have complex behavior. However, it is an error to use the
+ * same flag key or segment key more than once, either in a single file or across multiple files.
+ * <p>
+ * If the data source encounters any error in any file-- malformed content, a missing file, or a
+ * duplicate key-- it will not load flags from any of the files.
+ * 
+ * @since 4.5.0
+ */
+public abstract class FileComponents {
+  /**
+   * Creates a {@link FileDataSourceFactory} which you can use to configure the file data
+   * source.
+   * @return a {@link FileDataSourceFactory}
+   */
+	public static FileDataSourceFactory fileDataSource() {
+		return new FileDataSourceFactory(); 
+	}
+}