Merge pull request #32 from launchdarkly/jko/store-javadoc

Store javadocs

Author: jkodumal

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

@@ -66,7 +66,7 @@ public interface FeatureStore {
   void upsert(String key, FeatureRep<?> feature);
 
   /**
-   * Returns true if this store has been initialized (i.e. if {@link #init(java.util.Map)} has been called)
+   * Returns true if this store has been initialized
    *
    * @return true if this store has been initialized
    */

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

@@ -4,12 +4,29 @@
 import java.util.Map;
 import java.util.concurrent.locks.ReentrantReadWriteLock;
 
+/**
+ * A thread-safe, versioned store for {@link com.launchdarkly.client.FeatureRep} objects based on a
+ * {@link HashMap}
+ *
+ */
 public class InMemoryFeatureStore implements FeatureStore {
 
   final ReentrantReadWriteLock lock = new ReentrantReadWriteLock();
   final Map<String, FeatureRep<?>> features = new HashMap<String, FeatureRep<?>>();
   volatile boolean initialized = false;
 
+
+  /**
+   *
+   * Returns the {@link com.launchdarkly.client.FeatureRep} to which the specified key is mapped, or
+   * null if the key is not associated or the associated {@link com.launchdarkly.client.FeatureRep} has
+   * been deleted.
+   *
+   * @param key the key whose associated {@link com.launchdarkly.client.FeatureRep} is to be returned
+   * @return the {@link com.launchdarkly.client.FeatureRep} to which the specified key is mapped, or
+   * null if the key is not associated or the associated {@link com.launchdarkly.client.FeatureRep} has
+   * been deleted.
+   */
   @Override
   public FeatureRep<?> get(String key) {
     try {
@@ -24,6 +41,12 @@ public FeatureRep<?> get(String key) {
     }
   }
 
+  /**
+   * Returns a {@link java.util.Map} of all associated features.
+   *
+   *
+   * @return a map of all associated features.
+   */
   @Override
   public Map<String, FeatureRep<?>> all() {
     try {
@@ -41,18 +64,33 @@ public Map<String, FeatureRep<?>> all() {
     }
   }
 
+
+  /**
+   * Initializes (or re-initializes) the store with the specified set of features. Any existing entries
+   * will be removed.
+   *
+   * @param features the features to set the store
+   */
   @Override
-  public void init(Map<String, FeatureRep<?>> fs) {
+  public void init(Map<String, FeatureRep<?>> features) {
     try {
       lock.writeLock().lock();
       this.features.clear();
-      this.features.putAll(fs);
+      this.features.putAll(features);
       initialized = true;
     } finally {
       lock.writeLock().unlock();
     }
   }
 
+  /**
+   *
+   * Deletes the feature associated with the specified key, if it exists and its version
+   * is less than or equal to the specified version.
+   *
+   * @param key the key of the feature to be deleted
+   * @param version the version for the delete operation
+   */
   @Override
   public void delete(String key, int version) {
     try {
@@ -72,6 +110,13 @@ else if (f == null) {
     }
   }
 
+  /**
+   * Update or insert the feature associated with the specified key, if its version
+   * is less than or equal to the version specified in the argument feature.
+   *
+   * @param key
+   * @param feature
+   */
   @Override
   public void upsert(String key, FeatureRep<?> feature) {
     try {
@@ -87,6 +132,11 @@ public void upsert(String key, FeatureRep<?> feature) {
     }
   }
 
+  /**
+   * Returns true if this store has been initialized
+   *
+   * @return true if this store has been initialized
+   */
   @Override
   public boolean initialized() {
     return initialized;

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

@@ -34,6 +34,7 @@ public final class LDConfig {
   final boolean stream;
   final boolean debugStreaming;
   final FeatureStore featureStore;
+  final boolean useLdd;
 
   protected LDConfig(Builder builder) {
     this.baseURI = builder.baseURI;
@@ -46,6 +47,7 @@ protected LDConfig(Builder builder) {
     this.stream = builder.stream;
     this.debugStreaming = builder.debugStreaming;
     this.featureStore = builder.featureStore;
+    this.useLdd = builder.useLdd;
   }
 
   /**
@@ -72,6 +74,7 @@ public static class Builder{
     private String proxyScheme;
     private boolean stream = true;
     private boolean debugStreaming = false;
+    private boolean useLdd = false;
     private FeatureStore featureStore = new InMemoryFeatureStore();
 
     /**
@@ -110,7 +113,7 @@ public Builder featureStore(FeatureStore store) {
      * retrieved feature with the value in the feature store. There is a performance cost to this, so it is not
      * recommended for production use.
      * @param debugStreaming whether streaming mode should be debugged
-     * @return
+     * @return the builder
      */
     public Builder debugStreaming(boolean debugStreaming) {
       this.debugStreaming = debugStreaming;
@@ -215,7 +218,7 @@ public Builder capacity(int capacity) {
      * a proxy will not be used, and {@link LDClient} will connect to LaunchDarkly directly.
      * </p>
      * @param host
-     * @return
+     * @return the builder
      */
     public Builder proxyHost(String host) {
       this.proxyHost = host;
@@ -231,7 +234,7 @@ public Builder proxyHost(String host) {
      * a proxy will not be used, and {@link LDClient} will connect to LaunchDarkly directly.
      * </p>
      * @param port
-     * @return
+     * @return the builder
      */
     public Builder proxyPort(int port) {
       this.proxyPort = port;
@@ -247,13 +250,24 @@ public Builder proxyPort(int port) {
      * a proxy will not be used, and {@link LDClient} will connect to LaunchDarkly directly.
      * </p>
      * @param scheme
-     * @return
+     * @return the builder
      */
     public Builder proxyScheme(String scheme) {
       this.proxyScheme = scheme;
       return this;
     }
 
+    /**
+     * Set whether this client should subscribe to the streaming API, or whether the LaunchDarkly daemon is in use
+     * instead
+     * @param useLdd
+     * @return the builder
+     */
+    public Builder useLdd(boolean useLdd) {
+      this.useLdd = useLdd;
+      return this;
+    }
+
     HttpHost proxyHost() {
       if (this.proxyHost == null && this.proxyPort == -1 && this.proxyScheme == null) {
         return null;

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

@@ -15,24 +15,47 @@
 import java.util.Map;
 import java.util.concurrent.TimeUnit;
 
+/**
+ * A thread-safe, versioned store for {@link com.launchdarkly.client.FeatureRep} objects backed by Redis. Also
+ * supports an optional in-memory cache configuration that can be used to improve performance.
+ *
+ */
 public class RedisFeatureStore implements FeatureStore {
   private static final String DEFAULT_PREFIX = "launchdarkly";
   private final Jedis jedis;
   private LoadingCache<String, FeatureRep<?>> cache;
   private String prefix;
 
+  /**
+   *
+   * @param host the host for the Redis connection
+   * @param port the port for the Redis connection
+   * @param prefix a namespace prefix for all keys stored in Redis
+   * @param cacheTimeSecs an optional timeout for the in-memory cache. If set to 0, no in-memory caching will be performed
+   */
   public RedisFeatureStore(String host, int port, String prefix, long cacheTimeSecs) {
     jedis = new Jedis(host, port);
     setPrefix(prefix);
     createCache(cacheTimeSecs);
   }
 
+  /**
+   * Creates a new store instance that connects to Redis with the provided URI, prefix, and cache timeout.
+   *
+   * @param uri the URI for the Redis connection
+   * @param prefix a namespace prefix for all keys stored in Redis
+   * @param cacheTimeSecs an optional timeout for the in-memory cache. If set to 0, no in-memory caching will be performed
+   */
   public RedisFeatureStore(URI uri, String prefix, long cacheTimeSecs) {
     jedis = new Jedis(uri);
     setPrefix(prefix);
     createCache(cacheTimeSecs);
   }
 
+  /**
+   * Creates a new store instance that connects to Redis with a default connection (localhost port 6379) and no in-memory cache.
+   *
+   */
   public RedisFeatureStore() {
     jedis = new Jedis("localhost");
     this.prefix = DEFAULT_PREFIX;
@@ -59,7 +82,17 @@ public FeatureRep<?> load(String key) throws Exception {
     }
   }
 
-
+  /**
+   *
+   * Returns the {@link com.launchdarkly.client.FeatureRep} to which the specified key is mapped, or
+   * null if the key is not associated or the associated {@link com.launchdarkly.client.FeatureRep} has
+   * been deleted.
+   *
+   * @param key the key whose associated {@link com.launchdarkly.client.FeatureRep} is to be returned
+   * @return the {@link com.launchdarkly.client.FeatureRep} to which the specified key is mapped, or
+   * null if the key is not associated or the associated {@link com.launchdarkly.client.FeatureRep} has
+   * been deleted.
+   */
   @Override
   public FeatureRep<?> get(String key) {
     if (cache != null) {
@@ -69,6 +102,14 @@ public FeatureRep<?> get(String key) {
     }
   }
 
+
+  /**
+   * Returns a {@link java.util.Map} of all associated features. This implementation does not take advantage
+   * of the in-memory cache, so fetching all features will involve a fetch from Redis.
+   *
+   *
+   * @return a map of all associated features.
+   */
   @Override
   public Map<String, FeatureRep<?>> all() {
     Map<String,String> featuresJson = jedis.hgetAll(featuresKey());
@@ -84,7 +125,12 @@ public Map<String, FeatureRep<?>> all() {
 
     return result;
   }
-
+  /**
+   * Initializes (or re-initializes) the store with the specified set of features. Any existing entries
+   * will be removed.
+   *
+   * @param features the features to set the store
+   */
   @Override
   public void init(Map<String, FeatureRep<?>> features) {
     Gson gson = new Gson();
@@ -99,6 +145,15 @@ public void init(Map<String, FeatureRep<?>> features) {
     t.exec();
   }
 
+
+  /**
+   *
+   * Deletes the feature associated with the specified key, if it exists and its version
+   * is less than or equal to the specified version.
+   *
+   * @param key the key of the feature to be deleted
+   * @param version the version for the delete operation
+   */
   @Override
   public void delete(String key, int version) {
     try {
@@ -126,6 +181,13 @@ public void delete(String key, int version) {
 
   }
 
+  /**
+   * Update or insert the feature associated with the specified key, if its version
+   * is less than or equal to the version specified in the argument feature.
+   *
+   * @param key
+   * @param feature
+   */
   @Override
   public void upsert(String key, FeatureRep<?> feature) {
     try {
@@ -149,6 +211,11 @@ public void upsert(String key, FeatureRep<?> feature) {
     }
   }
 
+  /**
+   * Returns true if this store has been initialized
+   *
+   * @return true if this store has been initialized
+   */
   @Override
   public boolean initialized() {
     return jedis.exists(featuresKey());

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

@@ -42,6 +42,11 @@ class StreamProcessor implements Closeable {
   }
 
   void subscribe() {
+    // If the LaunchDarkly daemon is to be used, then do not subscribe to the stream
+    if (config.useLdd) {
+      return;
+    }
+
     MultivaluedMap<String, Object> headers = new StringKeyIgnoreCaseMultivaluedMap<Object>();
     headers.putSingle("Authorization", "api_key " + this.apiKey);
     headers.putSingle("User-Agent", "JavaClient/" + LDClient.CLIENT_VERSION);