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/// Interface for selecting [ResourceProvider]s from a [Project] based on
028/// filters and intents, and requesting resources from the selected
029/// providers.
030///
031public interface ProviderSelection {
032
033    /// Only include the [ResourceProvider]s for which the filter
034    /// evaluates to `true`.
035    ///
036    /// @param filter the filter
037    /// @return the provider selection
038    ///
039    ProviderSelection filter(Predicate<ResourceProvider> filter);
040
041    /// Exclude the given provider when fetching resources.
042    ///
043    /// @param provider the provider
044    /// @return the bound resource query
045    ///
046    ProviderSelection without(ResourceProvider provider);
047
048    /// Exclude providers of the given type when fetching resources.
049    ///
050    /// @param providerType the provider type
051    /// @return the bound resource query
052    ///
053    ProviderSelection
054            without(Class<? extends ResourceProvider> providerType);
055
056    /// Register a callback for logging the provider invocation.
057    ///
058    /// @param hook the hook
059    /// @return the bound resource query
060    ///
061    ProviderSelection onBeforeUse(Consumer<ResourceProvider> hook);
062
063    /// Returns the providers with the requested intents from the project
064    /// matching the defined filters.
065    ///
066    /// @param intents the intents
067    /// @return the stream
068    ///
069    Stream<ResourceProvider> select(Set<Intent> intents);
070
071    /// Returns the providers with the requested intents from the project
072    /// matching the defined filters.
073    ///
074    /// @param intent the intent
075    /// @param intents the intents
076    /// @return the stream
077    ///
078    default Stream<ResourceProvider> select(Intent intent, Intent... intents) {
079        return select(EnumSet.of(intent, intents));
080    }
081
082    /// Returns the requested resources using the providers with the
083    /// requested intents from the project passed to constructor
084    /// and the defined filters.
085    ///
086    /// @param <T> the requested resource type
087    /// @param requested the resource request
088    /// @return the stream
089    ///
090    <T extends Resource> Stream<T> resources(ResourceRequest<T> requested);
091
092}