Package com.vaadin.flow.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>, HierarchicalConfigurableFilterDataProvider<T,Q,C>, HierarchicalDataProvider<T,F>, InMemoryDataProvider<T>
All Known Implementing Classes:
AbstractBackEndDataProvider, AbstractBackEndHierarchicalDataProvider, AbstractDataProvider, AbstractHierarchicalDataProvider, CallbackDataProvider, ConfigurableFilterDataProviderWrapper, DataCommunicator.EmptyDataProvider, 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:
1.0.
Author:
Vaadin Ltd
See Also:

  • Method Details

    • 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 Object.equals(Object) and Object.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:

    • refreshItem

      default void refreshItem(T item, boolean refreshChildren)
      Refreshes the given item and all of the children of the item as well.
      Parameters:
      item - the item to refresh
      refreshChildren - whether or not to refresh child items
      See 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) 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:

    • 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 -> {
             Predicate<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.
      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:

    • 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:

    • 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(CallbackDataProvider.FetchCallback, CallbackDataProvider.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.

      Type Parameters:
      T - data provider data type
      F - data provider filter type
      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.

      Type Parameters:
      T - data provider data type
      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