More refactoring of code. Re-naming to more meaningful names

Author: bbakerman

README.md

@@ -1,4 +1,4 @@
-# Java `DataLoader`
+# `java-dataloader`
 
 [![Build Status](https://travis-ci.org/bbakerman/java-dataloader.svg?branch=master)](https://travis-ci.org/bbakerman/java-dataloader/)  
 [![Apache licensed](https://img.shields.io/hexpm/l/plug.svg?maxAge=2592000)](https://github.com/bbakerman/java-dataloader/blob/master/LICENSE)  
@@ -10,8 +10,11 @@ This small and simple utility library is a Pure Java 8 port of [Facebook DataLoa
 It can serve as integral part of your application's data layer to provide a
 consistent API over various back-ends and reduce message communication overhead through batching and caching.
 
-An important use case for `java-dataloader` is improving the efficiency of GraphQL query execution, but there are
-many other use cases where you can benefit from using this utility.
+An important use case for `java-dataloader` is improving the efficiency of GraphQL query execution.  Graphql fields
+are resolved in a independent manner and with a true graph of objects, you may be fetching the same object many times.  
+Also a naive implementation of graphql data fetchers can easily lead to the dreaded  "n+1" fetch problem. 
+
+There are many other use cases where you can also benefit from using this utility.
 
 Most of the code is ported directly from Facebook's reference implementation, with one IMPORTANT adaptation to make
 it work for Java 8. ([more on this below](manual-dispatching)).
@@ -67,16 +70,17 @@ The original data loader was written in Javascript for NodeJS. NodeJS is single-
 asynchronous logic by invoking functions on separate threads in an event loop, as explained
 [in this post](http://stackoverflow.com/a/19823583/3455094) on StackOverflow.
 
-Now in NodeJS generates so-call 'ticks' in which queued functions are dispatched for execution, and Facebook `DataLoader` uses
-the `nextTick()` function in NodeJS to _automatically_ dequeue load requests and send them to the batch execution function for processing.
+NodeJS generates so-call 'ticks' in which queued functions are dispatched for execution, and Facebook `DataLoader` uses
+the `nextTick()` function in NodeJS to _automatically_ dequeue load requests and send them to the batch execution function 
+for processing.
 
-And here there is an **IMPORTANT DIFFERENCE** compared to how _this_ data loader operates!!
+And here there is an **IMPORTANT DIFFERENCE** compared to how `java-dataloader` operates!!
 
 In NodeJS the batch preparation will not affect the asynchronous processing behaviour in any way. It will just prepare
 batches in 'spare time' as it were.
 
-This is different in Java as you will actually _delay_ the execution of your load requests, until the moment where you make a call
-to `dataLoader.dispatch()` in comparison to when you would just handle futures directly.
+This is different in Java as you will actually _delay_ the execution of your load requests, until the moment where you make a 
+call to `dataLoader.dispatch()`.
 
 Does this make Java `DataLoader` any less useful than the reference implementation? We would argue this is not the case,
 and there are also gains to this different mode of operation:

build.gradle

@@ -1,3 +1,5 @@
+import java.text.SimpleDateFormat
+
 buildscript {
     repositories {
         jcenter()
@@ -12,7 +14,7 @@ apply plugin: 'maven-publish'
 publishing {
     repositories {
         maven {
-            url 'https://dl.bintray.com/engagingspaces/maven'
+            url 'https://dl.bintray.com/bbakerman/maven'
         }
     }
 }
@@ -33,8 +35,9 @@ repositories {
     }
 }
 
+def releaseVersion = System.properties.RELEASE_VERSION
+version = releaseVersion ? releaseVersion : new SimpleDateFormat('yyyy-MM-dd\'T\'HH-mm-ss').format(new Date())
 group = 'org.dataloader'
-version = '1.0.0'
 
 compileJava {
     sourceCompatibility = 1.8

gradle/publishing.gradle

@@ -67,7 +67,7 @@ bintray {
     publish = true
     pkg {
         repo = 'maven'
-        name = "$project.name"
+        name = "java-dataloader"
         desc = projectDescription
         userOrg = 'bbakerman'
         websiteUrl = 'https://github.com/bbakerman/java-dataloader'

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

@@ -16,27 +16,56 @@
 
 package org.dataloader;
 
-import org.dataloader.impl.CombinedFuturesImpl;
-
-import java.util.Collection;
+import java.util.List;
 
 /**
- * Function that is invoked for batch loading the list of data values indicated by the provided list of keys. The
- * function returns a {@link CombinedFuturesImpl} to aggregate results of individual load requests.
+ * A function that is invoked for batch loading a list of data values indicated by the provided list of keys. The
+ * function returns a {@link PromisedValues} to aggregate results of individual load requests.
+ *
+ * There are a few constraints that must be upheld:
+ * <ul>
+ * <li>The list of values must be the same size as the list of keys.</li>
+ * <li>Each index in the list of values must correspond to the same index in the list of keys.</li>
+ * </ul>
+ *
+ * For example, if your batch function was provided the list of keys: [ 2, 9, 6, 1 ], and loading from a back-end service returned the values:
+ *
+ * <pre>
+ *  [
+ *      { id: 9, name: 'Chicago' },
+ *      { id: 1, name: 'New York' },
+ *      { id: 2, name: 'San Francisco' },
+ *  ]
+ * </pre>
+ *
+ * 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 can interpret as no value
+ * existing for that key.
+ *
+ * To uphold the constraints of the batch function, it must return an 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>
+ *  [
+ *      { id: 2, name: 'San Francisco' },
+ *      { id: 9, name: 'Chicago' },
+ *      null,
+ *      { id: 1, name: 'New York' }
+ * ]
+ * </pre>
  *
  * @param <K> type parameter indicating the type of keys to use for data load requests.
+ * @param <V> type parameter indicating the type of values returned
  *
  * @author <a href="https://github.com/aschrijver/">Arnold Schrijver</a>
  */
 @FunctionalInterface
-public interface BatchLoader<K> {
+public interface BatchLoader<K, V> {
 
     /**
-     * Batch load the provided keys and return a composite future of the result.
+     * Called to batch load the provided keys and return a {@link PromisedValues} which is a promise to a list of values
      *
-     * @param keys the list of keys to load
+     * @param keys the collection of keys to load
      *
-     * @return the composite future
+     * @return a promise of the values for those keys
      */
-    CombinedFutures load(Collection<K> keys);
+    PromisedValues<V> load(List<K> keys);
 }