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

Class HierarchicalDataCommunicator<T>

java.lang.Object
com.vaadin.flow.data.provider.DataCommunicator<T>
com.vaadin.flow.data.provider.hierarchy.HierarchicalDataCommunicator<T>
Type Parameters:
T - the bean type
All Implemented Interfaces:
Serializable
public class HierarchicalDataCommunicator<T> extends DataCommunicator<T>
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.

HierarchicalDataCommunicator is a middleware layer between HierarchicalDataProvider and the client-side. It handles the loading 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 requested viewport range.

The communicator supports data providers that implement in one of the following formats: HierarchicalDataProvider.HierarchyFormat.NESTED or HierarchicalDataProvider.HierarchyFormat.FLATTENED.

Nested Hierarchy Format

When using data providers with HierarchicalDataProvider.HierarchyFormat.NESTED, the communicator stores data in a hierarchical cache structure where each level is represented by a Cache object, and the root by RootCache.

Before sending data to the client, the visible range is flattened into a linear list. This allows the client to work with a simplified view, without handling hierarchical structure directly. The getDepth(Object) method should be used by the component to get an item's depth and apply indentation or other visual styling based on hierarchy level.

Flattened Hierarchy Format

When using data providers whose format is HierarchicalDataProvider.HierarchyFormat.FLATTENED, the communicator maintains all items in a single flat list, managed through RootCache, which is directly suitable for client-side rendering without any additional processing. The getDepth(Object) method uses the data provider's implementation to determine the depth of an item in the hierarchy.

KeyMapper

For each item in the visible range, the communicator generates a client-side key using 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.

