prepare 4.3.0 release (#134)

Author: eli-darkly

CHANGELOG.md

@@ -3,6 +3,18 @@
 
 All notable changes to the LaunchDarkly Java SDK will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [4.3.0] - 2018-08-27
+### Added:
+- The new `LDClient` method `allFlagsState()` should be used instead of `allFlags()` if you are passing flag data to the front end for use with the JavaScript SDK. It preserves some flag metadata that the front end requires in order to send analytics events correctly. Versions 2.5.0 and above of the JavaScript SDK are able to use this metadata, but the output of `allFlagsState()` will still work with older versions.
+- The `allFlagsState()` method also allows you to select only client-side-enabled flags to pass to the front end, by using the option `FlagsStateOption.CLIENT_SIDE_ONLY`. ([#112](https://github.com/launchdarkly/java-client/issues/112))
+- The new `LDClient` methods `boolVariationDetail`, `intVariationDetail`, `doubleVariationDetail`, `stringVariationDetail`, and `jsonVariationDetail` allow you to evaluate a feature flag (using the same parameters as you would for `boolVariation`, etc.) and receive more information about how the value was calculated. This information is returned in an `EvaluationDetail` object, which contains both the result value and an `EvaluationReason` which will tell you, for instance, if the user was individually targeted for the flag or was matched by one of the flag's rules, or if the flag returned the default value due to an error.
+
+### Fixed:
+- Fixed a bug in `LDUser.Builder` that would throw an exception if you initialized the builder by copying an existing user, and then tried to add a custom attribute.
+
+### Deprecated:
+- `LDClient.allFlags()`
+
 ## [4.2.2] - 2018-08-17
 ### Fixed:
 - When logging errors related to the evaluation of a specific flag, the log message now always includes the flag key.

README.md

@@ -18,7 +18,7 @@ Quick setup
         <dependency>
           <groupId>com.launchdarkly</groupId>
           <artifactId>launchdarkly-client</artifactId>
-          <version>4.2.1</version>
+          <version>4.3.0</version>
         </dependency>
 
 1. Import the LaunchDarkly package:

gradle.properties

@@ -1,3 +1,3 @@
-version=4.2.2
+version=4.3.0
 ossrhUsername=
 ossrhPassword=

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

@@ -18,6 +18,7 @@ public abstract class Components {
 
   /**
    * Returns a factory for the default in-memory implementation of {@link FeatureStore}.
+   * @return a factory object
    */
   public static FeatureStoreFactory inMemoryFeatureStore() {
     return inMemoryFeatureStoreFactory;
@@ -26,6 +27,7 @@ public static FeatureStoreFactory inMemoryFeatureStore() {
   /**
    * Returns a factory with builder methods for creating a Redis-backed implementation of {@link FeatureStore},
    * using {@link RedisFeatureStoreBuilder#DEFAULT_URI}.
+   * @return a factory/builder object
    */
   public static RedisFeatureStoreBuilder redisFeatureStore() {
     return new RedisFeatureStoreBuilder();
@@ -34,6 +36,8 @@ public static RedisFeatureStoreBuilder redisFeatureStore() {
   /**
    * Returns a factory with builder methods for creating a Redis-backed implementation of {@link FeatureStore},
    * specifying the Redis URI.
+   * @param redisUri the URI of the Redis host
+   * @return a factory/builder object
    */
   public static RedisFeatureStoreBuilder redisFeatureStore(URI redisUri) {
     return new RedisFeatureStoreBuilder(redisUri);
@@ -43,6 +47,7 @@ public static RedisFeatureStoreBuilder redisFeatureStore(URI redisUri) {
    * Returns a factory for the default implementation of {@link EventProcessor}, which
    * forwards all analytics events to LaunchDarkly (unless the client is offline or you have
    * set {@link LDConfig.Builder#sendEvents(boolean)} to {@code false}).
+   * @return a factory object
    */
   public static EventProcessorFactory defaultEventProcessor() {
     return defaultEventProcessorFactory;
@@ -51,6 +56,7 @@ public static EventProcessorFactory defaultEventProcessor() {
   /**
    * Returns a factory for a null implementation of {@link EventProcessor}, which will discard
    * all analytics events and not send them to LaunchDarkly, regardless of any other configuration.
+   * @return a factory object
    */
   public static EventProcessorFactory nullEventProcessor() {
     return nullEventProcessorFactory;
@@ -60,6 +66,7 @@ public static EventProcessorFactory nullEventProcessor() {
    * Returns a factory for the default implementation of {@link UpdateProcessor}, which receives
    * feature flag data from LaunchDarkly using either streaming or polling as configured (or does
    * nothing if the client is offline, or in LDD mode).
+   * @return a factory object
    */
   public static UpdateProcessorFactory defaultUpdateProcessor() {
     return defaultUpdateProcessorFactory;
@@ -68,6 +75,7 @@ public static UpdateProcessorFactory defaultUpdateProcessor() {
   /**
    * Returns a factory for a null implementation of {@link UpdateProcessor}, which does not
    * connect to LaunchDarkly, regardless of any other configuration.
+   * @return a factory object
    */
   public static UpdateProcessorFactory nullUpdateProcessor() {
     return nullUpdateProcessorFactory;

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

@@ -0,0 +1,80 @@
+package com.launchdarkly.client;
+
+import com.google.common.base.Objects;
+
+/**
+ * An object returned by the "variation detail" methods such as {@link LDClientInterface#boolVariationDetail(String, LDUser, boolean)},
+ * combining the result of a flag evaluation with an explanation of how it was calculated.
+ * @since 4.3.0
+ */
+public class EvaluationDetail<T> {
+
+  private final EvaluationReason reason;
+  private final Integer variationIndex;
+  private final T value;
+  
+  public EvaluationDetail(EvaluationReason reason, Integer variationIndex, T value) {
+    this.reason = reason;
+    this.variationIndex = variationIndex;
+    this.value = value;
+  }
+  
+  static <T> EvaluationDetail<T> error(EvaluationReason.ErrorKind errorKind, T defaultValue) {
+    return new EvaluationDetail<>(EvaluationReason.error(errorKind), null, defaultValue);
+  }
+  
+  /**
+   * An object describing the main factor that influenced the flag evaluation value.
+   * @return an {@link EvaluationReason}
+   */
+  public EvaluationReason getReason() {
+    return reason;
+  }
+
+  /**
+   * The index of the returned value within the flag's list of variations, e.g. 0 for the first variation -
+   * or {@code null} if the default value was returned.
+   * @return the variation index or null
+   */
+  public Integer getVariationIndex() {
+    return variationIndex;
+  }
+
+  /**
+   * The result of the flag evaluation. This will be either one of the flag's variations or the default
+   * value that was passed to the {@code variation} method.
+   * @return the flag value
+   */
+  public T getValue() {
+    return value;
+  }
+  
+  /**
+   * Returns true if the flag evaluation returned the default value, rather than one of the flag's
+   * variations.
+   * @return true if this is the default value
+   */
+  public boolean isDefaultValue() {
+    return variationIndex == null;
+  }
+  
+  @Override
+  public boolean equals(Object other) {
+    if (other instanceof EvaluationDetail) {
+      @SuppressWarnings("unchecked")
+      EvaluationDetail<T> o = (EvaluationDetail<T>)other;
+      return Objects.equal(reason, o.reason) && Objects.equal(variationIndex, o.variationIndex) && Objects.equal(value, o.value);
+    }
+    return false;
+  }
+  
+  @Override
+  public int hashCode() {
+    return Objects.hashCode(reason, variationIndex, value);
+  }
+  
+  @Override
+  public String toString() {
+    return "{" + reason + "," + variationIndex + "," + value + "}";
+  }
+}

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

@@ -3,6 +3,7 @@
 /**
  * An error indicating an abnormal result from evaluating a feature
  */
+@SuppressWarnings("serial")
 class EvaluationException extends Exception {
   public EvaluationException(String message) {
     super(message);