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.io.IOException;
022import java.io.PrintStream;
023import java.nio.file.Path;
024import java.util.stream.Stream;
025import org.apache.commons.cli.CommandLine;
026
027/// The context of a build.
028///
029public interface BuildContext extends AutoCloseable {
030
031    /// The key for specifying the builder directory in the properties file.
032    String JDBLD_DIRECTORY = "jdbldDirectory";
033
034    /// The key for specifying the builder version in the properties file.
035    String JDBLD_VERSION = "jdbldVersion";
036
037    /// The key for specifying the build extensions in the properties file.
038    String BUILD_EXTENSIONS = "buildExtensions";
039
040    /// The key for specifying the extension repositories in the
041    /// properties file.
042    String EXTENSIONS_REPOSITORIES = "extensionsRepositories";
043
044    /// The key for specifying the extensions snapshot repository in the
045    /// properties file.
046    @SuppressWarnings("PMD.LongVariable")
047    String EXTENSIONS_SNAPSHOT_REPOSITORY = "extensionsSnapshotRepository";
048
049    /// The key for specifying the common configuration and cache directory.
050    String JDBLD_COMMON_DIRECTORY = "jdbldCommonDirectory";
051
052    /// Returns the relative path from a project directory to
053    /// the JDrupes Builder directory.
054    ///
055    /// @return the path
056    ///
057    default Path jdbldDirectory() {
058        return Path.of(property(JDBLD_DIRECTORY, "_jdbld"));
059    }
060
061    /// The path to the common cache directory. This may be used by
062    /// providers to cache information that is shared between projects.
063    /// Providers must create a sub-directory of this directory, preferably
064    /// with the same name FQN as the provider.
065    ///
066    /// @return the path
067    ///
068    default Path commonCacheDirectory() {
069        return Path.of(property(JDBLD_COMMON_DIRECTORY,
070            System.getProperty("user.home") + "/.jdbld")).resolve("cache");
071    }
072
073    /// The command line as processed by Apache Commons CLI.
074    ///
075    /// @return the parsed command line
076    ///
077    CommandLine commandLine();
078
079    /// Returns the class loader to use for loading resources.
080    ///
081    /// @return the class loader
082    ///
083    ClassLoader classLoader();
084
085    /// Obtains the stream of resources of the given type from the
086    /// given provider. The result from invoking the provider is
087    /// evaluated asynchronously and cached. Only when the returned
088    /// stream is consumed will the invocation block until the
089    /// result from the provider becomes available.
090    /// 
091    /// To avoid duplicate invocations of a non-project provider,
092    /// any intends are removed from the request before such a
093    /// provider is invoked.
094    ///
095    /// @param <T> the resource type
096    /// @param provider the provider
097    /// @param request the request
098    /// @return the results
099    ///
100    <T extends Resource> Stream<T> resources(ResourceProvider provider,
101            ResourceRequest<T> request);
102
103    /// Returns the value of the given property. Properties are defined by
104    /// (in order of precedence):
105    ///   1. command line options
106    ///   2. the file `.jdbld.properties` in the directory of the
107    ///      root project
108    ///   3. the file `.jdbld/jdbld.properties` in the user's home directory
109    ///
110    /// @param name the name
111    /// @param defaultValue the default value
112    /// @return the string
113    ///
114    String property(String name, String defaultValue);
115
116    /// Returns the status line for the current thread. The status line
117    /// may be used by [ResourceProvider]s to indicate progress during
118    /// the execution of [ResourceProviderSpi#provide(ResourceRequest)].
119    /// A [StatusLine] is automatically allocated by the context when
120    /// [#resources] is invoked.
121    /// 
122    /// When called while not executing [#resources], this method
123    /// returns a dummy status line that discards all updates.
124    ///
125    /// @return the status line
126    ///
127    StatusLine statusLine();
128
129    /// Returns the [PrintStream] for the standard output.
130    ///
131    /// @return the print stream
132    ///
133    PrintStream out();
134
135    /// Returns a [PrintStream] for errors. The data is sent to the
136    /// standard output stream as with [#out], but it is marked,
137    /// typically in red, to indicate an error.
138    ///
139    /// @return the print stream
140    ///
141    PrintStream error();
142
143    /// Close the context. The re-declaration of this method removes
144    /// the [IOException], which is never thrown.
145    ///
146    @Override
147    void close();
148}