com.vaadin.data.HasHierarchicalDataProvider Maven / Gradle / Ivy
/*
* Copyright (C) 2000-2024 Vaadin Ltd
*
* This program is available under Vaadin Commercial License and Service Terms.
*
* See for the full
* license.
*/
package com.vaadin.data;
import java.util.Arrays;
import java.util.Collection;
import java.util.Objects;
import java.util.stream.Collectors;
import java.util.stream.Stream;
import com.vaadin.data.provider.DataProvider;
import com.vaadin.data.provider.HierarchicalDataProvider;
import com.vaadin.data.provider.TreeDataProvider;
/**
* A generic interface for hierarchical listing components that use a data
* provider for showing data.
*
* @author Vaadin Ltd
* @since 8.1
*
* @param
* the item data type
*/
public interface HasHierarchicalDataProvider extends HasDataProvider {
/**
* Sets a new {@link TreeDataProvider} wrapping the given {@link TreeData}.
*
* @param treeData
* the tree data to set
*/
public default void setTreeData(TreeData treeData) {
setDataProvider(new TreeDataProvider<>(treeData));
}
/**
* Gets the backing {@link TreeData} instance of the data provider, if the
* data provider is a {@link TreeDataProvider}.
*
* @return the TreeData instance used by the data provider
* @throws IllegalStateException
* if the type of the data provider is not
* {@link TreeDataProvider}
*/
@SuppressWarnings("unchecked")
public default TreeData getTreeData() {
if (getDataProvider() instanceof TreeDataProvider) {
return ((TreeDataProvider) getDataProvider()).getTreeData();
} else {
throw new IllegalStateException(
"Data provider is not an instance of TreeDataProvider");
}
}
/**
* Sets the root data items of this component provided as a collection and
* recursively populates them with child items with the given value
* provider.
*
* The provided items are wrapped into a {@link TreeDataProvider} backed by
* a flat {@link TreeData} structure. The data provider instance is used as
* a parameter for the {@link #setDataProvider(DataProvider)} method. It
* means that the items collection can be accessed later on via
* {@link #getTreeData()}:
*
*
*
* Collection<Person> grandParents = getGrandParents();
* HasHierarchicalDataProvider<Person> treeGrid = new TreeGrid<>();
* treeGrid.setItems(grandParents, Person::getChildren);
* ...
*
* TreeData<Person> data = treeGrid.getTreeData();
*
*
*
* The returned {@link TreeData} instance may be used as-is to add, remove
* or modify items in the hierarchy. These modifications to the object are
* not automatically reflected back to the TreeGrid. Items modified should
* be refreshed with {@link HierarchicalDataProvider#refreshItem(Object)}
* and when adding or removing items
* {@link HierarchicalDataProvider#refreshAll()} should be called.
*
* @param rootItems
* the root items to display, not {@code null}
* @param childItemProvider
* the value provider used to recursively populate the given root
* items with child items, not {@code null}
*/
public default void setItems(Collection rootItems,
ValueProvider> childItemProvider) {
Objects.requireNonNull(rootItems, "Given root items may not be null");
Objects.requireNonNull(childItemProvider,
"Given child item provider may not be null");
setDataProvider(new TreeDataProvider<>(
new TreeData().addItems(rootItems, childItemProvider)));
}
/**
* Sets the root data items of this component provided as a stream and
* recursively populates them with child items with the given value
* provider.
*
* The provided items are wrapped into a {@link TreeDataProvider} backed by
* a flat {@link TreeData} structure. The data provider instance is used as
* a parameter for the {@link #setDataProvider(DataProvider)} method. It
* means that the items collection can be accessed later on via
* {@link #getTreeData()}:
*
*
*
* Stream<Person> grandParents = getGrandParents();
* HasHierarchicalDataProvider<Person> treeGrid = new TreeGrid<>();
* treeGrid.setItems(grandParents, Person::getChildren);
* ...
*
* TreeData<Person> data = treeGrid.getTreeData();
*
*
*
* The returned {@link TreeData} instance may be used as-is to add, remove
* or modify items in the hierarchy. These modifications to the object are
* not automatically reflected back to the TreeGrid. Items modified should
* be refreshed with {@link HierarchicalDataProvider#refreshItem(Object)}
* and when adding or removing items
* {@link HierarchicalDataProvider#refreshAll()} should be called.
*
* @param rootItems
* the root items to display, not {@code null}
* @param childItemProvider
* the value provider used to recursively populate the given root
* items with child items, not {@code null}
*/
public default void setItems(Stream rootItems,
ValueProvider> childItemProvider) {
Objects.requireNonNull(rootItems, "Given root items may not be null");
Objects.requireNonNull(childItemProvider,
"Given child item provider may not be null");
setDataProvider(new TreeDataProvider<>(
new TreeData().addItems(rootItems, childItemProvider)));
}
/**
* Sets the data items of this component provided as a collection.
*
* The provided items are wrapped into a {@link TreeDataProvider} backed by
* a flat {@link TreeData} structure. The data provider instance is used as
* a parameter for the {@link #setDataProvider(DataProvider)} method. It
* means that the items collection can be accessed later on via
* {@link #getTreeData()}:
*
*
*
* HasHierarchicalDataProvider<String> treeGrid = new TreeGrid<>();
* treeGrid.setItems(Arrays.asList("a","b"));
* ...
*
* TreeData<String> data = treeGrid.getTreeData();
*
*
*
* The returned {@link TreeData} instance may be used as-is to add, remove
* or modify items in the hierarchy. These modifications to the object are
* not automatically reflected back to the TreeGrid. Items modified should
* be refreshed with {@link HierarchicalDataProvider#refreshItem(Object)}
* and when adding or removing items
* {@link HierarchicalDataProvider#refreshAll()} should be called.
*
* @param items
* the data items to display, not {@code null}
*/
@Override
public default void setItems(Collection items) {
Objects.requireNonNull(items, "Given collection may not be null");
setDataProvider(new TreeDataProvider<>(
new TreeData().addItems(null, items)));
}
/**
* Sets the data items of this component provided as a stream.
*
* The provided items are wrapped into a {@link TreeDataProvider} backed by
* a flat {@link TreeData} structure. The data provider instance is used as
* a parameter for the {@link #setDataProvider(DataProvider)} method. It
* means that the items collection can be accessed later on via
* {@link #getTreeData()}:
*
*
*
* HasHierarchicalDataProvider<String> treeGrid = new TreeGrid<>();
* treeGrid.setItems(Stream.of("a","b"));
* ...
*
* TreeData<String> data = treeGrid.getTreeData();
*
*
*
* The returned {@link TreeData} instance may be used as-is to add, remove
* or modify items in the hierarchy. These modifications to the object are
* not automatically reflected back to the TreeGrid. Items modified should
* be refreshed with {@link HierarchicalDataProvider#refreshItem(Object)}
* and when adding or removing items
* {@link HierarchicalDataProvider#refreshAll()} should be called.
*
* @param items
* the data items to display, not {@code null}
*/
@Override
public default void setItems(Stream items) {
Objects.requireNonNull(items, "Given stream may not be null");
setItems(items.collect(Collectors.toList()));
}
/**
* Sets the data items of this listing.
*
* The provided items are wrapped into a {@link TreeDataProvider} backed by
* a flat {@link TreeData} structure. The data provider instance is used as
* a parameter for the {@link #setDataProvider(DataProvider)} method. It
* means that the items collection can be accessed later on via
* {@link #getTreeData()}:
*
*
*
* TreeGrid<String> treeGrid = new TreeGrid<>();
* treeGrid.setItems("a","b");
* ...
*
* TreeData<String> data = treeGrid.getTreeData();
*
*
*
* The returned {@link TreeData} instance may be used as-is to add, remove
* or modify items in the hierarchy. These modifications to the object are
* not automatically reflected back to the TreeGrid. Items modified should
* be refreshed with {@link HierarchicalDataProvider#refreshItem(Object)}
* and when adding or removing items
* {@link HierarchicalDataProvider#refreshAll()} should be called.
*
* @param items
* the data items to display, not {@code null}
*/
@Override
public default void setItems(@SuppressWarnings("unchecked") T... items) {
Objects.requireNonNull(items, "Given items may not be null");
setItems(Arrays.asList(items));
}
}