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
049            resources(ResourceRequest<T> requested) {
050        return context().resources(this, requested);
051    }
052
053    /// Convenience method to access the build context which is sometimes
054    /// needed in the context of resource requests.
055    ///
056    /// @return the builder configuration
057    ///
058    BuildContext context();
059
060    /// Create a new request for the given resource.
061    ///
062    /// @param <T> the resource type
063    /// @param type the type
064    /// @return the resource request
065    ///
066    @SuppressWarnings("PMD.ShortMethodName")
067    <T extends Resource> ResourceRequest<T> of(ResourceType<? extends T> type);
068
069    /// Create a new request for the given resource type.
070    ///
071    /// @param <T> the resource type
072    /// @param requested the requested
073    /// @return the resource request
074    ///
075    @SuppressWarnings("PMD.ShortMethodName")
076    default <T extends Resource> ResourceRequest<T> of(Class<T> requested) {
077        return of(new ResourceType<>(requested, null));
078    }
079}