Extract data provider callbacks to named and documented interfaces (#8508)

Fixes #8488

2 files changed, 77 insertions, 27 deletions

diff --git a/server/src/main/java/com/vaadin/data/provider/CallbackDataProvider.java b/server/src/main/java/com/vaadin/data/provider/CallbackDataProvider.java
index 2f68e57e06..bd34cc939f 100644
--- a/server/src/main/java/com/vaadin/data/provider/CallbackDataProvider.java
+++ b/server/src/main/java/com/vaadin/data/provider/CallbackDataProvider.java
@@ -15,12 +15,11 @@
  */
 package com.vaadin.data.provider;
 
+import java.io.Serializable;
 import java.util.Objects;
 import java.util.stream.Stream;
 
 import com.vaadin.data.ValueProvider;
-import com.vaadin.server.SerializableFunction;
-import com.vaadin.server.SerializableToIntFunction;
 
 /**
  * Data provider that uses one callback for fetching items from a back end and
@@ -35,8 +34,60 @@ import com.vaadin.server.SerializableToIntFunction;
  */
 public class CallbackDataProvider<T, F>
         extends AbstractBackEndDataProvider<T, F> {
-    private final SerializableFunction<Query<T, F>, Stream<T>> fetchCallback;
-    private final SerializableToIntFunction<Query<T, F>> sizeCallback;
+    /**
+     * Callback interface for fetching a stream of items from a backend based on
+     * a query.
+     *
+     * @param <T>
+     *            the type of the items to fetch
+     * @param <F>
+     *            the type of the optional filter in the query,
+     *            <code>Void</code> if filtering is not supported
+     */
+    @FunctionalInterface
+    public interface FetchCallback<T, F> extends Serializable {
+        /**
+         * Fetches a stream of items based on a query. The query defines the
+         * paging of the items to fetch through {@link Query#getOffset()} and
+         * {@link Query#getLimit()}, the sorting through
+         * {@link Query#getSortOrders()} and optionally also any filtering to
+         * use through {@link Query#getFilter()}.
+         *
+         * @param query
+         *            the query that defines which items to fetch
+         * @return a stream of items
+         */
+        public Stream<T> fetch(Query<T, F> query);
+    }
+
+    /**
+     * Callback interface for counting the number of items in a backend based on
+     * a query.
+     *
+     * @param <T>
+     *            the type of the items to count
+     * @param <F>
+     *            the type of the optional filter in the query,
+     *            <code>Void</code> if filtering is not supported
+     */
+    @FunctionalInterface
+    public interface CountCallback<T, F> extends Serializable {
+        /**
+         * Counts the number of available items based on a query. The query
+         * optionally defines any filtering to use through
+         * {@link Query#getFilter()}. The query also contains information about
+         * paging and sorting although that information is generally not
+         * applicable for determining the number of items.
+         *
+         * @param query
+         *            the query that defines which items to count
+         * @return the number of available items
+         */
+        public int count(Query<T, F> query);
+    }
+
+    private final FetchCallback<T, F> fetchCallback;
+    private final CountCallback<T, F> countCallback;
     private final ValueProvider<T, Object> idGetter;
 
     /**
@@ -46,17 +97,15 @@ public class CallbackDataProvider<T, F>
      * @param fetchCallback
      *            function that returns a stream of items from the back end for
      *            a query
-     * @param sizeCallback
+     * @param countCallback
      *            function that return the number of items in the back end for a
      *            query
      *
-     * @see #CallbackDataProvider(SerializableFunction,
-     *      SerializableToIntFunction, ValueProvider)
+     * @see #CallbackDataProvider(FetchCallback, CountCallback, ValueProvider)
      */
-    public CallbackDataProvider(
-            SerializableFunction<Query<T, F>, Stream<T>> fetchCallback,
-            SerializableToIntFunction<Query<T, F>> sizeCallback) {
-        this(fetchCallback, sizeCallback, t -> t);
+    public CallbackDataProvider(FetchCallback<T, F> fetchCallback,
+            CountCallback<T, F> countCallback) {
+        this(fetchCallback, countCallback, t -> t);
     }
 
     /**
@@ -65,32 +114,31 @@ public class CallbackDataProvider<T, F>
      *
      * @param fetchCallBack
      *            function that requests data from back end based on query
-     * @param sizeCallback
+     * @param countCallback
      *            function that returns the amount of data in back end for query
      * @param identifierGetter
      *            function that returns the identifier for a given item
      */
-    public CallbackDataProvider(
-            SerializableFunction<Query<T, F>, Stream<T>> fetchCallBack,
-            SerializableToIntFunction<Query<T, F>> sizeCallback,
+    public CallbackDataProvider(FetchCallback<T, F> fetchCallBack,
+            CountCallback<T, F> countCallback,
             ValueProvider<T, Object> identifierGetter) {
         Objects.requireNonNull(fetchCallBack, "Request function can't be null");
-        Objects.requireNonNull(sizeCallback, "Size callback can't be null");
+        Objects.requireNonNull(countCallback, "Count callback can't be null");
         Objects.requireNonNull(identifierGetter,
                 "Identifier getter function can't be null");
         this.fetchCallback = fetchCallBack;
-        this.sizeCallback = sizeCallback;
+        this.countCallback = countCallback;
         this.idGetter = identifierGetter;
     }
 
     @Override
     public Stream<T> fetchFromBackEnd(Query<T, F> query) {
-        return fetchCallback.apply(query);
+        return fetchCallback.fetch(query);
     }
 
     @Override
     protected int sizeInBackEnd(Query<T, F> query) {
-        return sizeCallback.applyAsInt(query);
+        return countCallback.count(query);
     }
 
     @Override
diff --git a/server/src/main/java/com/vaadin/data/provider/DataProvider.java b/server/src/main/java/com/vaadin/data/provider/DataProvider.java
index f9c3c80146..6a5f9c0bb3 100644
--- a/server/src/main/java/com/vaadin/data/provider/DataProvider.java
+++ b/server/src/main/java/com/vaadin/data/provider/DataProvider.java
@@ -24,6 +24,8 @@ import java.util.stream.Stream;
 
 import com.vaadin.data.HasDataProvider;
 import com.vaadin.data.HasFilterableDataProvider;
+import com.vaadin.data.provider.CallbackDataProvider.CountCallback;
+import com.vaadin.data.provider.CallbackDataProvider.FetchCallback;
 import com.vaadin.server.SerializableBiFunction;
 import com.vaadin.server.SerializableFunction;
 import com.vaadin.server.SerializableToIntFunction;
@@ -290,15 +292,15 @@ public interface DataProvider<T, F> extends Serializable {
      * @param fetchCallback
      *            function that returns a stream of items from the back end for
      *            a query
-     * @param sizeCallback
+     * @param countCallback
      *            function that returns the number of items in the back end for
      *            a query
      * @return a new callback data provider
      */
     public static <T, F> CallbackDataProvider<T, F> fromFilteringCallbacks(
-            SerializableFunction<Query<T, F>, Stream<T>> fetchCallback,
-            SerializableToIntFunction<Query<T, F>> sizeCallback) {
-        return new CallbackDataProvider<>(fetchCallback, sizeCallback);
+            FetchCallback<T, F> fetchCallback,
+            CountCallback<T, F> countCallback) {
+        return new CallbackDataProvider<>(fetchCallback, countCallback);
     }
 
     /**
@@ -311,14 +313,14 @@ public interface DataProvider<T, F> extends Serializable {
      * @param fetchCallback
      *            function that returns a stream of items from the back end for
      *            a query
-     * @param sizeCallback
+     * @param countCallback
      *            function that returns the number of items in the back end for
      *            a query
      * @return a new callback data provider
      */
     public static <T> CallbackDataProvider<T, Void> fromCallbacks(
-            SerializableFunction<Query<T, Void>, Stream<T>> fetchCallback,
-            SerializableToIntFunction<Query<T, Void>> sizeCallback) {
-        return fromFilteringCallbacks(fetchCallback, sizeCallback);
+            FetchCallback<T, Void> fetchCallback,
+            CountCallback<T, Void> countCallback) {
+        return fromFilteringCallbacks(fetchCallback, countCallback);
     }
 }