001/*
002 * JDrupes Builder
003 * Copyright (C) 2025 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/// A marker interface to identify the root project.
024///
025public interface RootProject extends Project {
026
027    /// May be overridden by the root project to apply common settings
028    /// to projects of specific types or with specific properties.
029    /// 
030    /// This method must be invoked by any base class for project 
031    /// configuration classes before it returns the control to the
032    /// project configuration class' constructor. The method is never
033    /// invoked by the user.
034    ///
035    /// @param project the project to prepare
036    /// @throws Exception the exception
037    ///
038    @SuppressWarnings("PMD.SignatureDeclareThrowsException")
039    default void prepareProject(Project project) throws Exception {
040        // Default does nothing
041    }
042
043    /// Return the projects matching the pattern. The pattern is a glob
044    /// pattern applied to the project's directory. `""`matches the root
045    /// project. `"*"` matches the root project and all immediate
046    /// sub project. `"**"` matches all projects.
047    ///
048    /// @param pattern the pattern
049    /// @return the stream
050    ///
051    Stream<Project> projects(String pattern);
052
053    /// Define an alias for requesting one or more specific resources.
054    ///
055    /// @param name the name
056    /// @return the root project
057    ///
058    default CommandBuilder commandAlias(String name) {
059        throw new UnsupportedOperationException();
060    }
061
062    /// A builder for command aliases.
063    interface CommandBuilder {
064
065        /// Apply the request(s) to the projects selected by the given
066        /// pattern instead of the root project.
067        ///
068        /// @param pattern the pattern
069        /// @return the command builder
070        ///
071        CommandBuilder projects(String pattern);
072
073        /// Apply the request(s) to the root project or the selected
074        /// projects. The results from the request are written to the
075        /// standard output.
076        /// 
077        /// To simplify the command alias definition, this method
078        /// replaces a request with no intents (i.e. with
079        /// [ResourceRequest#uses()] being empty) with a request that
080        /// uses all intents.
081        ///
082        /// @param requests the requests
083        /// @return the root project
084        ///
085        RootProject resources(ResourceRequest<?>... requests);
086    }
087}