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.

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));
     }
 
 }

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,

server/src/main/java/com/vaadin/data/provider/DataProvider.java

@@ -26,6 +26,7 @@
 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 @@
  * @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 default ConfigurableFilterDataProvider<T, Void, F> withConfigurableFilter
     }
 
     /**
-     * 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,30 +225,72 @@ public static <T> ListDataProvider<T> create(Collection<T> items) {
      * @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
      * @param items
      *            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);
+    }
 }

server/src/main/java/com/vaadin/ui/CheckBoxGroup.java

@@ -84,7 +84,7 @@ public CheckBoxGroup(String caption, DataProvider<T, ?> dataProvider) {
      * @see #setItems(Collection)
      */
     public CheckBoxGroup(String caption, Collection<T> items) {
-        this(caption, DataProvider.create(items));
+        this(caption, DataProvider.ofCollection(items));
     }
 
     /**

server/src/main/java/com/vaadin/ui/ComboBox.java

@@ -219,7 +219,7 @@ private void init() {
      */
     @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 void setDataProvider(ListDataProvider<T> listDataProvider) {
      *            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);
     }

server/src/main/java/com/vaadin/ui/ListSelect.java

@@ -77,7 +77,7 @@ public ListSelect(String caption, DataProvider<T, ?> dataProvider) {
      *            the options, cannot be {@code null}
      */
     public ListSelect(String caption, Collection<T> options) {
-        this(caption, DataProvider.create(options));
+        this(caption, DataProvider.ofCollection(options));
     }
 
     /**

server/src/main/java/com/vaadin/ui/RadioButtonGroup.java

@@ -93,7 +93,7 @@ public RadioButtonGroup(String caption, DataProvider<T, ?> dataProvider) {
      * @see #setItems(Collection)
      */
     public RadioButtonGroup(String caption, Collection<T> items) {
-        this(caption, DataProvider.create(items));
+        this(caption, DataProvider.ofCollection(items));
     }
 
     /**

server/src/main/java/com/vaadin/ui/TwinColSelect.java

@@ -74,7 +74,7 @@ public TwinColSelect(String caption, DataProvider<T, ?> dataProvider) {
      *            the options, cannot be {@code null}
      */
     public TwinColSelect(String caption, Collection<T> options) {
-        this(caption, DataProvider.create(options));
+        this(caption, DataProvider.ofCollection(options));
     }
 
     /**

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

server/src/test/java/com/vaadin/data/provider/bov/DataProviderBoVTest.java

@@ -25,7 +25,6 @@
 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 void testPersons() {
     }
 
     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 void testSortedPersons() {
     }
 
     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<>();

server/src/test/java/com/vaadin/tests/components/grid/GridMultiSelectionModelTest.java

@@ -24,7 +24,7 @@
 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 void selectAllCheckboxVisible__lazyDataProvider() {
                 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());

server/src/test/java/com/vaadin/tests/server/component/combobox/ComboBoxFilteringTest.java

@@ -123,7 +123,8 @@ public void setListDataProvider_defaultFiltering() {
 
         // 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 void setListDataProvider_customFiltering() {
         // 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 void customDataProvider_filterByLastName() {
         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 void customDataProvider_filterByLastNameWithAccessRestriction() {
         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

server/src/test/java/com/vaadin/ui/AbstractListingTest.java

@@ -12,7 +12,6 @@
 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 void testSetItemsWithVarargs() {
 
     @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());
     }

server/src/test/java/com/vaadin/ui/RadioButtonGroupTest.java

@@ -35,7 +35,7 @@ public void setUp() {
         radioButtonGroup = new RadioButtonGroup<>();
         // Intentional deviation from upcoming selection order
         radioButtonGroup.setDataProvider(
-                DataProvider.create("Third", "Second", "First"));
+                DataProvider.ofItems("Third", "Second", "First"));
     }
 
     @Test

uitest/src/main/java/com/vaadin/tests/components/grid/GridColumnWidthsWithoutData.java

@@ -79,7 +79,7 @@ private Grid<Person> createGrid(boolean withData) {
         grid.setSelectionMode(selectionMode);
 
         items = new ArrayList<>();
-        provider = DataProvider.create(items);
+        provider = DataProvider.ofCollection(items);
         grid.setDataProvider(provider);
 
         if (withData) {

uitest/src/main/java/com/vaadin/tests/components/grid/GridDataSourceReset.java

@@ -37,7 +37,7 @@ protected void setup(VaadinRequest request) {
         persons = createPersons(10, new Random(1));
 
         grid = new Grid<>();
-        ListDataProvider<ComplexPerson> provider = DataProvider.create(persons);
+        ListDataProvider<ComplexPerson> provider = DataProvider.ofCollection(persons);
         grid.setDataProvider(provider);
         grid.getSelectionModel().select(persons.get(0));
         addComponent(new Button("Remove first", event -> {

uitest/src/main/java/com/vaadin/tests/components/grid/basics/RefreshDataProvider.java

@@ -35,7 +35,7 @@ protected void setup(VaadinRequest request) {
         Grid<DataObject> grid = new Grid<>();
         List<DataObject> data = DataObject.generateObjects();
 
-        ListDataProvider<DataObject> dataProvider = DataProvider.create(data);
+        ListDataProvider<DataObject> dataProvider = DataProvider.ofCollection(data);
         grid.setDataProvider(dataProvider);
 
         grid.setDataProvider(dataProvider);

uitest/src/main/java/com/vaadin/tests/fieldgroup/ComplexPerson.java

@@ -107,7 +107,7 @@ public static ListDataProvider<ComplexPerson> createDataProvider(int size) {
             list.add(cp);
         }
 
-        return DataProvider.create(list);
+        return DataProvider.ofCollection(list);
     }
 
     public static ComplexPerson create(Random r) {