feat: add convenient API to set items (#21979)

jcgueriaud1 · tltv · web-flow · commit 66cbdfdceae7 · 2025-08-04T13:41:38.000+03:00
Add convenient API to set items with ListDataView#setItems(Collection). Fixes: #15978 Co-authored-by: Tomi Virtanen <tltv@vaadin.com>
diff --git a/flow-data/src/main/java/com/vaadin/flow/data/provider/AbstractListDataView.java b/flow-data/src/main/java/com/vaadin/flow/data/provider/AbstractListDataView.java
@@ -286,6 +286,16 @@ public AbstractListDataView<T> removeItems(Collection<T> items) {
         return this;
     }
 
+    @Override
+    public AbstractListDataView<T> setItems(Collection<T> items) {
+        Objects.requireNonNull(items, NULL_COLLECTION_ERROR_MESSAGE);
+        final ListDataProvider<T> dataProvider = getDataProvider();
+        dataProvider.getItems().clear();
+        dataProvider.getItems().addAll(items);
+        dataProvider.refreshAll();
+        return this;
+    }
+
     /**
      * Validate that index is inside bounds of the data available.
      *
diff --git a/flow-data/src/main/java/com/vaadin/flow/data/provider/ListDataView.java b/flow-data/src/main/java/com/vaadin/flow/data/provider/ListDataView.java
@@ -282,6 +282,26 @@ public interface ListDataView<T, V extends ListDataView<T, ?>>
      */
     V removeItems(Collection<T> items);
 
+    /**
+     * Remove all the items in the list and adds given items to the data list.
+     * <p>
+     * The backing {@link List} must be mutable to use this method. Immutable
+     * data structure will throw an exception.
+     * <p>
+     * Refreshes all items of the component after adding the items, i.e. runs
+     * {@link DataView#refreshAll()}.
+     *
+     * @throws UnsupportedOperationException
+     *             if backing collection doesn't support modification
+     * @param items
+     *            collection of items to set
+     * @return this ListDataView instance
+     * @see #addItems(Collection)
+     * @see #addItemsBefore(Collection, Object)
+     * @see #addItemsAfter(Collection, Object)
+     */
+    V setItems(Collection<T> items);
+
     /**
      * Sets a filter to be applied to the data. The filter replaces any filter
      * that has been set or added previously. {@code null} will clear all
diff --git a/flow-data/src/test/java/com/vaadin/flow/data/provider/AbstractListDataViewTest.java b/flow-data/src/test/java/com/vaadin/flow/data/provider/AbstractListDataViewTest.java
@@ -21,6 +21,7 @@
 import java.util.Collections;
 import java.util.HashSet;
 import java.util.Iterator;
+import java.util.List;
 import java.util.Optional;
 import java.util.Set;
 import java.util.concurrent.atomic.AtomicInteger;
@@ -724,6 +725,27 @@ public void removeItems_emptyCollectionPassed_dataNotChanged() {
                 dataView.getItems().toArray(String[]::new));
     }
 
+    @Test
+    public void setItems_nullCollectionPassed_throwsException() {
+        exceptionRule.expect(NullPointerException.class);
+        exceptionRule.expectMessage("Items collection cannot be null");
+
+        dataView.setItems(null);
+    }
+
+    @Test
+    public void setItems_emptyCollectionPassed_dataEmpty() {
+        dataView.setItems(Collections.emptyList());
+        Assert.assertTrue(dataView.getItems().toList().isEmpty());
+    }
+
+    @Test
+    public void setItems_collectionPassed_dataFilled() {
+        dataView.setItems(List.of("first", "middle", "last"));
+        Assert.assertArrayEquals(new String[] { "first", "middle", "last" },
+                dataView.getItems().toArray(String[]::new));
+    }
+
     @Test
     public void addItemsAndRemoveItems_noConcurrencyIssues() {
         dataView.addItemsBefore(Arrays.asList("newOne", "newTwo", "newThree"),
diff --git a/flow-data/src/test/java/com/vaadin/flow/data/provider/hierarchy/HasHierarchicalDataProviderTest.java b/flow-data/src/test/java/com/vaadin/flow/data/provider/hierarchy/HasHierarchicalDataProviderTest.java
@@ -159,6 +159,11 @@ public TestListDataView removeItems(Collection<String> items) {
             return null;
         }
 
+        @Override
+        public TestListDataView setItems(Collection<String> items) {
+            return null;
+        }
+
         @Override
         public TestListDataView setFilter(
                 SerializablePredicate<String> filter) {
