The PR 56 followup work

build.gradle

@@ -61,5 +61,5 @@ dependencies {
 
 task wrapper(type: Wrapper) {
     gradleVersion = '4.0'
-    distributionUrl = "http://services.gradle.org/distributions/gradle-4.0-all.zip"
+    distributionUrl = "https://services.gradle.org/distributions/gradle-4.0-all.zip"
 }

gradle/publishing.gradle

@@ -4,7 +4,7 @@ apply plugin: 'com.jfrog.bintray'
 publishing {
     repositories {
         maven {
-            url 'http://dl.bintray.com/bbakerman/java-dataloader'
+            url 'https://dl.bintray.com/bbakerman/java-dataloader'
         }
     }
 }
@@ -52,7 +52,7 @@ publishing {
                     licenses {
                         license {
                             name 'The Apache Software License, Version 2.0'
-                            url 'http://www.apache.org/licenses/LICENSE-2.0.txt'
+                            url 'https://www.apache.org/licenses/LICENSE-2.0.txt'
                             distribution 'repo'
                         }
                     }

gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=http\://services.gradle.org/distributions/gradle-4.0-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-4.0-all.zip

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

@@ -71,6 +71,7 @@
  * @author <a href="https://github.com/bbakerman/">Brad Baker</a>
  */
 @FunctionalInterface
+@PublicSpi
 public interface BatchLoader<K, V> {
 
     /**

src/main/java/org/dataloader/BatchLoaderContextProvider.java

@@ -5,6 +5,7 @@
  * provide overall calling context to the {@link org.dataloader.BatchLoader} call.  A common use
  * case is for propagating user security credentials or database connection parameters for example.
  */
+@PublicSpi
 public interface BatchLoaderContextProvider {
     /**
      * @return a context object that may be needed in batch load calls

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

@@ -12,6 +12,7 @@
  * This object is passed to a batch loader as calling context.  It could contain security credentials
  * of the calling users for example or database parameters that allow the data layer call to succeed.
  */
+@PublicApi
 public class BatchLoaderEnvironment {
 
     private final Object context;

src/main/java/org/dataloader/BatchLoaderEnvironmentProvider.java

@@ -6,6 +6,7 @@
  * the {@link org.dataloader.BatchLoader} call.  A common use
  * case is for propagating user security credentials or database connection parameters.
  */
+@PublicSpi
 public interface BatchLoaderEnvironmentProvider {
     /**
      * @return a {@link org.dataloader.BatchLoaderEnvironment} that may be needed in batch calls

src/main/java/org/dataloader/BatchLoaderWithContext.java

@@ -11,6 +11,7 @@
  * See {@link org.dataloader.BatchLoader} for more details on the design invariants that you must implement in order to
  * use this interface.
  */
+@PublicSpi
 public interface BatchLoaderWithContext<K, V> {
     /**
      * Called to batch load the provided keys and return a promise to a list of values.  This default

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

@@ -35,6 +35,7 @@
  * @author <a href="https://github.com/aschrijver/">Arnold Schrijver</a>
  * @author <a href="https://github.com/bbakerman/">Brad Baker</a>
  */
+@PublicSpi
 public interface CacheMap<U, V> {
 
     /**

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

@@ -54,6 +54,7 @@
  * @author <a href="https://github.com/aschrijver/">Arnold Schrijver</a>
  * @author <a href="https://github.com/bbakerman/">Brad Baker</a>
  */
+@PublicApi
 public class DataLoader<K, V> {
 
     private final DataLoaderHelper<K, V> helper;
@@ -470,7 +471,7 @@ public CompletableFuture<List<V>> loadMany(List<K> keys, List<Object> keyContext
      * @return the promise of the queued load requests
      */
     public CompletableFuture<List<V>> dispatch() {
-        return helper.dispatch().futureList;
+        return helper.dispatch().getPromisedResults();
     }
 
     /**
@@ -480,9 +481,9 @@ public CompletableFuture<List<V>> dispatch() {
      * If batching is disabled, or there are no queued requests, then a succeeded promise with no entries dispatched is
      * returned.
      *
-     * @return the promise of the queued load requests and the number of entries dispatched.
+     * @return the promise of the queued load requests and the number of keys dispatched.
      */
-    public DataLoaderHelper.DispatchResult<V> dispatchWithCounts() {
+    public DispatchResult<V> dispatchWithCounts() {
         return helper.dispatch();
     }
 

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

@@ -26,6 +26,7 @@
  * @param <K> the type of keys
  * @param <V> the type of values
  */
+@Internal
 class DataLoaderHelper<K, V> {
 
 
@@ -134,15 +135,6 @@ Object getCacheKey(K key) {
                 loaderOptions.cacheKeyFunction().get().getKey(key) : key;
     }
 
-    public static class DispatchResult<X> {
-        public final CompletableFuture<List<X>> futureList;
-        public final int totalEntriesHandled;
-        public DispatchResult(CompletableFuture<List<X>> futureList, int totalEntriesHandled) {
-            this.futureList = futureList;
-            this.totalEntriesHandled = totalEntriesHandled;
-        }
-    }
-
     DispatchResult<V> dispatch() {
         boolean batchingEnabled = loaderOptions.batchingEnabled();
         //

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

@@ -29,6 +29,7 @@
  *
  * @author <a href="https://github.com/aschrijver/">Arnold Schrijver</a>
  */
+@PublicApi
 public class DataLoaderOptions {
 
     private static final BatchLoaderContextProvider NULL_PROVIDER = () -> null;

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

@@ -15,6 +15,7 @@
  * they can be dispatched as one.  It also allows you to retrieve data loaders by
  * name from a central place
  */
+@PublicApi
 public class DataLoaderRegistry {
     private final Map<String, DataLoader<?, ?>> dataLoaders = new ConcurrentHashMap<>();
 
@@ -118,8 +119,8 @@ public void dispatchAll() {
      */
     public int dispatchAllWithCount() {
         int sum = 0;
-        for (DataLoader dataLoader : getDataLoaders()) {
-            sum += dataLoader.dispatchWithCounts().totalEntriesHandled;
+        for (DataLoader<?,?> dataLoader : getDataLoaders()) {
+            sum += dataLoader.dispatchWithCounts().getKeysCount();
         }
         return sum;
     }

src/main/java/org/dataloader/DispatchResult.java

@@ -0,0 +1,29 @@
+package org.dataloader;
+
+import java.util.List;
+import java.util.concurrent.CompletableFuture;
+
+/**
+ * When a DataLoader is dispatched this object holds the promised results and also the count of key asked for
+ * via methods like {@link org.dataloader.DataLoader#load(Object)} or {@link org.dataloader.DataLoader#loadMany(java.util.List)}
+ *
+ * @param <T> for two
+ */
+@PublicApi
+public class DispatchResult<T> {
+    private final CompletableFuture<List<T>> futureList;
+    private final int keysCount;
+
+    public DispatchResult(CompletableFuture<List<T>> futureList, int keysCount) {
+        this.futureList = futureList;
+        this.keysCount = keysCount;
+    }
+
+    public CompletableFuture<List<T>> getPromisedResults() {
+        return futureList;
+    }
+
+    public int getKeysCount() {
+        return keysCount;
+    }
+}

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

@@ -0,0 +1,21 @@
+package org.dataloader;
+
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.CONSTRUCTOR;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+
+/**
+ * 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
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value = {CONSTRUCTOR, METHOD, TYPE, FIELD})
+public @interface Internal {
+}

src/main/java/org/dataloader/PublicApi.java

@@ -0,0 +1,24 @@
+package org.dataloader;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.CONSTRUCTOR;
+import static java.lang.annotation.ElementType.FIELD;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+
+/**
+ * This represents code that the java-dataloader project considers public API and has an imperative to be stable within
+ * major releases.
+ *
+ * The guarantee  is for code calling classes and interfaces with this annotation, not derived from them.  New methods
+ * maybe be added which would break derivations but not callers.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value = {CONSTRUCTOR, METHOD, TYPE, FIELD})
+@Documented
+public @interface PublicApi {
+}

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

@@ -0,0 +1,25 @@
+package org.dataloader;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import static java.lang.annotation.ElementType.CONSTRUCTOR;
+import static java.lang.annotation.ElementType.METHOD;
+import static java.lang.annotation.ElementType.TYPE;
+
+/**
+ * This represents code that the java-dataloader project considers public SPI and has an imperative to be stable within
+ * major releases.
+ *
+ * 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
+ * within a major release.
+ */
+@Retention(RetentionPolicy.RUNTIME)
+@Target(value = {CONSTRUCTOR, METHOD, TYPE})
+@Documented
+public @interface PublicSpi {
+}

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

@@ -22,6 +22,7 @@
  * {@link org.dataloader.DataLoader} understands the use of Try and will take the exceptional path and complete
  * the value promise with that exception value.
  */
+@PublicApi
 public class Try<V> {
     private static Throwable NIL = new Throwable() {
         @Override

src/main/java/org/dataloader/impl/Assertions.java

@@ -1,7 +1,10 @@
 package org.dataloader.impl;
 
+import org.dataloader.Internal;
+
 import java.util.Objects;
 
+@Internal
 public class Assertions {
 
     public static void assertState(boolean state, String message) {

src/main/java/org/dataloader/impl/CompletableFutureKit.java

@@ -1,5 +1,7 @@
 package org.dataloader.impl;
 
+import org.dataloader.Internal;
+
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.ExecutionException;
@@ -9,6 +11,7 @@
 /**
  * Some really basic helpers when working with CompletableFutures
  */
+@Internal
 public class CompletableFutureKit {
 
     public static <V> CompletableFuture<V> failedFuture(Exception e) {

src/main/java/org/dataloader/impl/DefaultCacheMap.java

@@ -17,6 +17,7 @@
 package org.dataloader.impl;
 
 import org.dataloader.CacheMap;
+import org.dataloader.Internal;
 
 import java.util.HashMap;
 import java.util.Map;
@@ -29,6 +30,7 @@
  *
  * @author <a href="https://github.com/aschrijver/">Arnold Schrijver</a>
  */
+@Internal
 public class DefaultCacheMap<U, V> implements CacheMap<U, V> {
 
     private Map<U, V> cache;

src/main/java/org/dataloader/impl/PromisedValues.java

@@ -1,5 +1,7 @@
 package org.dataloader.impl;
 
+import org.dataloader.Internal;
+
 import java.util.List;
 import java.util.concurrent.CancellationException;
 import java.util.concurrent.CompletableFuture;
@@ -22,6 +24,7 @@
  *
  * @author <a href="https://github.com/bbakerman/">Brad Baker</a>
  */
+@Internal
 public interface PromisedValues<T> {
 
     /**

src/main/java/org/dataloader/impl/PromisedValuesImpl.java

@@ -1,5 +1,7 @@
 package org.dataloader.impl;
 
+import org.dataloader.Internal;
+
 import java.util.ArrayList;
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
@@ -13,6 +15,7 @@
 import static org.dataloader.impl.Assertions.assertState;
 import static org.dataloader.impl.Assertions.nonNull;
 
+@Internal
 public class PromisedValuesImpl<T> implements PromisedValues<T> {
 
     private final List<? extends CompletionStage<T>> futures;

src/main/java/org/dataloader/stats/Statistics.java

@@ -1,11 +1,14 @@
 package org.dataloader.stats;
 
+import org.dataloader.PublicApi;
+
 import java.util.LinkedHashMap;
 import java.util.Map;
 
 /**
  * This holds statistics on how a {@link org.dataloader.DataLoader} has performed
  */
+@PublicApi
 public class Statistics {
 
     private final long loadCount;

src/main/java/org/dataloader/stats/StatisticsCollector.java

@@ -1,8 +1,11 @@
 package org.dataloader.stats;
 
+import org.dataloader.PublicSpi;
+
 /**
  * This allows statistics to be collected for {@link org.dataloader.DataLoader} operations
  */
+@PublicSpi
 public interface StatisticsCollector {
 
     /**