prepare 4.8.0 release

src/main/java/com/launchdarkly/client/Event.java

@@ -17,11 +17,17 @@ public Event(long creationDate, LDUser user) {
   public static final class Custom extends Event {
     final String key;
     final JsonElement data;
+    final Double metricValue;
 
-    public Custom(long timestamp, String key, LDUser user, JsonElement data) {
+    public Custom(long timestamp, String key, LDUser user, JsonElement data, Double metricValue) {
       super(timestamp, user);
       this.key = key;
       this.data = data;
+      this.metricValue = metricValue;
+    }
+
+    public Custom(long timestamp, String key, LDUser user, JsonElement data) {
+      this(timestamp, key, user, data, null);
     }
   }
 

src/main/java/com/launchdarkly/client/EventFactory.java

@@ -9,11 +9,29 @@ abstract class EventFactory {
   protected abstract long getTimestamp();
   protected abstract boolean isIncludeReasons();
 
+  public Event.FeatureRequest newFeatureRequestEvent(FeatureFlag flag, LDUser user, JsonElement value,
+      Integer variationIndex, EvaluationReason reason, JsonElement defaultValue, String prereqOf) {
+    boolean requireExperimentData = isExperiment(flag, reason);
+    return new Event.FeatureRequest(
+        getTimestamp(),
+        flag.getKey(),
+        user,
+        flag.getVersion(),
+        variationIndex,
+        value,
+        defaultValue,
+        prereqOf,
+        requireExperimentData || flag.isTrackEvents(),
+        flag.getDebugEventsUntilDate(),
+        (requireExperimentData || isIncludeReasons()) ? reason : null,
+        false
+    );
+  }
+
   public Event.FeatureRequest newFeatureRequestEvent(FeatureFlag flag, LDUser user, EvaluationDetail<JsonElement> result, JsonElement defaultVal) {
-    return new Event.FeatureRequest(getTimestamp(), flag.getKey(), user, flag.getVersion(),
-        result == null ? null : result.getVariationIndex(), result == null ? null : result.getValue(),
-        defaultVal, null, flag.isTrackEvents(), flag.getDebugEventsUntilDate(),
-        isIncludeReasons() ? result.getReason() : null, false);
+    return newFeatureRequestEvent(flag, user, result == null ? null : result.getValue(),
+        result == null ? null : result.getVariationIndex(), result == null ? null : result.getReason(),
+        defaultVal, null);
   }
 
   public Event.FeatureRequest newDefaultFeatureRequestEvent(FeatureFlag flag, LDUser user, JsonElement defaultValue,
@@ -31,25 +49,52 @@ public Event.FeatureRequest newUnknownFeatureRequestEvent(String key, LDUser use
 
   public Event.FeatureRequest newPrerequisiteFeatureRequestEvent(FeatureFlag prereqFlag, LDUser user, EvaluationDetail<JsonElement> result,
       FeatureFlag prereqOf) {
-    return new Event.FeatureRequest(getTimestamp(), prereqFlag.getKey(), user, prereqFlag.getVersion(),
-        result == null ? null : result.getVariationIndex(), result == null ? null : result.getValue(),
-        null, prereqOf.getKey(), prereqFlag.isTrackEvents(), prereqFlag.getDebugEventsUntilDate(),
-        isIncludeReasons() ? result.getReason() : null, false);
+    return newFeatureRequestEvent(prereqFlag, user, result == null ? null : result.getValue(),
+        result == null ? null : result.getVariationIndex(), result == null ? null : result.getReason(),
+        null, prereqOf.getKey());
   }
 
   public Event.FeatureRequest newDebugEvent(Event.FeatureRequest from) {
     return new Event.FeatureRequest(from.creationDate, from.key, from.user, from.version, from.variation, from.value,
         from.defaultVal, from.prereqOf, from.trackEvents, from.debugEventsUntilDate, from.reason, true);
   }
 
-  public Event.Custom newCustomEvent(String key, LDUser user, JsonElement data) {
-    return new Event.Custom(getTimestamp(), key, user, data);
+  public Event.Custom newCustomEvent(String key, LDUser user, JsonElement data, Double metricValue) {
+    return new Event.Custom(getTimestamp(), key, user, data, metricValue);
   }
 
   public Event.Identify newIdentifyEvent(LDUser user) {
     return new Event.Identify(getTimestamp(), user);
   }
 
+  private boolean isExperiment(FeatureFlag flag, EvaluationReason reason) {
+    if (reason == null) {
+      // doesn't happen in real life, but possible in testing
+      return false;
+    }
+    switch (reason.getKind()) { 
+    case FALLTHROUGH:
+      return flag.isTrackEventsFallthrough();
+    case RULE_MATCH:
+      if (!(reason instanceof EvaluationReason.RuleMatch)) {
+        // shouldn't be possible
+        return false;
+      }
+      EvaluationReason.RuleMatch rm = (EvaluationReason.RuleMatch)reason;
+      int ruleIndex = rm.getRuleIndex();
+      // Note, it is OK to rely on the rule index rather than the unique ID in this context, because the
+      // FeatureFlag that is passed to us here *is* necessarily the same version of the flag that was just
+      // evaluated, so we cannot be out of sync with its rule list.
+      if (ruleIndex >= 0 && ruleIndex < flag.getRules().size()) {
+        Rule rule = flag.getRules().get(ruleIndex);
+        return rule.isTrackEvents();
+      }
+      return false;
+    default:
+      return false;
+    }
+  }
+
   public static class DefaultEventFactory extends EventFactory {
     private final boolean includeReasons;
 

src/main/java/com/launchdarkly/client/EventOutput.java

@@ -80,13 +80,15 @@ static final class Custom extends EventOutputWithTimestamp {
     private final String userKey;
     private final LDUser user;
     private final JsonElement data;
+    private final Double metricValue;
 
-    Custom(long creationDate, String key, String userKey, LDUser user, JsonElement data) {
+    Custom(long creationDate, String key, String userKey, LDUser user, JsonElement data, Double metricValue) {
       super("custom", creationDate);
       this.key = key;
       this.userKey = userKey;
       this.user = user;
       this.data = data;
+      this.metricValue = metricValue;
     }
   }
 
@@ -174,7 +176,8 @@ private EventOutput createOutputEvent(Event e) {
         return new EventOutput.Custom(ce.creationDate, ce.key,
             inlineUsers ? null : userKey,
             inlineUsers ? e.user : null,
-            ce.data);
+            ce.data,
+            ce.metricValue);
       } else if (e instanceof Event.Index) {
         return new EventOutput.Index(e.creationDate, e.user);
       } else {

src/main/java/com/launchdarkly/client/FeatureFlag.java

@@ -29,6 +29,7 @@ class FeatureFlag implements VersionedData {
   private List<JsonElement> variations;
   private boolean clientSide;
   private boolean trackEvents;
+  private boolean trackEventsFallthrough;
   private Long debugEventsUntilDate;
   private boolean deleted;
 
@@ -37,7 +38,8 @@ class FeatureFlag implements VersionedData {
 
   FeatureFlag(String key, int version, boolean on, List<Prerequisite> prerequisites, String salt, List<Target> targets,
       List<Rule> rules, VariationOrRollout fallthrough, Integer offVariation, List<JsonElement> variations,
-      boolean clientSide, boolean trackEvents, Long debugEventsUntilDate, boolean deleted) {
+      boolean clientSide, boolean trackEvents, boolean trackEventsFallthrough,
+      Long debugEventsUntilDate, boolean deleted) {
     this.key = key;
     this.version = version;
     this.on = on;
@@ -50,6 +52,7 @@ class FeatureFlag implements VersionedData {
     this.variations = variations;
     this.clientSide = clientSide;
     this.trackEvents = trackEvents;
+    this.trackEventsFallthrough = trackEventsFallthrough;
     this.debugEventsUntilDate = debugEventsUntilDate;
     this.deleted = deleted;
   }
@@ -167,6 +170,10 @@ public boolean isTrackEvents() {
     return trackEvents;
   }
 
+  public boolean isTrackEventsFallthrough() {
+    return trackEventsFallthrough;
+  }
+
   public Long getDebugEventsUntilDate() {
     return debugEventsUntilDate;
   }

src/main/java/com/launchdarkly/client/FeatureFlagBuilder.java

@@ -19,6 +19,7 @@ class FeatureFlagBuilder {
   private List<JsonElement> variations = new ArrayList<>();
   private boolean clientSide;
   private boolean trackEvents;
+  private boolean trackEventsFallthrough;
   private Long debugEventsUntilDate;
   private boolean deleted;
 
@@ -40,6 +41,7 @@ class FeatureFlagBuilder {
       this.variations = f.getVariations();
       this.clientSide = f.isClientSide();
       this.trackEvents = f.isTrackEvents();
+      this.trackEventsFallthrough = f.isTrackEventsFallthrough();
       this.debugEventsUntilDate = f.getDebugEventsUntilDate();
       this.deleted = f.isDeleted();
     }
@@ -103,6 +105,11 @@ FeatureFlagBuilder trackEvents(boolean trackEvents) {
     this.trackEvents = trackEvents;
     return this;
   }
+
+  FeatureFlagBuilder trackEventsFallthrough(boolean trackEventsFallthrough) {
+    this.trackEventsFallthrough = trackEventsFallthrough;
+    return this;
+  }
 
   FeatureFlagBuilder debugEventsUntilDate(Long debugEventsUntilDate) {
     this.debugEventsUntilDate = debugEventsUntilDate;
@@ -116,6 +123,6 @@ FeatureFlagBuilder deleted(boolean deleted) {
 
   FeatureFlag build() {
     return new FeatureFlag(key, version, on, prerequisites, salt, targets, rules, fallthrough, offVariation, variations,
-        clientSide, trackEvents, debugEventsUntilDate, deleted);
+        clientSide, trackEvents, trackEventsFallthrough, debugEventsUntilDate, deleted);
   }
 }

src/main/java/com/launchdarkly/client/LDClient.java

@@ -108,25 +108,28 @@ public LDClient(String sdkKey, LDConfig config) {
   public boolean initialized() {
     return updateProcessor.initialized();
   }
-
+
+  @Override
+  public void track(String eventName, LDUser user) {
+    track(eventName, user, null);
+  }
+
   @Override
   public void track(String eventName, LDUser user, JsonElement data) {
-    if (isOffline()) {
-      return;
-    }
     if (user == null || user.getKey() == null) {
       logger.warn("Track called with null user or null user key!");
     } else {
-      eventProcessor.sendEvent(EventFactory.DEFAULT.newCustomEvent(eventName, user, data));
+      eventProcessor.sendEvent(EventFactory.DEFAULT.newCustomEvent(eventName, user, data, null));
     }
   }
 
   @Override
-  public void track(String eventName, LDUser user) {
-    if (isOffline()) {
-      return;
+  public void track(String eventName, LDUser user, JsonElement data, double metricValue) {
+    if (user == null || user.getKey() == null) {
+      logger.warn("Track called with null user or null user key!");
+    } else {
+      eventProcessor.sendEvent(EventFactory.DEFAULT.newCustomEvent(eventName, user, data, metricValue));
     }
-    track(eventName, user, null);
   }
 
   @Override

src/main/java/com/launchdarkly/client/LDClientInterface.java

@@ -17,17 +17,35 @@ public interface LDClientInterface extends Closeable {
    *
    * @param eventName the name of the event
    * @param user      the user that performed the event
-   * @param data      a JSON object containing additional data associated with the event
    */
-  void track(String eventName, LDUser user, JsonElement data);
+  void track(String eventName, LDUser user);
 
   /**
-   * Tracks that a user performed an event.
+   * Tracks that a user performed an event, and provides additional custom data.
    *
    * @param eventName the name of the event
    * @param user      the user that performed the event
+   * @param data      a JSON object containing additional data associated with the event; may be null
    */
-  void track(String eventName, LDUser user);
+  void track(String eventName, LDUser user, JsonElement data);
+
+  /**
+   * Tracks that a user performed an event, and provides an additional numeric value for custom metrics.
+   * <p>
+   * As of this version’s release date, the LaunchDarkly service does not support the {@code metricValue}
+   * parameter. As a result, calling this overload of {@code track} will not yet produce any different
+   * behavior from calling {@link #track(String, LDUser, JsonElement)} without a {@code metricValue}.
+   * Refer to the <a href="https://docs.launchdarkly.com/docs/java-sdk-reference#section-track">SDK reference guide</a> for the latest status.
+   * 
+   * @param eventName the name of the event
+   * @param user      the user that performed the event
+   * @param data      a JSON object containing additional data associated with the event; may be null
+   * @param metricValue a numeric value used by the LaunchDarkly experimentation feature in numeric custom
+   * metrics. Can be omitted if this event is used by only non-numeric metrics. This field will also be
+   * returned as part of the custom event for Data Export.
+   * @since 4.8.0
+   */
+  void track(String eventName, LDUser user, JsonElement data, double metricValue);
 
   /**
    * Registers the user.
@@ -80,7 +98,9 @@ public interface LDClientInterface extends Closeable {
 
   /**
    * Calculates the integer value of a feature flag for a given user.
-   *
+   * <p>
+   * If the flag variation has a numeric value that is not an integer, it is rounded toward zero (truncated).
+   * 
    * @param featureKey   the unique key for the feature flag
    * @param user         the end user requesting the flag
    * @param defaultValue the default value of the flag
@@ -134,6 +154,9 @@ public interface LDClientInterface extends Closeable {
    * Calculates the value of a feature flag for a given user, and returns an object that describes the
    * way the value was determined. The {@code reason} property in the result will also be included in
    * analytics events, if you are capturing detailed event data for this flag.
+   * <p>
+   * If the flag variation has a numeric value that is not an integer, it is rounded toward zero (truncated).
+   * 
    * @param featureKey   the unique key for the feature flag
    * @param user         the end user requesting the flag
    * @param defaultValue the default value of the flag

src/main/java/com/launchdarkly/client/Rule.java

@@ -10,22 +10,36 @@
 class Rule extends VariationOrRollout {
   private String id;
   private List<Clause> clauses;
+  private boolean trackEvents;
 
   // We need this so Gson doesn't complain in certain java environments that restrict unsafe allocation
   Rule() {
     super();
   }
 
-  Rule(String id, List<Clause> clauses, Integer variation, Rollout rollout) {
+  Rule(String id, List<Clause> clauses, Integer variation, Rollout rollout, boolean trackEvents) {
     super(variation, rollout);
     this.id = id;
     this.clauses = clauses;
+    this.trackEvents = trackEvents;
+  }
+
+  Rule(String id, List<Clause> clauses, Integer variation, Rollout rollout) {
+    this(id, clauses, variation, rollout, false);
   }
 
   String getId() {
     return id;
   }
 
+  Iterable<Clause> getClauses() {
+    return clauses;
+  }
+
+  boolean isTrackEvents() {
+    return trackEvents;
+  }
+
   boolean matchesUser(FeatureStore store, LDUser user) {
     for (Clause clause : clauses) {
       if (!clause.matchesUser(store, user)) {

src/test/java/com/launchdarkly/client/DefaultEventProcessorTest.java

@@ -378,7 +378,8 @@ public void nonTrackedEventsAreSummarized() throws Exception {
   public void customEventIsQueuedWithUser() throws Exception {
     JsonObject data = new JsonObject();
     data.addProperty("thing", "stuff");
-    Event.Custom ce = EventFactory.DEFAULT.newCustomEvent("eventkey", user, data);
+    double metric = 1.5;
+    Event.Custom ce = EventFactory.DEFAULT.newCustomEvent("eventkey", user, data, metric);
 
     try (MockWebServer server = makeStartedServer(eventsSuccessResponse())) {
       try (DefaultEventProcessor ep = new DefaultEventProcessor(SDK_KEY, baseConfig(server).build())) {
@@ -396,7 +397,7 @@ public void customEventIsQueuedWithUser() throws Exception {
   public void customEventCanContainInlineUser() throws Exception {
     JsonObject data = new JsonObject();
     data.addProperty("thing", "stuff");
-    Event.Custom ce = EventFactory.DEFAULT.newCustomEvent("eventkey", user, data);
+    Event.Custom ce = EventFactory.DEFAULT.newCustomEvent("eventkey", user, data, null);
 
     try (MockWebServer server = makeStartedServer(eventsSuccessResponse())) {
       LDConfig config = baseConfig(server).inlineUsersInEvents(true).build();
@@ -413,7 +414,7 @@ public void customEventCanContainInlineUser() throws Exception {
   public void userIsFilteredInCustomEvent() throws Exception {
     JsonObject data = new JsonObject();
     data.addProperty("thing", "stuff");
-    Event.Custom ce = EventFactory.DEFAULT.newCustomEvent("eventkey", user, data);
+    Event.Custom ce = EventFactory.DEFAULT.newCustomEvent("eventkey", user, data, null);
 
     try (MockWebServer server = makeStartedServer(eventsSuccessResponse())) {
       LDConfig config = baseConfig(server).inlineUsersInEvents(true).allAttributesPrivate(true).build();
@@ -644,6 +645,7 @@ private Matcher<JsonElement> isFeatureEvent(Event.FeatureRequest sourceEvent, Fe
     );
   }
 
+  @SuppressWarnings("unchecked")
   private Matcher<JsonElement> isCustomEvent(Event.Custom sourceEvent, JsonElement inlineUser) {
     return allOf(
         hasJsonProperty("kind", "custom"),
@@ -653,7 +655,9 @@ private Matcher<JsonElement> isCustomEvent(Event.Custom sourceEvent, JsonElement
           hasJsonProperty("userKey", sourceEvent.user.getKeyAsString()),
         (inlineUser != null) ? hasJsonProperty("user", inlineUser) :
           hasJsonProperty("user", nullValue(JsonElement.class)),
-        hasJsonProperty("data", sourceEvent.data)
+        hasJsonProperty("data", sourceEvent.data),
+        (sourceEvent.metricValue == null) ? hasJsonProperty("metricValue", nullValue(JsonElement.class)) :
+          hasJsonProperty("metricValue", sourceEvent.metricValue.doubleValue())              
     );
   }