Package com.vaadin.flow.data.provider.hierarchy

Enum Class HierarchicalDataProvider.HierarchyFormat

java.lang.Object
java.lang.Enum<HierarchicalDataProvider.HierarchyFormat>
com.vaadin.flow.data.provider.hierarchy.HierarchicalDataProvider.HierarchyFormat
All Implemented Interfaces:
Serializable, Comparable<HierarchicalDataProvider.HierarchyFormat>, Constable
Enclosing interface:
HierarchicalDataProvider<T,F>
public static enum HierarchicalDataProvider.HierarchyFormat extends Enum<HierarchicalDataProvider.HierarchyFormat>

  • Enum Constant Details

    • NESTED

      public static final HierarchicalDataProvider.HierarchyFormat NESTED
      The nested hierarchy format refers to a data provider implementation in which each expanded parent's children are fetched via a separate request, on demand: 
       └── Item 0               | Fetched in 1st request
     └── Item 0-0         | Fetched in 2nd request
         └── Item 0-0-0   | Fetched in 3rd request
 └── Item 1               | Fetched in 1st request
      Every request to the data provider returns a paginated list that contains only the direct children of the requested parent. The component decides when to request deeper levels and how much to load based on the current viewport and the expansion state of items, storing the loaded hierarchy state in memory.

      Example: 

       class MyDataProvider
         implements HierarchicalDataProvider<String, Void> {
     private HashMap<String, List<String>> data = new HashMap<>() {
         {
             put(null, List.of("Item 0", "Item 1"));
             put("Item 0", List.of("Item 0-0"));
             put("Item 0-0", List.of("Item 0-0-0"));
         }
     };

     @Override
     public HierarchyFormat getHierarchyFormat() {
         return HierarchyFormat.NESTED;
     }

     @Override
     public Stream<String> fetchChildren(
             HierarchicalQuery<String, Void> query) {
         return data.get(query.getParent()).stream()
                 .skip(query.getOffset()).limit(query.getLimit());
     }

     @Override
     public int getChildCount(HierarchicalQuery<String, Void> query) {
         return data.get(query.getParent()).size();
     }
 }
      Pros:
      • Simple and fast data queries by avoiding hierarchy construction – each request fetches only the direct children, which are then cached hierarchically.
      Cons:
      • The full size and structure of the tree remains unknown without recursively fetching the entire hierarchy, which is impractical due to potentially a lot of consecutive requests and heavy memory usage. As a result, the scroll position cannot be restored automatically after using DataProvider.refreshAll() which resets the cached hierarchy state.
      • The scroll container size updates dynamically while the user scrolls, which can cause them to jump over and miss some levels when scrolling quickly.

    • FLATTENED

      public static final HierarchicalDataProvider.HierarchyFormat FLATTENED
      The flattened hierarchy format refers to a data provider implementation that returns the entire subtree of the requested parent in a single, flattened, paginated list: 
       └── Item 0
 └── Item 0-0
 └── Item 0-0-0
 └── Item 1
      The list contains all expanded descendants, arranged in depth-first order: starting from the parent, then its children and their descendants, before the next sibling. The component delegates hierarchy construction entirely to the data provider by supplying a HierarchicalQuery where: The flattened format also requires the data provider to implement HierarchicalDataProvider.getDepth(T), which the component uses to make items appear as a hierarchy by applying visual indentation.

      Example: 

       class MyDataProvider
         implements HierarchicalDataProvider<String, Void> {
     private HashMap<String, List<String>> data = new HashMap<>() {
         {
             put(null, List.of("Item 0", "Item 1"));
             put("Item 0", List.of("Item 0-0"));
             put("Item 0-0", List.of("Item 0-0-0"));
         }
     };

     @Override
     public HierarchyFormat getHierarchyFormat() {
         return HierarchyFormat.FLATTENED;
     }

     @Override
     public Stream<String> fetchChildren(
             HierarchicalQuery<String, Void> query) {
         return flatten(query.getParent(), query.getExpandedItemIds())
                 .skip(query.getOffset()).limit(query.getLimit());
     }

     @Override
     public int getChildCount(HierarchicalQuery<String, Void> query) {
         return (int) flatten(query.getParent(),
                 query.getExpandedItemIds()).count();
     }

     @Override
     public int getDepth(String item) {
         return item.split("-").length - 1;
     }

     private Stream<String> flatten(String parent,
             Set<Object> expandedItemIds) {
         return data.getOrDefault(parent, List.of()).stream().flatMap(
                 child -> expandedItemIds.contains(getId(child))
                         ? Stream.concat(Stream.of(child),
                                 flatten(child, expandedItemIds))
                         : Stream.of(child));
     }
 }
      Pros:
      • The component can fetch the total size of the tree upfront and set a fixed scroll container size that does not change while scrolling, resulting in more predictable behavior.
      • DataProvider.refreshAll() avoids unexpected scroll jumps by refetching the total tree size and retaining the size of expanded items whose nested structure hasn't changed.
      • The developer has full control over how data is queried, making it possible to leverage more advanced optimizations and storage strategies at the database level.
      Cons:
      • Increased complexity and potentially heavier data queries due to the need for hierarchy reconstruction, which may require, for example, the use of recursive CTEs (Common Table Expressions) to retrieve all descendants of an item in a single SQL query.
      Since:
      25.0

  • Method Details

    • values

      public static HierarchicalDataProvider.HierarchyFormat[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static HierarchicalDataProvider.HierarchyFormat valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null