feat: Introduce flattened hierarchy format (#22040)

The PR introduces a new getHierarchyFormat() method to HierarchicalDataProvider. It can be configured to return either HierarchyFormat#NESTED (default) or HierarchyFormat#FLATTENED (new). The selected format defines in what way the data provider returns hierarchical data and how HierarchicalDataCommunicator should fetch and render it.

Author: vursen

flow-data/src/main/java/com/vaadin/flow/data/provider/DataProvider.java

@@ -27,6 +27,7 @@
 import com.vaadin.flow.data.binder.HasFilterableDataProvider;
 import com.vaadin.flow.data.provider.CallbackDataProvider.CountCallback;
 import com.vaadin.flow.data.provider.CallbackDataProvider.FetchCallback;
+import com.vaadin.flow.data.provider.hierarchy.HierarchicalDataProvider.HierarchyFormat;
 import com.vaadin.flow.function.SerializableBiFunction;
 import com.vaadin.flow.function.SerializableFunction;
 import com.vaadin.flow.shared.Registration;
@@ -109,14 +110,17 @@ public interface DataProvider<T, F> extends Serializable {
     void refreshItem(T item);
 
     /**
-     * Refreshes the given item and its children if refreshChildren is true and
-     * a hierarchical data provider is used. Otherwise, it behaves like regular
-     * {@link #refreshItem(Object)}.
+     * Refreshes the given item and its children when {@code refreshChildren} is
+     * true.
      * <p>
-     * It's important to note that this method resets the item's hierarchy which
-     * can cause a content shift if the item contains expanded children: their
-     * descendants aren't guaranteed to be re-fetched eagerly, which may affect
-     * the overall size of the rendered hierarchy, leading to content shifts.
+     * This method will reset the item's cached hierarchy which can cause a
+     * content shift if the item also contains <i>expanded</i> children: their
+     * descendants aren't guaranteed to be re-fetched eagerly if they aren't
+     * visible, which may affect the overall size of the rendered hierarchy,
+     * leading to content shifts.
+     * <p>
+     * This method is only supported for hierarchical data providers that use
+     * {@link HierarchyFormat#NESTED}.
      *
      * @param item
      *            the item to refresh

flow-data/src/main/java/com/vaadin/flow/data/provider/hierarchy/AbstractHierarchicalDataProvider.java

@@ -34,6 +34,23 @@
 public abstract class AbstractHierarchicalDataProvider<T, F> extends
         AbstractDataProvider<T, F> implements HierarchicalDataProvider<T, F> {
 
+    /**
+     * @throws UnsupportedOperationException
+     *             if the hierarchy format is not {@link HierarchyFormat#NESTED}
+     */
+    @Override
+    public void refreshItem(T item, boolean refreshChildren) {
+        if (!getHierarchyFormat().equals(HierarchyFormat.NESTED)) {
+            throw new UnsupportedOperationException(
+                    """
+                            Refreshing children of an item is only supported when the data provider \
+                            uses HierarchyFormat#NESTED. For other formats, use refreshAll() instead.
+                            """);
+        }
+
+        super.refreshItem(item, refreshChildren);
+    }
+
     @Override
     public <Q, C> HierarchicalConfigurableFilterDataProvider<T, Q, C> withConfigurableFilter(
             SerializableBiFunction<Q, C, F> filterCombiner) {

flow-data/src/main/java/com/vaadin/flow/data/provider/hierarchy/HierarchicalDataCommunicator.java

@@ -17,6 +17,7 @@
 
 import java.util.Arrays;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.HashSet;
 import java.util.LinkedList;
 import java.util.List;
@@ -32,6 +33,7 @@
 import com.vaadin.flow.data.provider.DataGenerator;
 import com.vaadin.flow.data.provider.DataProvider;
 import com.vaadin.flow.data.provider.KeyMapper;
+import com.vaadin.flow.data.provider.hierarchy.HierarchicalDataProvider.HierarchyFormat;
 import com.vaadin.flow.function.SerializableConsumer;
 import com.vaadin.flow.function.SerializableSupplier;
 import com.vaadin.flow.function.ValueProvider;
@@ -45,13 +47,25 @@
 import elemental.json.JsonValue;
 
 /**
+ * WARNING: Direct use of this class in application code is not recommended and
+ * may result in unexpected behavior. Use the API provided by the component
+ * instead.
+ * <p>
  * {@link HierarchicalDataCommunicator} is a middleware layer between
  * {@link HierarchicalDataProvider} and the client-side. It handles the loading
- * and caching of hierarchical data from the data provider, tracks expanded and
- * collapsed items, and delivers data to the client based on the
- * {@link #setViewportRange(int, int) requested viewport range}.
+ * and caching of hierarchical data from the data provider based on its
+ * hierarchy format, tracks expanded and collapsed items, and delivers data to
+ * the client based on the {@link #setViewportRange(int, int) requested viewport
+ * range}.
+ * <p>
+ * The communicator supports data providers that implement in one of the
+ * following formats: {@link HierarchyFormat#NESTED} or
+ * {@link HierarchyFormat#FLATTENED}.
  * <p>
- * Internally, it stores data in a hierarchical cache structure where each level
+ * <strong>Nested Hierarchy Format</strong>
+ * <p>
+ * When using data providers with {@link HierarchyFormat#NESTED}, the
+ * communicator stores data in a hierarchical cache structure where each level
  * is represented by a {@link Cache} object, and the root by {@link RootCache}.
  * <p>
  * Before sending data to the client, the visible range is flattened into a
@@ -60,14 +74,21 @@
  * method should be used by the component to get an item's depth and apply
  * indentation or other visual styling based on hierarchy level.
  * <p>
+ * <strong>Flattened Hierarchy Format</strong>
+ * <p>
+ * When using data providers whose format is {@link HierarchyFormat#FLATTENED},
+ * the communicator maintains all items in a single flat list, managed through
+ * {@link RootCache}, which is directly suitable for client-side rendering
+ * without any additional processing. The {@link #getDepth(Object)} method uses
+ * the data provider's implementation to determine the depth of an item in the
+ * hierarchy.
+ * <p>
+ * <strong>KeyMapper</strong>
+ * <p>
  * For each item in the visible range, the communicator generates a client-side
  * key using {@link KeyMapper}. This key is used to identify the item on the
  * server when the client sends updates or interaction events for that item such
  * as selection, expansion, etc.
- * <p>
- * WARNING: It's not recommended to rely on this class directly in application
- * code. Instead, the API provided by the component should be used. Direct use
- * may lead to unexpected behavior and isn't guaranteed to be stable.
  *
  * @param <T>
  *            the bean type
@@ -137,15 +158,15 @@ private void requestFlush() {
 
     /**
      * Clears all cached data and recursively re-fetches items from hierarchy
-     * levels that happen to be within the current viewport range, starting from
+     * levels that are still within the current viewport range, starting from
      * the root level.
      * <p>
-     * WARNING: This method performs a full hierarchy reset which discards
-     * information about previously visited expanded items and their positions
-     * in the hierarchy. As a result, the viewport's start index may become
-     * pointing to a different item if there were visited expanded items before
-     * the start index, which can cause a shift in the currently displayed
-     * items.
+     * WARNING: For data providers that use {@link HierarchyFormat#NESTED}, this
+     * method will clear all cached hierarchy state, discarding any potential
+     * information about the positions of expanded items in the hierarchy. As a
+     * result, the viewport's start index may become pointing to a different
+     * item if there were cached expanded items before the start index, causing
+     * a shift in the currently displayed items.
      */
     @Override
     public void reset() {
@@ -175,26 +196,38 @@ public void refresh(T item) {
 
     /**
      * Replaces the cached item with a new instance and schedules a client
-     * update to re-render this item. If {@code refreshChildren} is true, the
-     * item's children are cleared from the cache and forced to be re-fetched
-     * from the data provider when visible.
+     * update to re-render this item. When {@code refreshChildren} is true, the
+     * item's sub-hierarchy is cleared from the cache and scheduled to be
+     * re-fetched from the data provider once visible.
      * <p>
-     * WARNING: When {@code refreshChildren} is true, the method resets the
-     * item's hierarchy, which may in turn cause visible range shifts if the
-     * refreshed item contains expanded children. In such cases, their
-     * descendants might not be re-fetched immediately, which can affect the
-     * flattened hierarchy size and result in the viewport range pointing to a
-     * different set of items than before the refresh.
+     * WARNING: This method is only supported with data providers that use
+     * {@link HierarchyFormat#NESTED} and may cause visible range shift if the
+     * refreshed item contains <i>expanded</i> descendants. In such cases, they
+     * might not be re-fetched immediately if they are not visible. This can
+     * affect the flattened hierarchy size and result in the viewport range
+     * pointing to a different set of items than before the refresh.
      *
      * @since 25.0
      * @param item
      *            the item to refresh
      * @param refreshChildren
      *            whether or not to refresh child items
+     * @throws UnsupportedOperationException
+     *             if {@code refreshChildren} is true and the data provider's
+     *             hierarchy format is not {@link HierarchyFormat#NESTED}
      */
     public void refresh(T item, boolean refreshChildren) {
         Objects.requireNonNull(item, "Item cannot be null");
 
+        if (!getHierarchyFormat().equals(HierarchyFormat.NESTED)
+                && refreshChildren) {
+            throw new UnsupportedOperationException(
+                    """
+                            Refreshing children of an item is only supported when the data provider \
+                            uses HierarchyFormat#NESTED. For other formats, use reset() instead.
+                            """);
+        }
+
         getKeyMapper().refresh(item);
         dataGenerator.refreshData(item);
 
@@ -311,6 +344,11 @@ public Collection<T> collapse(Collection<T> items) {
         if (rootCache != null) {
             rootCache.removeDescendantCacheIf(
                     (cache) -> !isExpanded(cache.getParentItem()));
+        }
+
+        if (getHierarchyFormat().equals(HierarchyFormat.FLATTENED)) {
+            reset();
+        } else {
             requestFlush();
         }
 
@@ -345,7 +383,11 @@ public Collection<T> expand(Collection<T> items) {
             return expandedItemIds.add(getDataProvider().getId(item));
         }).toList();
 
-        requestFlush();
+        if (getHierarchyFormat().equals(HierarchyFormat.FLATTENED)) {
+            reset();
+        } else {
+            requestFlush();
+        }
 
         return expandedItems;
     }
@@ -384,6 +426,10 @@ public boolean isExpanded(T item) {
     public int getDepth(T item) {
         Objects.requireNonNull(item, "Item cannot be null");
 
+        if (getHierarchyFormat().equals(HierarchyFormat.FLATTENED)) {
+            return getDataProvider().getDepth(item);
+        }
+
         if (rootCache == null) {
             return -1;
         }
@@ -447,8 +493,14 @@ private void resolveIndexPath(Cache<T> cache, int... path) {
             preloadRange(cache, index, 1);
         }
 
+        if (restPath.length == 0) {
+            // If there is no rest path, we are at the target item
+            return;
+        }
+
         var item = cache.getItem(index);
-        if (restPath.length > 0 && isExpanded(item)) {
+        if (getHierarchyFormat().equals(HierarchyFormat.NESTED)
+                && isExpanded(item)) {
             var subCache = cache.ensureSubCache(index,
                     () -> getDataProviderChildCount(item));
             resolveIndexPath(subCache, restPath);
@@ -507,7 +559,8 @@ protected List<T> preloadFlatRangeBackward(int start, int length) {
             // Checking result.size() > 0 ensures that the start item
             // won't be expanded and its descendants won't be included
             // in the result.
-            if (isExpanded(item) && !cache.hasSubCache(index)
+            if (getHierarchyFormat().equals(HierarchyFormat.NESTED)
+                    && isExpanded(item) && !cache.hasSubCache(index)
                     && result.size() > 0) {
                 var subCache = cache.ensureSubCache(index,
                         () -> getDataProviderChildCount(item));
@@ -556,7 +609,8 @@ protected List<T> preloadFlatRangeForward(int start, int length) {
             }
 
             var item = cache.getItem(index);
-            if (isExpanded(item)) {
+            if (getHierarchyFormat().equals(HierarchyFormat.NESTED)
+                    && isExpanded(item)) {
                 cache.ensureSubCache(index,
                         () -> getDataProviderChildCount(item));
             }
@@ -604,10 +658,21 @@ private void flush(ExecutionContext context) {
         update.commit(nextUpdateId++);
     }
 
+    private HierarchyFormat getHierarchyFormat() {
+        return getDataProvider().getHierarchyFormat();
+    }
+
+    private Set<Object> getExpandedItemIds() {
+        return getHierarchyFormat().equals(HierarchyFormat.FLATTENED)
+                ? Collections.unmodifiableSet(this.expandedItemIds)
+                : Collections.emptySet();
+    }
+
     @SuppressWarnings("unchecked")
     private Stream<T> fetchDataProviderChildren(T parent, Range range) {
         var query = new HierarchicalQuery<>(range.getStart(), range.length(),
-                getBackEndSorting(), getInMemorySorting(), getFilter(), parent);
+                getBackEndSorting(), getInMemorySorting(), getFilter(),
+                getExpandedItemIds(), parent);
 
         return ((HierarchicalDataProvider<T, Object>) getDataProvider())
                 .fetchChildren(query).peek((item) -> {
@@ -620,7 +685,8 @@ private Stream<T> fetchDataProviderChildren(T parent, Range range) {
 
     @SuppressWarnings("unchecked")
     private int getDataProviderChildCount(T parent) {
-        var query = new HierarchicalQuery<>(getFilter(), parent);
+        var query = new HierarchicalQuery<>(getFilter(), getExpandedItemIds(),
+                parent);
 
         var count = ((HierarchicalDataProvider<T, Object>) getDataProvider())
                 .getChildCount(query);