001/*
002 * JDrupes Builder
003 * Copyright (C) 2026 Michael N. Lipp
004 * 
005 * This program is free software: you can redistribute it and/or modify
006 * it under the terms of the GNU Affero General Public License as
007 * published by the Free Software Foundation, either version 3 of the
008 * License, or (at your option) any later version.
009 *
010 * This program is distributed in the hope that it will be useful,
011 * but WITHOUT ANY WARRANTY; without even the implied warranty of
012 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
013 * GNU Affero General Public License for more details.
014 *
015 * You should have received a copy of the GNU Affero General Public License
016 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
017 */
018
019package org.jdrupes.builder.api;
020
021import java.util.EnumSet;
022import java.util.Set;
023import java.util.function.Consumer;
024import java.util.function.Predicate;
025import java.util.stream.Stream;
026
027/// The interface ProviderSelection.
028///
029public interface ProviderSelection {
030
031    /// Only include the [ResourceProvider]s for which the filter
032    /// evaluates to `true`.
033    ///
034    /// @param filter the filter
035    /// @return the provider selection
036    ///
037    ProviderSelection filter(Predicate<ResourceProvider> filter);
038
039    /// Exclude the given provider when fetching resources.
040    ///
041    /// @param provider the provider
042    /// @return the bound resource query
043    ///
044    ProviderSelection without(ResourceProvider provider);
045
046    /// Exclude providers of the given type when fetching resources.
047    ///
048    /// @param providerType the provider type
049    /// @return the bound resource query
050    ///
051    ProviderSelection
052            without(Class<? extends ResourceProvider> providerType);
053
054    /// Register a callback for logging the provider invocation.
055    ///
056    /// @param hook the hook
057    /// @return the bound resource query
058    ///
059    ProviderSelection onBeforeUse(Consumer<ResourceProvider> hook);
060
061    /// Returns the providers with the requested intents from the project
062    /// matching the defined filters.
063    ///
064    /// @param intents the intents
065    /// @return the stream
066    ///
067    Stream<ResourceProvider> select(Set<Intent> intents);
068
069    /// Returns the providers with the requested intents from the project
070    /// matching the defined filters.
071    ///
072    /// @param intent the intent
073    /// @param intents the intents
074    /// @return the stream
075    ///
076    default Stream<ResourceProvider> select(Intent intent, Intent... intents) {
077        return select(EnumSet.of(intent, intents));
078    }
079
080    /// Returns the requested resources using the providers with the
081    /// requested intents from the project passed to constructor
082    /// and the defined filters.
083    ///
084    /// @param <T> the requested resource type
085    /// @param requested the resource request
086    /// @return the stream
087    ///
088    <T extends Resource> Stream<T> resources(ResourceRequest<T> requested);
089
090}