Add static helpers for creating callback data providers (#8314)

Cannot overload the same create method for this purpose since it
conflicts with T... overload. Each case is instead given its own
descriptive but still discoverable method name.

14 files changed, 104 insertions, 51 deletions

diff --git a/server/src/main/java/com/vaadin/data/HasDataProvider.java b/server/src/main/java/com/vaadin/data/HasDataProvider.java
index 142ef29336..0dc0fc1c2c 100644
--- a/server/src/main/java/com/vaadin/data/HasDataProvider.java
+++ b/server/src/main/java/com/vaadin/data/HasDataProvider.java
@@ -54,7 +54,7 @@ public interface HasDataProvider<T> extends HasItems<T> {
 
     @Override
     public default void setItems(Collection<T> items) {
-        setDataProvider(DataProvider.create(items));
+        setDataProvider(DataProvider.ofCollection(items));
     }
 
 }
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 dcb0340416..d83c1f1934 100644
--- a/server/src/main/java/com/vaadin/data/provider/CallbackDataProvider.java
+++ b/server/src/main/java/com/vaadin/data/provider/CallbackDataProvider.java
@@ -45,8 +45,8 @@ public class CallbackDataProvider<T, F>
      *            function that returns a stream of items from the back end for
      *            a query
      * @param sizeCallback
-     *            function that return the number of items in the back end for a
-     *            query
+     *            function that returns the number of items in the back end for
+     *            a query
      */
     public CallbackDataProvider(
             SerializableFunction<Query<T, F>, Stream<T>> fetchCallback,
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 69d4d8edbc..e641f0d057 100644
--- a/server/src/main/java/com/vaadin/data/provider/DataProvider.java
+++ b/server/src/main/java/com/vaadin/data/provider/DataProvider.java
@@ -26,6 +26,7 @@ import com.vaadin.data.HasDataProvider;
 import com.vaadin.data.HasFilterableDataProvider;
 import com.vaadin.server.SerializableBiFunction;
 import com.vaadin.server.SerializableFunction;
+import com.vaadin.server.SerializableToIntFunction;
 import com.vaadin.shared.Registration;
 
 /**
@@ -47,9 +48,11 @@ import com.vaadin.shared.Registration;
  * @param <F>
  *            filter type
  *
- * @see #create(Collection)
- * @see #create(Stream)
- * @see #create(Object...)
+ * @see #ofCollection(Collection)
+ * @see #ofItems(Object...)
+ * @see #fromStream(Stream)
+ * @see #fromCallbacks(SerializableFunction, SerializableToIntFunction)
+ * @see #fromFilteringCallbacks(SerializableFunction, SerializableToIntFunction)
  * @see ListDataProvider
  * @see BackEndDataProvider
  *
@@ -193,24 +196,27 @@ public interface DataProvider<T, F> extends Serializable {
     }
 
     /**
-     * This method creates a new {@link ListDataProvider} from a given
-     * Collection. The ListDataProvider creates a protective List copy of all
-     * the contents in the Collection.
+     * Creates a new data provider backed by a collection.
+     * <p>
+     * The collection is used as-is. Changes in the collection will be visible
+     * via the created data provider. The caller should copy the collection if
+     * necessary.
      *
      * @param <T>
      *            the data item type
      * @param items
-     *            the collection of data, not null
+     *            the collection of data, not <code>null</code>
      * @return a new list data provider
      */
-    public static <T> ListDataProvider<T> create(Collection<T> items) {
+    public static <T> ListDataProvider<T> ofCollection(Collection<T> items) {
         return new ListDataProvider<>(items);
     }
 
     /**
-     * This method creates a new {@link ListDataProvider} from given objects.The
-     * ListDataProvider creates a protective List copy of all the contents in
-     * the array.
+     * Creates a new data provider from the given items.
+     * <p>
+     * The items are copied into a new backing list, so structural changes to
+     * the provided array will not be visible via the created data provider.
      *
      * @param <T>
      *            the data item type
@@ -219,22 +225,22 @@ public interface DataProvider<T, F> extends Serializable {
      * @return a new list data provider
      */
     @SafeVarargs
-    public static <T> ListDataProvider<T> create(T... items) {
+    public static <T> ListDataProvider<T> ofItems(T... items) {
         return new ListDataProvider<>(Arrays.asList(items));
     }
 
     /**
-     * This method creates a new {@link ListDataProvider} from the given stream.
-     * The ListDataProvider <b>collects all the items in the stream to a
-     * list</b>.
+     * Creates a new data provider from the given stream. <b>All items in the
+     * stream are eagerly collected to a list.</b>
      * <p>
-     * This is just a shorthand for using {@link #create(Collection)} after
+     * This is a shorthand for using {@link #ofCollection(Collection)} after
      * collecting the items in the stream to a list with e.g.
      * {@code stream.collect(Collectors.toList));}.
      * <p>
      * <strong>Using big streams is not recommended, you should instead use a
-     * lazy data provider.</strong> See {@link BackEndDataProvider} for more
-     * info.
+     * lazy data provider.</strong> See
+     * {@link #fromCallbacks(SerializableFunction, SerializableToIntFunction)}
+     * or {@link BackEndDataProvider} for more info.
      *
      * @param <T>
      *            the data item type
@@ -242,7 +248,49 @@ public interface DataProvider<T, F> extends Serializable {
      *            a stream of data items, not {@code null}
      * @return a new list data provider
      */
-    public static <T> ListDataProvider<T> create(Stream<T> items) {
+    public static <T> ListDataProvider<T> fromStream(Stream<T> items) {
         return new ListDataProvider<>(items.collect(Collectors.toList()));
     }
+
+    /**
+     * Creates a new data provider that uses filtering callbacks for fetching
+     * and counting items from any backing store.
+     * <p>
+     * The query that is passed to each callback may contain a filter value that
+     * is provided by the component querying for data.
+     *
+     * @param fetchCallback
+     *            function that returns a stream of items from the back end for
+     *            a query
+     * @param sizeCallback
+     *            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);
+    }
+
+    /**
+     * Creates a new data provider that uses callbacks for fetching and counting
+     * items from any backing store.
+     * <p>
+     * The query that is passed to each callback will not contain any filter
+     * values.
+     *
+     * @param fetchCallback
+     *            function that returns a stream of items from the back end for
+     *            a query
+     * @param sizeCallback
+     *            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);
+    }
 }
diff --git a/server/src/main/java/com/vaadin/ui/CheckBoxGroup.java b/server/src/main/java/com/vaadin/ui/CheckBoxGroup.java
index 15d895142a..b6b6d69074 100644
--- a/server/src/main/java/com/vaadin/ui/CheckBoxGroup.java
+++ b/server/src/main/java/com/vaadin/ui/CheckBoxGroup.java
@@ -84,7 +84,7 @@ public class CheckBoxGroup<T> extends AbstractMultiSelect<T>
      * @see #setItems(Collection)
      */
     public CheckBoxGroup(String caption, Collection<T> items) {
-        this(caption, DataProvider.create(items));
+        this(caption, DataProvider.ofCollection(items));
     }
 
     /**
diff --git a/server/src/main/java/com/vaadin/ui/ComboBox.java b/server/src/main/java/com/vaadin/ui/ComboBox.java
index 4cfcca813d..d08f269fa3 100644
--- a/server/src/main/java/com/vaadin/ui/ComboBox.java
+++ b/server/src/main/java/com/vaadin/ui/ComboBox.java
@@ -219,7 +219,7 @@ public class ComboBox<T> extends AbstractSingleSelect<T>
      */
     @Override
     public void setItems(Collection<T> items) {
-        ListDataProvider<T> listDataProvider = DataProvider.create(items);
+        ListDataProvider<T> listDataProvider = DataProvider.ofCollection(items);
 
         setDataProvider(listDataProvider);
     }
@@ -285,7 +285,7 @@ public class ComboBox<T> extends AbstractSingleSelect<T>
      *            the data items to display
      */
     public void setItems(CaptionFilter captionFilter, Collection<T> items) {
-        ListDataProvider<T> listDataProvider = DataProvider.create(items);
+        ListDataProvider<T> listDataProvider = DataProvider.ofCollection(items);
 
         setDataProvider(captionFilter, listDataProvider);
     }
diff --git a/server/src/main/java/com/vaadin/ui/ListSelect.java b/server/src/main/java/com/vaadin/ui/ListSelect.java
index 1e7c92f14d..515570cc38 100644
--- a/server/src/main/java/com/vaadin/ui/ListSelect.java
+++ b/server/src/main/java/com/vaadin/ui/ListSelect.java
@@ -77,7 +77,7 @@ public class ListSelect<T> extends AbstractMultiSelect<T>
      *            the options, cannot be {@code null}
      */
     public ListSelect(String caption, Collection<T> options) {
-        this(caption, DataProvider.create(options));
+        this(caption, DataProvider.ofCollection(options));
     }
 
     /**
diff --git a/server/src/main/java/com/vaadin/ui/RadioButtonGroup.java b/server/src/main/java/com/vaadin/ui/RadioButtonGroup.java
index 7f2284b08e..35490c49d1 100644
--- a/server/src/main/java/com/vaadin/ui/RadioButtonGroup.java
+++ b/server/src/main/java/com/vaadin/ui/RadioButtonGroup.java
@@ -93,7 +93,7 @@ public class RadioButtonGroup<T> extends AbstractSingleSelect<T>
      * @see #setItems(Collection)
      */
     public RadioButtonGroup(String caption, Collection<T> items) {
-        this(caption, DataProvider.create(items));
+        this(caption, DataProvider.ofCollection(items));
     }
 
     /**
diff --git a/server/src/main/java/com/vaadin/ui/TwinColSelect.java b/server/src/main/java/com/vaadin/ui/TwinColSelect.java
index fb8a785076..2a8c91f9a7 100644
--- a/server/src/main/java/com/vaadin/ui/TwinColSelect.java
+++ b/server/src/main/java/com/vaadin/ui/TwinColSelect.java
@@ -74,7 +74,7 @@ public class TwinColSelect<T> extends AbstractMultiSelect<T>
      *            the options, cannot be {@code null}
      */
     public TwinColSelect(String caption, Collection<T> options) {
-        this(caption, DataProvider.create(options));
+        this(caption, DataProvider.ofCollection(options));
     }
 
     /**
diff --git a/server/src/test/java/com/vaadin/data/provider/ListDataProviderTest.java b/server/src/test/java/com/vaadin/data/provider/ListDataProviderTest.java
index d80ec546be..7e32449628 100644
--- a/server/src/test/java/com/vaadin/data/provider/ListDataProviderTest.java
+++ b/server/src/test/java/com/vaadin/data/provider/ListDataProviderTest.java
@@ -16,7 +16,7 @@ public class ListDataProviderTest
 
     @Override
     protected ListDataProvider<StrBean> createDataProvider() {
-        return DataProvider.create(data);
+        return DataProvider.ofCollection(data);
     }
 
     @Test
diff --git a/server/src/test/java/com/vaadin/data/provider/bov/DataProviderBoVTest.java b/server/src/test/java/com/vaadin/data/provider/bov/DataProviderBoVTest.java
index 45cfb82f69..cecb6bf511 100644
--- a/server/src/test/java/com/vaadin/data/provider/bov/DataProviderBoVTest.java
+++ b/server/src/test/java/com/vaadin/data/provider/bov/DataProviderBoVTest.java
@@ -25,7 +25,6 @@ import java.util.stream.Stream;
 import org.junit.Before;
 import org.junit.Test;
 
-import com.vaadin.data.provider.CallbackDataProvider;
 import com.vaadin.data.provider.DataProvider;
 import com.vaadin.data.provider.SortOrder;
 import com.vaadin.shared.data.sort.SortDirection;
@@ -102,7 +101,7 @@ public class DataProviderBoVTest {
     }
 
     private DataProvider<Person, ?> createUnsortedDataProvider() {
-        DataProvider<Person, ?> dataProvider = new CallbackDataProvider<>(
+        DataProvider<Person, ?> dataProvider = DataProvider.fromCallbacks(
                 // First callback fetches items based on a query
                 query -> {
                     // The index of the first item to load
@@ -130,7 +129,7 @@ public class DataProviderBoVTest {
     }
 
     private DataProvider<Person, ?> createSortedDataProvider() {
-        DataProvider<Person, ?> dataProvider = new CallbackDataProvider<>(
+        DataProvider<Person, ?> dataProvider = DataProvider.fromCallbacks(
                 // First callback fetches items based on a query
                 query -> {
                     List<PersonService.PersonSort> sortOrders = new ArrayList<>();
diff --git a/server/src/test/java/com/vaadin/tests/components/grid/GridMultiSelectionModelTest.java b/server/src/test/java/com/vaadin/tests/components/grid/GridMultiSelectionModelTest.java
index 2f8f5d9efa..c45bad66f0 100644
--- a/server/src/test/java/com/vaadin/tests/components/grid/GridMultiSelectionModelTest.java
+++ b/server/src/test/java/com/vaadin/tests/components/grid/GridMultiSelectionModelTest.java
@@ -24,7 +24,7 @@ import org.junit.Before;
 import org.junit.Test;
 import org.mockito.Mockito;
 
-import com.vaadin.data.provider.CallbackDataProvider;
+import com.vaadin.data.provider.DataProvider;
 import com.vaadin.data.provider.bov.Person;
 import com.vaadin.event.selection.MultiSelectionEvent;
 import com.vaadin.event.selection.MultiSelectionListener;
@@ -664,13 +664,15 @@ public class GridMultiSelectionModelTest {
                 model.getSelectAllCheckBoxVisibility());
 
         grid.setDataProvider(
-                new CallbackDataProvider<String, String>(
-                        q -> IntStream
-                                .range(q.getOffset(),
-                                        Math.max(q.getOffset() + q.getLimit()
-                                                + 1, 1000))
-                                .mapToObj(i -> "Item " + i),
-                        q -> 1000));
+                DataProvider
+                        .fromCallbacks(
+                                query -> IntStream
+                                        .range(query.getOffset(),
+                                                Math.max(query.getOffset()
+                                                        + query.getLimit() + 1,
+                                                        1000))
+                                        .mapToObj(i -> "Item " + i),
+                                query -> 1000));
 
         // not in-memory -> checkbox is hidden
         Assert.assertFalse(model.isSelectAllCheckBoxVisible());
diff --git a/server/src/test/java/com/vaadin/tests/server/component/combobox/ComboBoxFilteringTest.java b/server/src/test/java/com/vaadin/tests/server/component/combobox/ComboBoxFilteringTest.java
index f44c7924a0..e8c8d3dd6e 100644
--- a/server/src/test/java/com/vaadin/tests/server/component/combobox/ComboBoxFilteringTest.java
+++ b/server/src/test/java/com/vaadin/tests/server/component/combobox/ComboBoxFilteringTest.java
@@ -123,7 +123,8 @@ public class ComboBoxFilteringTest {
 
         // Result: typing "en" into the search field finds "Enrique Iglesias"
         // and "Henry Dunant", but not "Erwin Engelbrecht"
-        comboBox.setDataProvider(DataProvider.create(getPersonCollection()));
+        comboBox.setDataProvider(
+                DataProvider.ofCollection(getPersonCollection()));
 
         checkFiltering("en", "ennen", 3, 2);
     }
@@ -135,13 +136,14 @@ public class ComboBoxFilteringTest {
         // Result: typing "En" into the search field finds "Enrique Iglesias"
         // but not "Henry Dunant" or "Erwin Engelbrecht"
         comboBox.setDataProvider(String::startsWith,
-                DataProvider.create(getPersonCollection()));
+                DataProvider.ofCollection(getPersonCollection()));
 
         checkFiltering("En", "en", 3, 1);
     }
 
     public void invalid_dataProvider_compile_error() {
-        DataProvider<Person, Address> dp = DataProvider.create(getPersonArray())
+        DataProvider<Person, Address> dp = DataProvider
+                .ofItems(getPersonArray())
                 .filteringByEquals(Person::getAddress);
 
         // uncommenting this causes a compile time error because of invalid data
@@ -154,7 +156,7 @@ public class ComboBoxFilteringTest {
         comboBox.setItemCaptionGenerator(Person::getFirstName);
 
         // Filters by last name, regardless of the item caption generator
-        ListDataProvider<Person> ldp = DataProvider.create(getPersonArray());
+        ListDataProvider<Person> ldp = DataProvider.ofItems(getPersonArray());
         comboBox.setDataProvider(ldp.withConvertedFilter(
                 text -> person -> person.getLastName().contains(text)));
 
@@ -166,7 +168,7 @@ public class ComboBoxFilteringTest {
         comboBox.setItemCaptionGenerator(Person::getFirstName);
 
         // Filters by last name, regardless of the item caption generator
-        ListDataProvider<Person> ldp = DataProvider.create(getPersonArray());
+        ListDataProvider<Person> ldp = DataProvider.ofItems(getPersonArray());
         ldp.setFilter(person -> person.getFirstName().contains("nr"));
 
         // Same as above, but only showing a subset of the persons
diff --git a/server/src/test/java/com/vaadin/ui/AbstractListingTest.java b/server/src/test/java/com/vaadin/ui/AbstractListingTest.java
index 496d7e06bb..400105567d 100644
--- a/server/src/test/java/com/vaadin/ui/AbstractListingTest.java
+++ b/server/src/test/java/com/vaadin/ui/AbstractListingTest.java
@@ -12,7 +12,6 @@ import org.junit.Before;
 import org.junit.Test;
 
 import com.vaadin.data.HasDataProvider;
-import com.vaadin.data.provider.CallbackDataProvider;
 import com.vaadin.data.provider.DataProvider;
 import com.vaadin.data.provider.ListDataProvider;
 import com.vaadin.data.provider.Query;
@@ -109,13 +108,16 @@ public class AbstractListingTest {
 
     @Test
     public void testSetDataProvider() {
-        ListDataProvider<String> dataProvider = DataProvider.create(items);
+        ListDataProvider<String> dataProvider = DataProvider
+                .ofCollection(items);
         listing.setDataProvider(dataProvider);
         Assert.assertEquals("setDataProvider did not set data provider",
                 dataProvider, listing.getDataProvider());
-        listing.setDataProvider(new CallbackDataProvider<>(q -> Stream
-                .of(ITEM_ARRAY).skip(q.getOffset()).limit(q.getLimit()),
-                q -> ITEM_ARRAY.length));
+        listing.setDataProvider(
+                DataProvider.fromCallbacks(
+                        query -> Stream.of(ITEM_ARRAY).skip(query.getOffset())
+                                .limit(query.getLimit()),
+                        query -> ITEM_ARRAY.length));
         Assert.assertNotEquals("setDataProvider did not replace data provider",
                 dataProvider, listing.getDataProvider());
     }
diff --git a/server/src/test/java/com/vaadin/ui/RadioButtonGroupTest.java b/server/src/test/java/com/vaadin/ui/RadioButtonGroupTest.java
index 281690d7ee..136b23984a 100644
--- a/server/src/test/java/com/vaadin/ui/RadioButtonGroupTest.java
+++ b/server/src/test/java/com/vaadin/ui/RadioButtonGroupTest.java
@@ -35,7 +35,7 @@ public class RadioButtonGroupTest {
         radioButtonGroup = new RadioButtonGroup<>();
         // Intentional deviation from upcoming selection order
         radioButtonGroup.setDataProvider(
-                DataProvider.create("Third", "Second", "First"));
+                DataProvider.ofItems("Third", "Second", "First"));
     }
 
     @Test