com.vaadin.data.provider

Interface DataProvider<T,F>

Type Parameters:

T - data type

F - filter type

All Superinterfaces:

Serializable

All Known Subinterfaces:

BackEndDataProvider<T,F>, BackEndHierarchicalDataProvider<T,F>, ConfigurableFilterDataProvider<T,Q,C>, HierarchicalDataProvider<T,F>, InMemoryDataProvider<T>

All Known Implementing Classes:

AbstractBackEndDataProvider, AbstractBackEndHierarchicalDataProvider, AbstractDataProvider, AbstractHierarchicalDataProvider, CallbackDataProvider, ConfigurableFilterDataProviderWrapper, DataProviderWrapper, ListDataProvider, TreeDataProvider

public interface DataProvider<T,F>
extends Serializable

A common interface for fetching data from a backend. The DataProvider interface is used by listing components implementing HasDataProvider or HasFilterableDataProvider. The listing component will provide a Query object with request information, and the data provider uses this information to return a stream containing requested beans.

Vaadin comes with a ready-made solution for in-memory data, known as ListDataProvider which can be created using static create methods in this interface. For custom backends such as SQL, EntityManager, REST APIs or SpringData, use a BackEndDataProvider or its subclass.

Since:

8.0

Author:

Vaadin Ltd.

See Also:

ofCollection(Collection), ofItems(Object...), fromStream(Stream), #fromCallbacks(FetchCallback, CountCallback), #fromFilteringCallbacks(FetchCallback, CountCallback), ListDataProvider, BackEndDataProvider

Method Summary

Modifier and Type	Method and Description
Registration	addDataProviderListener(DataProviderListener<T> listener) Adds a data provider listener.
Stream<T>	fetch(Query<T,F> query) Fetches data from this DataProvider using given query.
static <T> CallbackDataProvider<T,Void>	fromCallbacks(CallbackDataProvider.FetchCallback<T,Void> fetchCallback, CallbackDataProvider.CountCallback<T,Void> countCallback) Creates a new data provider that uses callbacks for fetching and counting items from any backing store.
static <T,F> CallbackDataProvider<T,F>	fromFilteringCallbacks(CallbackDataProvider.FetchCallback<T,F> fetchCallback, CallbackDataProvider.CountCallback<T,F> countCallback) Creates a new data provider that uses filtering callbacks for fetching and counting items from any backing store.
static <T> ListDataProvider<T>	fromStream(Stream<T> items) Creates a new data provider from the given stream.
default Object	getId(T item) Gets an identifier for the given item.
boolean	isInMemory() Gets whether the DataProvider content all available in memory or does it use some external backend.
static <T> ListDataProvider<T>	ofCollection(Collection<T> items) Creates a new data provider backed by a collection.
static <T> ListDataProvider<T>	ofItems(T... items) Creates a new data provider from the given items.
void	refreshAll() Refreshes all data based on currently available data in the underlying provider.
void	refreshItem(T item) Refreshes the given item.
int	size(Query<T,F> query) Gets the amount of data in this DataProvider.
default ConfigurableFilterDataProvider<T,Void,F>	withConfigurableFilter() Wraps this data provider to create a data provider that supports programmatically setting a filter but no filtering through the query.
default <Q,C> ConfigurableFilterDataProvider<T,Q,C>	withConfigurableFilter(SerializableBiFunction<Q,C,F> filterCombiner) 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.
default <C> DataProvider<T,C>	withConvertedFilter(SerializableFunction<C,F> filterConverter) Wraps this data provider to create a data provider that uses a different filter type.

Method Detail

isInMemory

boolean isInMemory()

Gets whether the DataProvider content all available in memory or does it use some external backend.

Returns:

true if all data is in memory; false if not

size

int size(Query<T,F> query)

Gets the amount of data in this DataProvider.

Parameters:

query - query with sorting and filtering

Returns:

the size of the data provider

fetch

Stream<T> fetch(Query<T,F> query)

Fetches data from this DataProvider using given query.

Parameters:

query - given query to request data

Returns:

the result of the query request: a stream of data objects, not null

refreshItem

void refreshItem(T item)

Refreshes the given item. This method should be used to inform all DataProviderListeners that an item has been updated or replaced with a new instance.

For this to work properly, the item must either implement #equals(Object) and #hashCode() to consider both the old and the new item instances to be equal, or alternatively getId(Object) should be implemented to return an appropriate identifier.