Since:
1.2
Author:
Vaadin Ltd
See Also:

  • Constructor Details

    • HierarchicalDataCommunicator

      public HierarchicalDataCommunicator(CompositeDataGenerator<T> dataGenerator, ArrayUpdater arrayUpdater, StateNode stateNode, SerializableSupplier<ValueProvider<T,String>> uniqueKeyProviderSupplier)
      Construct a new hierarchical data communicator backed by a TreeDataProvider.
      Parameters:
      dataGenerator - the data generator function
      arrayUpdater - array updater strategy
      stateNode - the state node used to communicate for
      uniqueKeyProviderSupplier - Unique key provider for a row. If null, then using Grid's default key generator.

  • Method Details

    • reset

      public void reset()
      Clears all cached data and recursively re-fetches items from hierarchy levels that are still within the current viewport range, starting from the root level.

      WARNING: For data providers that use HierarchicalDataProvider.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.

      Overrides:
      reset in class DataCommunicator<T>

    • handleDataRefreshEvent

      protected void handleDataRefreshEvent(DataChangeEvent.DataRefreshEvent<T> event)
      Overrides:
      handleDataRefreshEvent in class DataCommunicator<T>

    • refresh

      public void refresh(T item)
      Replaces the cached item with a new instance and schedules a client update to re-render this item.
      Overrides:
      refresh in class DataCommunicator<T>
      Parameters:
      item - updated data object; not null

    • refresh

      public void refresh(T item, boolean refreshChildren)
      Replaces the cached item with a new instance and schedules a client update to re-render this item. When 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.

      WARNING: This method is only supported with data providers that use HierarchicalDataProvider.HierarchyFormat.NESTED and may cause visible range shift if the refreshed item contains expanded 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.

      Parameters:
      item - the item to refresh
      refreshChildren - whether or not to refresh child items
      Throws:
      UnsupportedOperationException - if refreshChildren is true and the data provider's hierarchy format is not HierarchicalDataProvider.HierarchyFormat.NESTED
      Since:
      25.0

    • fetchFromProvider

      public Stream<T> fetchFromProvider(int offset, int limit)
      Description copied from class: DataCommunicator
      Fetches a list of items from the DataProvider.

      NOTE: the limit parameter shows how many items the client wants to fetch, but the actual number of results may be greater, and vary from 0 to pages * pageSize.

      Overrides:
      fetchFromProvider in class DataCommunicator<T>
      Parameters:
      offset - the starting index of the range
      limit - the desired number of results
      Returns:
      the list of items in given range

    • getDataProvider

      public HierarchicalDataProvider<T,?> getDataProvider()
      Description copied from class: DataCommunicator
      Gets the current data provider from this DataCommunicator.
      Overrides:
      getDataProvider in class DataCommunicator<T>
      Returns:
      the data provider

    • setDataProvider

      public <F> SerializableConsumer<F> setDataProvider(HierarchicalDataProvider<T,F> dataProvider, F initialFilter)
      Sets the hierarchical data provider for this communicator.

      The returned consumer allows updating the filter value used in subsequent queries to the data provider. The consumer is only valid until another data provider is set.

      Type Parameters:
      F - the filter type
      Parameters:
      dataProvider - the hierarchical data provider to use, not null
      initialFilter - the initial filter value, or null if no filtering is needed
      Returns:
      a SerializableConsumer for updating the filter value

    • setDataProvider

      public <F> SerializableConsumer<F> setDataProvider(DataProvider<T,F> dataProvider, F initialFilter)
      Alias for setDataProvider(HierarchicalDataProvider, Object). Only hierarchical data providers are supported.
      Overrides:
      setDataProvider in class DataCommunicator<T>
      Type Parameters:
      F - the filter type
      Parameters:
      dataProvider - the hierarchical data provider to use, not null
      initialFilter - the initial filter value, or null if no filtering is needed
      Returns:
      a SerializableConsumer for updating the filter value
      Throws:
      IllegalArgumentException - if the provided data provider is not a hierarchical data provider

    • confirmUpdate

      public void confirmUpdate(int updateId)
      Description copied from class: DataCommunicator
      Confirm update with the given updateId.
      Overrides:
      confirmUpdate in class DataCommunicator<T>
      Parameters:
      updateId - the update identifier

    • collapse

      public void collapse(T item)
      Collapses the given item and removes its sub-hierarchy. Calling this method will have no effect if the row is already collapsed.
      Parameters:
      item - the item to collapse

    • collapse

      public Collection<T> collapse(Collection<T> items)
      Collapses the given items and removes its sub-hierarchy. Calling this method will have no effect if the row is already collapsed.
      Parameters:
      items - the items to collapse
      Returns:
      the collapsed items

    • expand

      public void expand(T item)
      Expands the given item and schedules a client update to render children (if visible). Calling this method will have no effect if the item is already expanded or if it has no children.
      Parameters:
      item - the item to expand

    • expand

      public Collection<T> expand(Collection<T> items)
      Expands the given items and schedules a client update to render children (if visible). Calling this method will have no effect if the item is already expanded or if it has no children.
      Parameters:
      items - the items to expand
      Returns:
      the expanded items

    • hasChildren

      public boolean hasChildren(T item)
      Returns whether given item has children.
      Parameters:
      item - the item to test
      Returns:
      true if item has children; false if not

    • isExpanded

      public boolean isExpanded(T item)
      Returns whether given item is expanded.
      Parameters:
      item - the item to test
      Returns:
      true if item is expanded; false if not

    • getDepth

      public int getDepth(T item)
      Returns depth of item in the tree starting from zero representing a root.
      Parameters:
      item - Target item
      Returns:
      depth of item in the tree or -1 if item is null or not found in the cache

    • getDataProviderSize

      public int getDataProviderSize()
      Description copied from class: DataCommunicator
      Getter method for determining the item count of the data.

      This method should be used only with defined size, i.e. when DataCommunicator.isDefinedSize() returns true.

      Can be overridden by a subclass that uses a specific type of DataProvider and/or query.

      Overrides:
      getDataProviderSize in class DataCommunicator<T>
      Returns:
      the size of data provider with current filter

    • hasExpandedItems

      public boolean hasExpandedItems()
      Returns true if there is any expanded items.
      Returns:
      true if there is any expanded items.

    • resolveIndexPath

      protected int resolveIndexPath(int... path)
      Ensures that all items along the specified path are preloaded into the cache, starting from the root level, and returns the flat index of the target item.
      Parameters:
      path - the hierarchical path to the item, where each element represents the index within its respective level
      Returns:
      the flat index of the target item after resolving all ancestors
      Since:
      25.0

    • preloadFlatRangeBackward

      protected List<T> preloadFlatRangeBackward(int start, int length)
      Preloads and returns a range of items from the flattened hierarchy, starting at the specified flat index and spanning the given length. Items are preloaded in the backward direction, beginning from the given start index and continuing toward lower indexes until the specified length is reached.

      NOTE: Backward preloading can affect the position of the start index in the flat list, so it may need to be recalculated if it's used after this method call.

      Parameters:
      start - the start index of the range to preload
      length - the length of the range to preload
      Returns:
      a list of items preloaded in the specified range
      Since:
      25.0

    • preloadFlatRangeForward

      protected List<T> preloadFlatRangeForward(int start, int length)
      Preloads and returns a range of items from the flattened hierarchy, starting at the specified flat index and spanning the given length. Items are preloaded in the forward direction, beginning from the given start index and continuing toward higher indexes until the specified length is reached.
      Parameters:
      start - the start index of the range to preload
      length - the length of the range to preload
      Returns:
      a list of items preloaded in the specified range
      Since:
      25.0

    • setViewportRange

      public void setViewportRange(int start, int length)
      Description copied from class: DataCommunicator
      Sets the range of data to be sent to the client.
      Overrides:
      setViewportRange in class DataCommunicator<T>
      Parameters:
      start - the start of the viewport range
      length - the end of the viewport range

    • setItemCountEstimate

      public void setItemCountEstimate(int itemCountEstimate)
      Estimates are not supported in HierarchicalDataCommunicator
      Overrides:
      setItemCountEstimate in class DataCommunicator<T>
      Parameters:
      itemCountEstimate - the item count estimate to be used

    • getItemCountEstimate

      public int getItemCountEstimate()
      Estimates are not supported in HierarchicalDataCommunicator
      Overrides:
      getItemCountEstimate in class DataCommunicator<T>
      Returns:
      the item count estimate used

    • setItemCountEstimateIncrease

      public void setItemCountEstimateIncrease(int itemCountEstimateIncrease)
      Estimates are not supported in HierarchicalDataCommunicator
      Overrides:
      setItemCountEstimateIncrease in class DataCommunicator<T>
      Parameters:
      itemCountEstimateIncrease - the item count estimate step to use

    • getItemCountEstimateIncrease

      public int getItemCountEstimateIncrease()
      Estimates are not supported in HierarchicalDataCommunicator
      Overrides:
      getItemCountEstimateIncrease in class DataCommunicator<T>
      Returns:
      the item count estimate increase

    • setDefinedSize

      public void setDefinedSize(boolean definedSize)
      Estimates are not supported in HierarchicalDataCommunicator
      Overrides:
      setDefinedSize in class DataCommunicator<T>
      Parameters:
      definedSize - true for defined size, false for undefined size

    • isDefinedSize

      public boolean isDefinedSize()
      Estimates are not supported in HierarchicalDataCommunicator. Therefore this method will always return true
      Overrides:
      isDefinedSize in class DataCommunicator<T>
      Returns:
      true for defined size, false for undefined size