com.vaadin.data.provider.

Interface DataProvider<T,​F>

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

        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:

        
         try (Stream<T> stream = fetch(query)) {
             stream.forEach(System.out::println); // Example terminal operation
         }
         
        NOTE: This mainly concerns data providers where isInMemory() returns false. 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 if isInMemory() returns true.

        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) or BackEndDataProvider for more info.

        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:

        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)

      • 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. 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) or BackEndDataProvider for more info.

        See fetch(Query) for more information about handling I/O streams.

        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