com.vaadin.data.provider.
Interface DataProvider<T,F>
-
Type Parameters:
T
- data typeF
- filter typeAll Superinterfaces:
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 implementingHasDataProvider
orHasFilterableDataProvider
. The listing component will provide aQuery
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 staticcreate
methods in this interface. For custom backends such as SQL, EntityManager, REST APIs or SpringData, use aBackEndDataProvider
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
All Methods Modifier and Type Method 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 filteringReturns:
the size of the data provider
-
fetch
Stream<T> fetch(Query<T,F> query)
Fetches data from this DataProvider using given
query
.Depending on the use case this operation might open I/O channels.
Consumers of the returned stream are responsible for closing it when all the stream operations are done to ensure that any resources feeding the stream are properly released. Failure to close an I/O stream might lead to resource leaks.
It is strongly recommended to use a try-with-resources block to automatically close an I/O stream after its terminal operation has been executed. Below is an example of how to properly use and close the stream:
NOTE: This mainly concerns data providers wheretry (Stream<T> stream = fetch(query)) { stream.forEach(System.out::println); // Example terminal operation }
isInMemory()
returnsfalse
. While it is technically possible to configure or extend an in-memory data provider in a way that compromises the in-memory nature, doing so is conceptually frowned upon. In applications that choose to do so regardless, the use of this pattern is strongly recommended even ifisInMemory()
returnstrue
.The try-with-resources pattern is safe to use with this method even if you are unsure whether or not it returns an I/O stream, but it's unnecessary to apply the pattern to all stream handling everywhere. For most streams the only consumed resource is memory, and Java's built-in cleanup is sufficient to free it.
With large data sets where memory consumption might become a problem it is recommended to use lazy data providers instead of in-memory ones. See e.g.
fromCallbacks(FetchCallback, CountCallback)
orBackEndDataProvider
for more info.Parameters:
query
- given query to request dataReturns:
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
Object.equals(Object)
andObject.hashCode()
to consider both the old and the new item instances to be equal, or alternativelygetId(Object)
should be implemented to return an appropriate identifier.Parameters:
item
- the item to refreshSee Also:
-
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)
andObject.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; notnull
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 firesDataChangeEvent
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 nullReturns:
a registration for the listener
See Also:
-
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 ComponentParameters:
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. Notnull
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 benull
, but the callback will not be invoked at all if both would benull
. Notnull
.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 typeParameters:
items
- the collection of data, notnull
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 typeParameters:
items
- the data itemsReturns:
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. The stream is eagerly closed after the operation in case it's connected to open I/O channels.
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)
orBackEndDataProvider
for more info.See
fetch(Query)
for more information about handling I/O streams.Type Parameters:
T
- the data item typeParameters:
items
- a stream of data items, notnull
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 querycountCallback
- function that returns the number of items in the back end for a queryReturns:
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 querycountCallback
- function that returns the number of items in the back end for a queryReturns:
a new callback data provider
-
-