Parameters:

item - the item to refresh

See Also:

getId(Object)

refreshAll

void refreshAll()

Refreshes all data based on currently available data in the underlying provider.

getId

default Object getId(T item)

Gets an identifier for the given item. This identifier is used by the framework to determine equality between two items.

Default is to use item itself as its own identifier. If the item has Object.equals(Object) and Object.hashCode() implemented in a way that it can be compared to other items, no changes are required.

Note: This method will be called often by the Framework. It should not do any expensive operations.

Parameters:

item - the item to get identifier for; not null

Returns:

the identifier for given item; not null

addDataProviderListener

Registration addDataProviderListener(DataProviderListener<T> listener)

Adds a data provider listener. The listener is called when some piece of data is updated.

The refreshAll() method fires DataChangeEvent each time when it's called. It allows to update UI components when user changes something in the underlying data.

Parameters:

listener - the data change listener, not null

Returns:

a registration for the listener

See Also:

refreshAll()

withConvertedFilter

default <C> DataProvider<T,C> withConvertedFilter(SerializableFunction<C,F> filterConverter)

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 -> {
             SerializablePredicate<Person> predicate = person -> person
                     .getName().startsWith(filterText);
             return predicate;
         });
 comboBox.setDataProvider(wrappedProvider);
 

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 <Q,C> ConfigurableFilterDataProvider<T,Q,C> withConfigurableFilter(SerializableBiFunction<Q,C,F> filterCombiner)

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.

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:

withConfigurableFilter(), ConfigurableFilterDataProvider.setFilter(Object)

withConfigurableFilter

default ConfigurableFilterDataProvider<T,Void,F> withConfigurableFilter()

Wraps this data provider to create a data provider that supports programmatically setting a filter but no filtering through the query.

Returns:

a data provider with a configurable filter, not null

See Also:

withConfigurableFilter(SerializableBiFunction), ConfigurableFilterDataProvider.setFilter(Object)

ofCollection

static <T> ListDataProvider<T> ofCollection(Collection<T> items)

Creates a new data provider backed by a collection.

The collection is used as-is. Changes in the collection will be visible via the created data provider. The caller should copy the collection if necessary.

Type Parameters:

T - the data item type

Parameters:

items - the collection of data, not null

Returns:

a new list data provider

ofItems

@SafeVarargs
static <T> ListDataProvider<T> ofItems(T... items)

Creates a new data provider from the given items.

The items are copied into a new backing list, so structural changes to the provided array will not be visible via the created data provider.

Type Parameters:

T - the data item type

Parameters:

items - the data items

Returns:

a new list data provider

fromStream

static <T> ListDataProvider<T> fromStream(Stream<T> items)

Creates a new data provider from the given stream. All items in the stream are eagerly collected to a list.

This is a shorthand for using ofCollection(Collection) after collecting the items in the stream to a list with e.g. stream.collect(Collectors.toList));.

Using big streams is not recommended, you should instead use a lazy data provider. See #fromCallbacks(FetchCallback, CountCallback) or BackEndDataProvider for more info.

Type Parameters:

T - the data item type

Parameters:

items - a stream of data items, not null

Returns:

a new list data provider

fromFilteringCallbacks

static <T,F> CallbackDataProvider<T,F> fromFilteringCallbacks(CallbackDataProvider.FetchCallback<T,F> fetchCallback,
                                                              CallbackDataProvider.CountCallback<T,F> countCallback)

Creates a new data provider that uses filtering callbacks for fetching and counting items from any backing store.

The query that is passed to each callback may contain a filter value that is provided by the component querying for data.

Parameters:

fetchCallback - function that returns a stream of items from the back end for a query

countCallback - function that returns the number of items in the back end for a query

Returns:

a new callback data provider

fromCallbacks

static <T> CallbackDataProvider<T,Void> fromCallbacks(CallbackDataProvider.FetchCallback<T,Void> fetchCallback,
                                                      CallbackDataProvider.CountCallback<T,Void> countCallback)

Creates a new data provider that uses callbacks for fetching and counting items from any backing store.

The query that is passed to each callback will not contain any filter values.

Parameters:

fetchCallback - function that returns a stream of items from the back end for a query

countCallback - function that returns the number of items in the back end for a query

Returns:

a new callback data provider