Skip to content

feat: Introduce flattened hierarchy format - #22040

Merged
vursen merged 3 commits into
mainfrom
flat-hierarchy-api
Aug 25, 2025
Merged

vursen merged 3 commits into
mainfrom
flat-hierarchy-api

Conversation

@vursen

@vursen vursen commented Aug 14, 2025 •

Copy link
Copy Markdown
Contributor

Description

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.

Image

Nested Hierarchy Format (default)

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 HierarchicalQuery#getParent(). 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 this lazy 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 HierarchicalDataProvider#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 Hierarchy Format (new)

The flattened hierarchy format refers to a data provider implementation that returns the entire subtree of the HierarchicalQuery#getParent() 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:

  • HierarchicalQuery#getOffset() points to the start of the requested range across all flattened descendants
  • HierarchicalQuery#getLimit() specifies the number of items to return
  • HierarchicalQuery#getExpandedItemIds() contains the set of expanded item IDs

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.
  • 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.

Depends on

Fixes #21880, #21878

Type of change

  • Feature

@vursen vursen changed the title feat: add support for flattened hierarchy in HierarchicalDataCommunicator feat: add support for flattened hierarchy in HierarchicalDataProvider Aug 14, 2025
@vursen vursen changed the title feat: add support for flattened hierarchy in HierarchicalDataProvider feat: add flattened hierarchy support to HierarchicalDataProvider Aug 14, 2025
@github-actions

github-actions Bot commented Aug 14, 2025 •

Copy link
Copy Markdown
Contributor

Test Results

1 246 files  + 1  1 246 suites  +1   1h 12m 22s ⏱️ -39s
8 629 tests + 7  8 562 ✅ + 7  67 💤 ±0  0 ❌ ±0 
8 894 runs   - 45  8 820 ✅  - 44  74 💤  - 1  0 ❌ ±0 

Results for commit 7b39cfb. ± Comparison against base commit 7a0e62f.

♻️ This comment has been updated with latest results.

@vursen
vursen force-pushed the flat-hierarchy-api branch 2 times, most recently from 179ed14 to 3ec2cd1 Compare August 18, 2025 07:07
@vursen
vursen changed the base branch from main to refactor/flattening-data-in-tree-grid August 18, 2025 07:07
@vaadin-bot vaadin-bot added +1.0.0 and removed +0.1.0 labels Aug 18, 2025
@vursen
vursen force-pushed the flat-hierarchy-api branch from 0fb19ba to 0b894ba Compare August 18, 2025 15:48
@vursen vursen changed the title feat: add flattened hierarchy support to HierarchicalDataProvider feat: introduce flattened hierarchy format Aug 19, 2025
@vursen vursen changed the title feat: introduce flattened hierarchy format feat: Introduce flattened hierarchy format Aug 19, 2025
@vursen
vursen requested review from mshabarov and tltv August 19, 2025 07:42
@vursen
vursen marked this pull request as ready for review August 19, 2025 09:32
* scrolling quickly.
* </ul>
*/
NESTED,

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The alternative could be RECURSIVE

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

RECURSIVE describes the hierarchy format a bit better since data providers are supposed to fetch tree branch recursively.
And just FLAT for the other one.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I changed my mind about this change after realizing it's too much focused on edge case of fetching the whole tree at once.

Base automatically changed from refactor/flattening-data-in-tree-grid to main August 22, 2025 10:58
tltv
tltv previously approved these changes Aug 22, 2025
@vursen vursen linked an issue Aug 22, 2025 that may be closed by this pull request
vursen added 3 commits August 22, 2025 17:03
wip

wip

wip

wip

wip

rename isFlatHierarchy to getHierarchyFormat

add missing details

wip

wip
@sonarqubecloud

Copy link
Copy Markdown

@vursen
vursen requested a review from tltv August 25, 2025 06:16
@vursen
vursen merged commit 1d12de6 into main Aug 25, 2025
@vursen
vursen deleted the flat-hierarchy-api branch August 25, 2025 07:02
@vaadin-bot

Copy link
Copy Markdown
Collaborator

This ticket/PR has been released with Vaadin 25.0.0-alpha8.

Copilot AI pushed a commit that referenced this pull request Oct 1, 2025
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Introduce getExpandedItemIds to HierarchicalQuery Introduce isFlatHierarchy and getDepth to HierarchicalDataProvider

3 participants