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;