InvokerRequest.java

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 */
package org.apache.maven.api.cli;

import java.io.InputStream;
import java.io.OutputStream;
import java.nio.file.Path;
import java.util.List;
import java.util.Map;
import java.util.Optional;

import org.apache.maven.api.annotations.Experimental;
import org.apache.maven.api.annotations.Immutable;
import org.apache.maven.api.annotations.Nonnull;
import org.apache.maven.api.cli.cisupport.CIInfo;
import org.apache.maven.api.services.Lookup;
import org.apache.maven.api.services.MessageBuilderFactory;

/**
 * Represents a Maven invocation request, encapsulating all necessary information
 * for invoking a Maven build or command. Arguments are parsed and exposed via methods.
 *
 * @since 4.0.0
 */
@Immutable
@Experimental
public interface InvokerRequest {
    /**
     * The parser request this instance was created from.
     */
    @Nonnull
    ParserRequest parserRequest();

    /**
     * Flag representing parser processing result: if there were some fatal errors during
     * {@link Parser#parseInvocation(ParserRequest)} this method will return {@code true} and invoker should
     * handle this request as "early failure". In these cases, {@link #options()} usually is absent.
     */
    boolean parsingFailed();

    /**
     * Returns {@code true} if this call happens in "embedded" mode.
     *
     * @see ParserRequest#embedded()
     */
    default boolean embedded() {
        return parserRequest().embedded();
    }

    /**
     * Returns the current working directory for the Maven execution.
     * This is typically the directory from which Maven was invoked.
     *
     * @return the current working directory path
     */
    @Nonnull
    Path cwd();

    /**
     * Returns the Maven installation directory.
     * This is usually set by the Maven launcher script using the "maven.home" system property.
     *
     * @return the Maven installation directory path
     */
    @Nonnull
    Path installationDirectory();

    /**
     * Returns the user's home directory.
     * This is typically obtained from the "user.home" system property.
     *
     * @return the user's home directory path
     */
    @Nonnull
    Path userHomeDirectory();

    /**
     * Shorthand for {@link MessageBuilderFactory}.
     */
    default MessageBuilderFactory messageBuilderFactory() {
        return parserRequest().messageBuilderFactory();
    }

    /**
     * Shorthand for {@link Lookup}.
     */
    default Lookup lookup() {
        return parserRequest().lookup();
    }

    /**
     * Returns a map of user-defined properties for the Maven execution.
     * These properties can be set using the -D command-line option.
     *
     * @return an unmodifiable map of user properties
     */
    @Nonnull
    Map<String, String> userProperties();

    /**
     * Returns a map of system properties for the Maven execution.
     * These include both Java system properties and Maven-specific system properties.
     *
     * @return an unmodifiable map of system properties
     */
    @Nonnull
    Map<String, String> systemProperties();

    /**
     * Returns the top-level directory of the Maven invocation.
     * This is typically the directory containing the POM file being executed.
     *
     * @return the top-level directory path
     */
    @Nonnull
    Path topDirectory();

    /**
     * Returns the root directory of the Maven invocation, if found. This is determined by the presence of a
     * {@code .mvn} directory or a POM with the root="true" property but is not always applicable (ie invocation
     * from outside a checkout).
     *
     * @return the root directory path, if present
     */
    @Nonnull
    Optional<Path> rootDirectory();

    /**
     * Returns the input stream for the Maven execution, if running in embedded mode.
     *
     * @return an {@link Optional} containing the input stream, or empty if not applicable
     */
    @Nonnull
    default Optional<InputStream> stdIn() {
        return Optional.ofNullable(parserRequest().stdIn());
    }

    /**
     * Returns the output stream for the Maven execution, if running in embedded mode.
     *
     * @return an {@link Optional} containing the output stream, or empty if not applicable
     */
    @Nonnull
    default Optional<OutputStream> stdOut() {
        return Optional.ofNullable(parserRequest().stdOut());
    }

    /**
     * Returns the error stream for the Maven execution, if running in embedded mode.
     *
     * @return an {@link Optional} containing the error stream, or empty if not applicable
     */
    @Nonnull
    default Optional<OutputStream> stdErr() {
        return Optional.ofNullable(parserRequest().stdErr());
    }

    /**
     * Returns a list of core extensions from all sources, that were discovered and loaded. Each instance of
     * {@link CoreExtensions} is validated, but the list elements may have overlapping elements, that requires
     * some logic to sort out (like precedence).
     * <p>
     * The list of {@link CoreExtensions} if present, is in precedence order.
     *
     * @return an {@link Optional} containing the {@link CoreExtensions}, or empty if not configured
     */
    @Nonnull
    Optional<List<CoreExtensions>> coreExtensions();

    /**
     * Returns detected CI system, if any.
     *
     * @return an {@link Optional} containing the {@link CIInfo} collected from CI system. or empty if CI not
     * detected.
     */
    @Nonnull
    Optional<CIInfo> ciInfo();

    /**
     * Returns the options associated with this invocation request.
     *
     * @return the options optional. It will be absent if {@link #parsingFailed()} return {@code true}.
     */
    @Nonnull
    Optional<Options> options();

    /**
     * This method returns "verbose" option value derived from multiple places: CLI options, but also CI detection,
     * if applicable.
     */
    default boolean effectiveVerbose() {
        return options().isPresent() && options().orElseThrow().verbose().orElse(false)
                || ciInfo().isPresent() && ciInfo().orElseThrow().isVerbose();
    }
}