Merge pull request #141 from dfa1/master

Minor javadoc fixes

Author: bbakerman

src/main/java/org/dataloader/BatchLoader.java

@@ -54,7 +54,7 @@
  * The back-end service returned results in a different order than we requested, likely because it was more efficient for it to
  * do so. Also, it omitted a result for key 6, which we may interpret as no value existing for that key.
  * <p>
- * To uphold the constraints of the batch function, it must return an List of values the same length as
+ * To uphold the constraints of the batch function, it must return a List of values the same length as
  * the List of keys, and re-order them to ensure each index aligns with the original keys [ 2, 9, 6, 1 ]:
  *
  * <pre>

src/main/java/org/dataloader/BatchLoaderEnvironment.java

@@ -54,7 +54,7 @@ public Map<Object, Object> getKeyContexts() {
      * {@link org.dataloader.DataLoader#loadMany(java.util.List, java.util.List)} can be given
      * a context object when it is invoked.  A list of them is present by this method.
      *
-     * @return a list of key context objects in the order they where encountered
+     * @return a list of key context objects in the order they were encountered
      */
     public List<Object> getKeyContextsList() {
         return keyContextsList;

src/main/java/org/dataloader/CacheMap.java

@@ -65,7 +65,7 @@ static <K, V> CacheMap<K, V> simpleMap() {
     /**
      * Gets the specified key from the cache map.
      * <p>
-     * May throw an exception if the key does not exists, depending on the cache map implementation that is used,
+     * May throw an exception if the key does not exist, depending on the cache map implementation that is used,
      * so be sure to check {@link CacheMap#containsKey(Object)} first.
      *
      * @param key the key to retrieve

src/main/java/org/dataloader/DataLoader.java

@@ -108,7 +108,7 @@ public static <K, V> DataLoader<K, V> newDataLoader(BatchLoader<K, V> batchLoadF
      * (batching, caching and unlimited batch size) where the batch loader function returns a list of
      * {@link org.dataloader.Try} objects.
      * <p>
-     * If its important you to know the exact status of each item in a batch call and whether it threw exceptions then
+     * If it's important you to know the exact status of each item in a batch call and whether it threw exceptions then
      * you can use this form to create the data loader.
      * <p>
      * Using Try objects allows you to capture a value returned or an exception that might
@@ -186,7 +186,7 @@ public static <K, V> DataLoader<K, V> newDataLoader(BatchLoaderWithContext<K, V>
      * (batching, caching and unlimited batch size) where the batch loader function returns a list of
      * {@link org.dataloader.Try} objects.
      * <p>
-     * If its important you to know the exact status of each item in a batch call and whether it threw exceptions then
+     * If it's important you to know the exact status of each item in a batch call and whether it threw exceptions then
      * you can use this form to create the data loader.
      * <p>
      * Using Try objects allows you to capture a value returned or an exception that might
@@ -264,7 +264,7 @@ public static <K, V> DataLoader<K, V> newMappedDataLoader(MappedBatchLoader<K, V
      * (batching, caching and unlimited batch size) where the batch loader function returns a list of
      * {@link org.dataloader.Try} objects.
      * <p>
-     * If its important you to know the exact status of each item in a batch call and whether it threw exceptions then
+     * If it's important you to know the exact status of each item in a batch call and whether it threw exceptions then
      * you can use this form to create the data loader.
      * <p>
      * Using Try objects allows you to capture a value returned or an exception that might
@@ -343,7 +343,7 @@ public static <K, V> DataLoader<K, V> newMappedDataLoader(MappedBatchLoaderWithC
      * (batching, caching and unlimited batch size) where the batch loader function returns a list of
      * {@link org.dataloader.Try} objects.
      * <p>
-     * If its important you to know the exact status of each item in a batch call and whether it threw exceptions then
+     * If it's important you to know the exact status of each item in a batch call and whether it threw exceptions then
      * you can use this form to create the data loader.
      * <p>
      * Using Try objects allows you to capture a value returned or an exception that might
@@ -471,11 +471,11 @@ public CompletableFuture<V> load(K key) {
      * This will return an optional promise to a value previously loaded via a {@link #load(Object)} call or empty if not call has been made for that key.
      * <p>
      * If you do get a present CompletableFuture it does not mean it has been dispatched and completed yet.  It just means
-     * its at least pending and in cache.
+     * it's at least pending and in cache.
      * <p>
      * If caching is disabled there will never be a present Optional returned.
      * <p>
-     * NOTE : This will NOT cause a data load to happen.  You must called {@link #load(Object)} for that to happen.
+     * NOTE : This will NOT cause a data load to happen. You must call {@link #load(Object)} for that to happen.
      *
      * @param key the key to check
      *
@@ -494,7 +494,7 @@ public Optional<CompletableFuture<V>> getIfPresent(K key) {
      * <p>
      * If caching is disabled there will never be a present Optional returned.
      * <p>
-     * NOTE : This will NOT cause a data load to happen.  You must called {@link #load(Object)} for that to happen.
+     * NOTE : This will NOT cause a data load to happen.  You must call {@link #load(Object)} for that to happen.
      *
      * @param key the key to check
      *

src/main/java/org/dataloader/DataLoaderFactory.java

@@ -42,7 +42,7 @@ public static <K, V> DataLoader<K, V> newDataLoader(BatchLoader<K, V> batchLoadF
      * (batching, caching and unlimited batch size) where the batch loader function returns a list of
      * {@link org.dataloader.Try} objects.
      * <p>
-     * If its important you to know the exact status of each item in a batch call and whether it threw exceptions then
+     * If it's important you to know the exact status of each item in a batch call and whether it threw exceptions then
      * you can use this form to create the data loader.
      * <p>
      * Using Try objects allows you to capture a value returned or an exception that might
@@ -109,7 +109,7 @@ public static <K, V> DataLoader<K, V> newDataLoader(BatchLoaderWithContext<K, V>
      * (batching, caching and unlimited batch size) where the batch loader function returns a list of
      * {@link org.dataloader.Try} objects.
      * <p>
-     * If its important you to know the exact status of each item in a batch call and whether it threw exceptions then
+     * If it's important you to know the exact status of each item in a batch call and whether it threw exceptions then
      * you can use this form to create the data loader.
      * <p>
      * Using Try objects allows you to capture a value returned or an exception that might
@@ -176,7 +176,7 @@ public static <K, V> DataLoader<K, V> newMappedDataLoader(MappedBatchLoader<K, V
      * (batching, caching and unlimited batch size) where the batch loader function returns a list of
      * {@link org.dataloader.Try} objects.
      * <p>
-     * If its important you to know the exact status of each item in a batch call and whether it threw exceptions then
+     * If it's important you to know the exact status of each item in a batch call and whether it threw exceptions then
      * you can use this form to create the data loader.
      * <p>
      * Using Try objects allows you to capture a value returned or an exception that might
@@ -244,7 +244,7 @@ public static <K, V> DataLoader<K, V> newMappedDataLoader(MappedBatchLoaderWithC
      * (batching, caching and unlimited batch size) where the batch loader function returns a list of
      * {@link org.dataloader.Try} objects.
      * <p>
-     * If its important you to know the exact status of each item in a batch call and whether it threw exceptions then
+     * If it's important you to know the exact status of each item in a batch call and whether it threw exceptions then
      * you can use this form to create the data loader.
      * <p>
      * Using Try objects allows you to capture a value returned or an exception that might

src/main/java/org/dataloader/DataLoaderHelper.java

@@ -34,8 +34,8 @@
 import static org.dataloader.impl.Assertions.nonNull;
 
 /**
- * This helps break up the large DataLoader class functionality and it contains the logic to dispatch the
- * promises on behalf of its peer dataloader
+ * This helps break up the large DataLoader class functionality, and it contains the logic to dispatch the
+ * promises on behalf of its peer dataloader.
  *
  * @param <K> the type of keys
  * @param <V> the type of values
@@ -148,13 +148,11 @@ CompletableFuture<V> load(K key, Object loadContext) {
         }
     }
 
-    @SuppressWarnings("unchecked")
     Object getCacheKey(K key) {
         return loaderOptions.cacheKeyFunction().isPresent() ?
                 loaderOptions.cacheKeyFunction().get().getKey(key) : key;
     }
 
-    @SuppressWarnings("unchecked")
     Object getCacheKeyWithContext(K key, Object context) {
         return loaderOptions.cacheKeyFunction().isPresent() ?
                 loaderOptions.cacheKeyFunction().get().getKeyWithContext(key, context) : key;
@@ -296,9 +294,9 @@ private void possiblyClearCacheEntriesOnExceptions(List<K> keys) {
         if (keys.isEmpty()) {
             return;
         }
-        // by default we don't clear the cached view of this entry to avoid
-        // frequently loading the same error.  This works for short lived request caches
-        // but might work against long lived caches.  Hence we have an option that allows
+        // by default, we don't clear the cached view of this entry to avoid
+        // frequently loading the same error.  This works for short-lived request caches
+        // but might work against long-lived caches. Hence, we have an option that allows
         // it to be cleared
         if (!loaderOptions.cachingExceptionsEnabled()) {
             keys.forEach(dataLoader::clear);
@@ -384,7 +382,7 @@ CompletableFuture<List<V>> invokeLoader(List<K> keys, List<Object> keyContexts,
                 return completedFuture(assembledValues);
             } else {
                 //
-                // we missed some of the keys from cache, so send them to the batch loader
+                // we missed some keys from cache, so send them to the batch loader
                 // and then fill in their values
                 //
                 CompletableFuture<List<V>> batchLoad = invokeLoader(missedKeys, missedKeyContexts);

src/main/java/org/dataloader/DataLoaderOptions.java

@@ -135,8 +135,8 @@ public DataLoaderOptions setCachingEnabled(boolean cachingEnabled) {
     /**
      * Option that determines whether to cache exceptional values (the default), or not.
      *
-     * For short lived caches (that is request caches) it makes sense to cache exceptions since
-     * its likely the key is still poisoned.  However if you have long lived caches, then it may make
+     * For short-lived caches (that is request caches) it makes sense to cache exceptions since
+     * it's likely the key is still poisoned.  However, if you have long-lived caches, then it may make
      * sense to set this to false since the downstream system may have recovered from its failure
      * mode.
      *
@@ -147,7 +147,7 @@ public boolean cachingExceptionsEnabled() {
     }
 
     /**
-     * Sets the option that determines whether exceptional values are cachedis enabled.
+     * Sets the option that determines whether exceptional values are cache enabled.
      *
      * @param cachingExceptionsEnabled {@code true} to enable caching exceptional values, {@code false} otherwise
      *
@@ -236,7 +236,7 @@ public StatisticsCollector getStatisticsCollector() {
 
     /**
      * Sets the statistics collector supplier that will be used with these data loader options.  Since it uses
-     * the supplier pattern, you can create a new statistics collector on each call or you can reuse
+     * the supplier pattern, you can create a new statistics collector on each call, or you can reuse
      * a common value
      *
      * @param statisticsCollector the statistics collector to use

src/main/java/org/dataloader/DataLoaderRegistry.java

@@ -127,7 +127,7 @@ public Set<String> getKeys() {
     }
 
     /**
-     * This will called {@link org.dataloader.DataLoader#dispatch()} on each of the registered
+     * This will be called {@link org.dataloader.DataLoader#dispatch()} on each of the registered
      * {@link org.dataloader.DataLoader}s
      */
     public void dispatchAll() {
@@ -197,7 +197,7 @@ public Builder register(String key, DataLoader<?, ?> dataLoader) {
         }
 
         /**
-         * This will combine together the data loaders in this builder with the ones
+         * This will combine the data loaders in this builder with the ones
          * from a previous {@link DataLoaderRegistry}
          *
          * @param otherRegistry the previous {@link DataLoaderRegistry}

src/main/java/org/dataloader/MappedBatchLoader.java

@@ -16,13 +16,12 @@
 
 package org.dataloader;
 
-import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.CompletionStage;
 
 /**
- * A function that is invoked for batch loading a map of of data values indicated by the provided set of keys. The
+ * A function that is invoked for batch loading a map of data values indicated by the provided set of keys. The
  * function returns a promise of a map of results of individual load requests.
  * <p>
  * There are a few constraints that must be upheld:

src/main/java/org/dataloader/MappedBatchLoaderWithContext.java

@@ -16,7 +16,6 @@
 
 package org.dataloader;
 
-import java.util.List;
 import java.util.Map;
 import java.util.Set;
 import java.util.concurrent.CompletionStage;

src/main/java/org/dataloader/Try.java

@@ -15,7 +15,7 @@
 /**
  * Try is class that allows you to hold the result of computation or the throwable it produced.
  *
- * This class is useful in {@link org.dataloader.BatchLoader}s so you can mix a batch of calls where some of
+ * This class is useful in {@link org.dataloader.BatchLoader}s so you can mix a batch of calls where some
  * the calls succeeded and some of them failed.  You would make your batch loader declaration like :
  *
  * <pre>
@@ -89,8 +89,8 @@ public static <V> Try<V> failed(Throwable throwable) {
     }
 
     /**
-     * This returns a Try that has always failed with an consistent exception.  Use this when
-     * yiu dont care about the exception but only that the Try failed.
+     * This returns a Try that has always failed with a consistent exception.  Use this when
+     * you don't care about the exception but only that the Try failed.
      *
      * @param <V> the type of value
      *

src/main/java/org/dataloader/ValueCache.java

@@ -15,11 +15,11 @@
  * <p>
  * It differs from {@link CacheMap} which is in fact a cache of promised values aka {@link CompletableFuture}&lt;V&gt;'s.
  * <p>
- * {@link ValueCache} is more suited to be a wrapper of a long-lived or externallly cached values.  {@link CompletableFuture}s cant
+ * {@link ValueCache} is more suited to be a wrapper of a long-lived or externally cached values.  {@link CompletableFuture}s can't
  * be easily placed in an external cache outside the JVM say, hence the need for the {@link ValueCache}.
  * <p>
  * {@link DataLoader}s use a two stage cache strategy if caching is enabled.  If the {@link CacheMap} already has the promise to a value
- * that is used.  If not then the {@link ValueCache} is asked for a value, if it has one then that is returned (and cached as a promise in the {@link CacheMap}.
+ * that is used.  If not then the {@link ValueCache} is asked for a value, if it has one then that is returned (and cached as a promise in the {@link CacheMap}).
  * <p>
  * If there is no value then the key is queued and loaded via the {@link BatchLoader} calls.  The returned values will then be stored in
  * the {@link ValueCache} and the promises to those values are also stored in the {@link CacheMap}.
@@ -29,7 +29,7 @@
  * out of the box.
  * <p>
  * The API signature uses {@link CompletableFuture}s because the backing implementation MAY be a remote external cache
- * and hence exceptions may happen in retrieving values and they may take time to complete.
+ * and hence exceptions may happen in retrieving values, and they may take time to complete.
  *
  * @param <K> the type of cache keys
  * @param <V> the type of cache values
@@ -67,8 +67,8 @@ static <K, V> ValueCache<K, V> defaultValueCache() {
     CompletableFuture<V> get(K key);
 
     /**
-     * Gets the specified keys from the value cache, in a batch call.  If your underlying cache cant do batch caching retrieval
-     * then do not implement this method and it will delegate back to {@link #get(Object)} for you
+     * Gets the specified keys from the value cache, in a batch call.  If your underlying cache cannot do batch caching retrieval
+     * then do not implement this method, and it will delegate back to {@link #get(Object)} for you
      * <p>
      * Each item in the returned list of values is a {@link Try}.  If the key could not be found then a failed Try just be returned otherwise
      * a successful Try contain the cached value is returned.
@@ -104,8 +104,8 @@ default CompletableFuture<List<Try<V>>> getValues(List<K> keys) throws ValueCach
     CompletableFuture<V> set(K key, V value);
 
     /**
-     * Stores the value with the specified keys, or updates it if the keys if they already exist.  If your underlying cache cant do batch caching setting
-     * then do not implement this method and it will delegate back to {@link #set(Object, Object)} for you
+     * Stores the value with the specified keys, or updates it if the keys if they already exist.  If your underlying cache can't do batch caching setting
+     * then do not implement this method, and it will delegate back to {@link #set(Object, Object)} for you
      *
      * @param keys   the keys to store
      * @param values the values to store

src/main/java/org/dataloader/ValueCacheOptions.java

@@ -22,7 +22,7 @@ public static ValueCacheOptions newOptions() {
 
     /**
      * This controls whether the {@link DataLoader} will wait for the {@link ValueCache#set(Object, Object)} call
-     * to complete before it completes the returned value.  By default this is false and hence
+     * to complete before it completes the returned value.  By default, this is false and hence
      * the {@link ValueCache#set(Object, Object)} call may complete some time AFTER the data loader
      * value has been returned.
      *

src/main/java/org/dataloader/annotations/ExperimentalApi.java

@@ -14,7 +14,7 @@
  * This represents code that the graphql-java project considers experimental API and while our intention is that it will
  * progress to be {@link PublicApi}, its existence, signature of behavior may change between releases.
  *
- * In general unnecessary changes will be avoided but you should not depend on experimental classes being stable
+ * In general unnecessary changes will be avoided, but you should not depend on experimental classes being stable
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = {CONSTRUCTOR, METHOD, TYPE, FIELD})

src/main/java/org/dataloader/annotations/Internal.java

@@ -13,7 +13,7 @@
  * This represents code that the java-dataloader project considers internal code that MAY not be stable within
  * major releases.
  *
- * In general unnecessary changes will be avoided but you should not depend on internal classes being stable
+ * In general unnecessary changes will be avoided, but you should not depend on internal classes being stable
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = {CONSTRUCTOR, METHOD, TYPE, FIELD})

src/main/java/org/dataloader/annotations/PublicSpi.java

@@ -15,7 +15,7 @@
  *
  * The guarantee  is for callers of code with this annotation as well as derivations that inherit / implement this code.
  *
- * New methods will not be added (without using default methods say) that would nominally breaks SPI implementations
+ * New methods will not be added (without using default methods say) that would nominally break SPI implementations
  * within a major release.
  */
 @Retention(RetentionPolicy.RUNTIME)

src/main/java/org/dataloader/annotations/VisibleForTesting.java

@@ -9,7 +9,7 @@
 import static java.lang.annotation.ElementType.METHOD;
 
 /**
- * Marks fields, methods etc as more visible than actually needed for testing purposes.
+ * Marks fields, methods etc. as more visible than actually needed for testing purposes.
  */
 @Retention(RetentionPolicy.RUNTIME)
 @Target(value = {CONSTRUCTOR, METHOD, FIELD})