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

Interface HierarchicalDataProvider<T,F>

Type Parameters:
T - data type
F - filter type
All Superinterfaces:
DataProvider<T,F>, Serializable
All Known Subinterfaces:
BackEndHierarchicalDataProvider<T,F>, HierarchicalConfigurableFilterDataProvider<T,Q,C>
All Known Implementing Classes:
AbstractBackEndHierarchicalDataProvider, AbstractHierarchicalDataProvider, TreeDataProvider
public interface HierarchicalDataProvider<T,F> extends DataProvider<T,F>
A common interface for fetching hierarchical data from a data source, such as an in-memory collection or a backend database. It supports two hierarchy formats: HierarchicalDataProvider.HierarchyFormat.NESTED and HierarchicalDataProvider.HierarchyFormat.FLATTENED.
Since:
1.2
Author:
Vaadin Ltd

  • Method Details

    • getHierarchyFormat

      default HierarchicalDataProvider.HierarchyFormat getHierarchyFormat()
      Specifies the format in which the data provider returns hierarchical data. The default format is HierarchicalDataProvider.HierarchyFormat.NESTED.

      The component uses this method to determine how to fetch and render hierarchical data with this data provider.

      Returns:
      the hierarchy format
      Since:
      25.0

    • size

      default int size(Query<T,F> query)
      Gets the number of children based on the given hierarchical query.

      The behavior of this method depends on the implemented hierarchy format, see getHierarchyFormat() and getChildCount(HierarchicalQuery)

      Specified by:
      size in interface DataProvider<T,F>
      Parameters:
      query - given query to request the count for
      Returns:
      the count of children for the parent item HierarchicalQuery.getParent() or the root level if null
      Throws:
      IllegalArgumentException - if the query is not of type HierarchicalQuery

    • fetch

      default Stream<T> fetch(Query<T,F> query)
      Fetches children based on the given hierarchical query.

      The behavior of this method depends on the implemented hierarchy format, see getHierarchyFormat() and fetchChildren(HierarchicalQuery)

      Specified by:
      fetch in interface DataProvider<T,F>
      Parameters:
      query - given query to request data with
      Returns:
      a stream of data objects for the parent item or the root level if the parent is null, must not contain null values
      Throws:
      IllegalArgumentException - if the query is not of type HierarchicalQuery

    • getChildCount

      int getChildCount(HierarchicalQuery<T,F> query)
      Gets the number of children based on the given hierarchical query.

      This method must be implemented in accordance with the selected hierarchy type, see getHierarchyFormat() and HierarchicalDataProvider.HierarchyFormat.

      Parameters:
      query - given query to request the count for
      Returns:
      the count of children for the parent item or the root level if the parent is null

    • fetchChildren

      Stream<T> fetchChildren(HierarchicalQuery<T,F> query)
      Fetches children based on the given hierarchical query.

      This method must be implemented in accordance with the selected hierarchy type, see getHierarchyFormat() and HierarchicalDataProvider.HierarchyFormat.

      Parameters:
      query - given query to request data with
      Returns:
      a stream of data objects for the parent item or the root level if the parent is null, must not contain null values

    • hasChildren

      boolean hasChildren(T item)
      Check whether a given item has any children associated with it.
      Parameters:
      item - the item to check for children
      Returns:
      whether the given item has children

    • getParent

      default T getParent(T item)
      Gets the parent item for the given item.
      Parameters:
      item - the item for which to retrieve the parent item for
      Returns:
      parent item for the given item or null if the item is a root item
      Throws:
      UnsupportedOperationException - if not implemented

    • getItemIndex

      default int getItemIndex(T item, HierarchicalQuery<T,F> query)
      Gets the index of a given item based on the given hierarchical query.

      This method must be implemented in accordance with the selected hierarchy type, see getHierarchyFormat() and HierarchicalDataProvider.HierarchyFormat.

      This method has a default implementation for in-memory data providers.

      Parameters:
      item - the item to get the index for
      query - given query to request data with
      Returns:
      the index of the provided item or -1 if not found
      Throws:
      UnsupportedOperationException - if not implemented

    • getDepth

      default int getDepth(T item)
      Gets the depth of a given item in the hierarchy, starting from zero (root).

      This method must be implemented for data providers that implement the flattened hierarchy format, see getHierarchyFormat() and HierarchicalDataProvider.HierarchyFormat.FLATTENED.

      Parameters:
      item - the item to get the depth for
      Returns:
      the depth of the item in the hierarchy
      Throws:
      UnsupportedOperationException - if not implemented

    • withConfigurableFilter

      default <Q, C> HierarchicalConfigurableFilterDataProvider<T,Q,C> withConfigurableFilter(SerializableBiFunction<Q,C,F> filterCombiner)
      Description copied from interface: DataProvider
      Wraps this data provider to create a data provider that supports programmatically setting a filter that will be combined with a filter provided through the query.
      Specified by:
      withConfigurableFilter in interface DataProvider<T,F>
      Type Parameters:
      Q - the query filter type
      C - the configurable filter type
      Parameters:
      filterCombiner - a callback for combining and the configured filter with the filter from the query to get a filter to pass to the wrapped provider. Either parameter might be null, but the callback will not be invoked at all if both would be null. Not null.
      Returns:
      a data provider with a configurable filter, not null
      See Also:

    • withConvertedFilter

      default <C> HierarchicalDataProvider<T,C> withConvertedFilter(SerializableFunction<C,F> filterConverter)
      Description copied from interface: DataProvider
      Wraps this data provider to create a data provider that uses a different filter type. This can be used for adapting this data provider to a filter type provided by a Component such as ComboBox.

      For example receiving a String from ComboBox and making a Predicate based on it: 

       DataProvider<Person, Predicate<Person>> dataProvider;
 // ComboBox uses String as the filter type
 DataProvider<Person, String> wrappedProvider = dataProvider
         .withConvertedFilter(filterText -> {
             Predicate<Person> predicate = person -> person.getName()
                     .startsWith(filterText);
             return predicate;
         });
 comboBox.setDataProvider(wrappedProvider);
      Specified by:
      withConvertedFilter in interface DataProvider<T,F>
      Type Parameters:
      C - the filter type that the wrapped data provider accepts; typically provided by a Component
      Parameters:
      filterConverter - callback that converts the filter in the query of the wrapped data provider into a filter supported by this data provider. Will only be called if the query contains a filter. Not null
      Returns:
      wrapped data provider, not null

    • withConfigurableFilter

      default HierarchicalConfigurableFilterDataProvider<T,Void,F> withConfigurableFilter()
      Description copied from interface: DataProvider
      Wraps this data provider to create a data provider that supports programmatically setting a filter but no filtering through the query.
      Specified by:
      withConfigurableFilter in interface DataProvider<T,F>
      Returns:
      a data provider with a configurable filter, not null
      See Also: