Merge pull request #196 from launchdarkly/eb/ch25268/flag-change-event

(5.0 - #4) implement flag change events

src/main/java/com/launchdarkly/sdk/server/Components.java

@@ -1,5 +1,6 @@
 package com.launchdarkly.sdk.server;
 
+import com.launchdarkly.sdk.LDUser;
 import com.launchdarkly.sdk.LDValue;
 import com.launchdarkly.sdk.server.DiagnosticEvent.ConfigProperty;
 import com.launchdarkly.sdk.server.integrations.EventProcessorBuilder;
@@ -16,6 +17,8 @@
 import com.launchdarkly.sdk.server.interfaces.Event;
 import com.launchdarkly.sdk.server.interfaces.EventProcessor;
 import com.launchdarkly.sdk.server.interfaces.EventProcessorFactory;
+import com.launchdarkly.sdk.server.interfaces.FlagChangeListener;
+import com.launchdarkly.sdk.server.interfaces.FlagValueChangeListener;
 import com.launchdarkly.sdk.server.interfaces.PersistentDataStoreFactory;
 
 import java.io.IOException;
@@ -209,6 +212,31 @@ public static DataSourceFactory externalUpdatesOnly() {
     return NullDataSourceFactory.INSTANCE;
   }
 
+  /**
+   * Convenience method for creating a {@link FlagChangeListener} that tracks a flag's value for a specific user.
+   * <p>
+   * This listener instance should only be used with a single {@link LDClient} instance. When you first
+   * register it by calling {@link LDClientInterface#registerFlagChangeListener(FlagChangeListener)}, it
+   * immediately evaluates the flag. It then re-evaluates the flag whenever there is an update, and calls
+   * your {@link FlagValueChangeListener} if and only if the resulting value has changed.
+   * <p>
+   * See {@link FlagValueChangeListener} for more information and examples.
+   * 
+   * @param client the same client instance that you will be registering this listener with
+   * @param flagKey the flag key to be evaluated
+   * @param user the user properties for evaluation
+   * @param valueChangeListener an object that you provide which will be notified of changes
+   * @return a {@link FlagChangeListener} to be passed to {@link LDClientInterface#registerFlagChangeListener(FlagChangeListener)}
+   * 
+   * @since 5.0.0
+   * @see FlagValueChangeListener
+   * @see FlagChangeListener
+   */
+  public static FlagChangeListener flagValueMonitoringListener(LDClientInterface client, String flagKey, LDUser user,
+      FlagValueChangeListener valueChangeListener) {
+    return new FlagValueMonitoringListener(client, flagKey, user, valueChangeListener);
+  }
+
   private static final class InMemoryDataStoreFactory implements DataStoreFactory, DiagnosticDescription {
     static final DataStoreFactory INSTANCE = new InMemoryDataStoreFactory();
     @Override

src/main/java/com/launchdarkly/sdk/server/DataModel.java

@@ -12,6 +12,8 @@
 import java.util.List;
 import java.util.Set;
 
+import static java.util.Collections.emptyList;
+
 /**
  * Contains information about the internal data model for feature flags and user segments.
  * <p>
@@ -151,28 +153,32 @@ boolean isOn() {
       return on;
     }
 
+    // Guaranteed non-null
     List<Prerequisite> getPrerequisites() {
-      return prerequisites;
+      return prerequisites == null ? emptyList() : prerequisites;
     }
 
     String getSalt() {
       return salt;
     }
 
+    // Guaranteed non-null
     List<Target> getTargets() {
-      return targets;
+      return targets == null ? emptyList() : targets;
     }
 
+    // Guaranteed non-null
     List<Rule> getRules() {
-      return rules;
+      return rules == null ? emptyList() : rules;
     }
 
     VariationOrRollout getFallthrough() {
       return fallthrough;
     }
 
+    // Guaranteed non-null
     List<LDValue> getVariations() {
-      return variations;
+      return variations == null ? emptyList() : variations;
     }
 
     Integer getOffVariation() {
@@ -241,8 +247,9 @@ static final class Target {
       this.variation = variation;
     }
 
+    // Guaranteed non-null
     Collection<String> getValues() {
-      return values;
+      return values == null ? emptyList() : values;
     }
 
     int getVariation() {
@@ -277,8 +284,9 @@ String getId() {
       return id;
     }
 
+    // Guaranteed non-null
     List<Clause> getClauses() {
-      return clauses;
+      return clauses == null ? emptyList() : clauses;
     }
 
     boolean isTrackEvents() {
@@ -417,20 +425,23 @@ public String getKey() {
       return key;
     }
 
+    // Guaranteed non-null
     Collection<String> getIncluded() {
-      return included;
+      return included == null ? emptyList() : included;
     }
 
+    // Guaranteed non-null
     Collection<String> getExcluded() {
-      return excluded;
+      return excluded == null ? emptyList() : excluded;
     }
 
     String getSalt() {
       return salt;
     }
 
+    // Guaranteed non-null
     List<SegmentRule> getRules() {
-      return rules;
+      return rules == null ? emptyList() : rules;
     }
 
     public int getVersion() {
@@ -453,8 +464,9 @@ static final class SegmentRule {
       this.bucketBy = bucketBy;
     }
 
+    // Guaranteed non-null
     List<Clause> getClauses() {
-      return clauses;
+      return clauses == null ? emptyList() : clauses;
     }
 
     Integer getWeight() {