001/*
002 * JDrupes Builder
003 * Copyright (C) 2025, 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.stream.Stream;
022
023/// This interface defines access to a resource provider, in particular,
024/// to the provider's resources. Resources are accessed by invoking
025/// [resources][#resources] with a [ResourceRequest]. In addition, this
026/// interface serves as a factory for creating the [ResourceRequest]
027/// instances used for these invocations.
028/// 
029/// Note that this interface specifies how a provider is invoked. Resource
030/// provider implementations must implement the [ResourceProviderSpi].
031///
032public interface ResourceProvider {
033
034    /// Returns the name of this resource provider.
035    ///
036    /// @return the string
037    ///
038    String name();
039
040    /// Returns resources provided by this resource provider. Short for
041    /// `context().resources(this, request)`.
042    ///
043    /// @param <T> the generic type
044    /// @param requested the request
045    /// @return the stream
046    ///
047    default <T extends Resource> Stream<T>
048            resources(ResourceRequest<T> requested) {
049        return context().resources(this, requested);
050    }
051
052    /// Convenience method to access the build context which is sometimes
053    /// needed in the context of resource requests.
054    ///
055    /// @return the builder configuration
056    ///
057    BuildContext context();
058
059    /// Create a new request for the given resource.
060    ///
061    /// @param <T> the resource type
062    /// @param type the type
063    /// @return the resource request
064    ///
065    @SuppressWarnings("PMD.ShortMethodName")
066    <T extends Resource> ResourceRequest<T> of(ResourceType<? extends T> type);
067
068    /// Create a new request for the given resource type.
069    ///
070    /// @param <T> the resource type
071    /// @param requested the requested
072    /// @return the resource request
073    ///
074    @SuppressWarnings("PMD.ShortMethodName")
075    default <T extends Resource> ResourceRequest<T> of(Class<T> requested) {
076        return of(new ResourceType<>(requested, null));
077    }
078}