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.EnumSet;
022import java.util.Optional;
023import java.util.Set;
024
025/// Represents a request for [Resource]s of a specified type, to be
026/// processed by a [ResourceProvider].
027/// 
028/// When requesting resources from a [Project], the [Project] forwards
029/// the request to its dependencies that have been associated with one
030/// of the [Intent]s specified with [#using(Set)].
031///
032/// @param <T> the requested type
033///
034public interface ResourceRequest<T extends Resource> extends Cloneable {
035
036    /// Return the requested type.
037    ///
038    /// @return the resource type
039    ///
040    ResourceType<? extends T> type();
041
042    /// Return a new resource request for a resource with the given name.
043    /// 
044    /// Support for resource names is optional and provider-specific.
045    /// Expect the name to be ignored if not explicitly supported for
046    /// a given resource type and provider.
047    ///
048    /// @param name the name
049    /// @return the resource request
050    ///
051    ResourceRequest<T> withName(String name);
052
053    /// Returns the name that the requested resource should have.
054    ///
055    /// @return the name if set
056    ///
057    Optional<String> name();
058
059    /// Return a new resource request that uses project providers with
060    /// the given intents.
061    ///
062    /// @param intents the intents
063    /// @return the resource request
064    ///
065    ResourceRequest<T> using(Set<Intent> intents);
066
067    /// Return a new resource request that uses a project's providers
068    /// with the given intents.
069    ///
070    /// @param intent the intent
071    /// @param intents the intents
072    /// @return the resource request
073    ///
074    default ResourceRequest<T> using(Intent intent, Intent... intents) {
075        return using(EnumSet.of(intent, intents));
076    }
077
078    /// Return a new resource request that uses all providers of projects.
079    ///
080    /// @return the resource request
081    ///
082    default ResourceRequest<T> usingAll() {
083        return using(EnumSet.allOf(Intent.class));
084    }
085
086    /// Returns the intents to be used for selecting providers.
087    ///
088    /// @return the sets the
089    ///
090    Set<Intent> uses();
091
092    /// Checks if the query accepts results of the given type. This
093    /// is short for `type().isAssignableFrom(type)`. 
094    ///
095    /// @param type the type to check
096    /// @return true, if successful
097    ///
098    boolean accepts(ResourceType<?> type);
099
100    /// Checks if the query requires results of the given type. This
101    /// is short for `type.isAssignableFrom(type())`. 
102    ///
103    /// @param type the type to check
104    /// @return true, if successful
105    ///
106    boolean requires(ResourceType<?> type);
107}