1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one
3 * or more contributor license agreements. See the NOTICE file
4 * distributed with this work for additional information
5 * regarding copyright ownership. The ASF licenses this file
6 * to you under the Apache License, Version 2.0 (the
7 * "License"); you may not use this file except in compliance
8 * with the License. You may obtain a copy of the License at
9 *
10 * http://www.apache.org/licenses/LICENSE-2.0
11 *
12 * Unless required by applicable law or agreed to in writing,
13 * software distributed under the License is distributed on an
14 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15 * KIND, either express or implied. See the License for the
16 * specific language governing permissions and limitations
17 * under the License.
18 */
19 package org.apache.maven.api.cli;
20
21 import java.io.InputStream;
22 import java.io.OutputStream;
23 import java.nio.file.Path;
24 import java.util.List;
25 import java.util.Map;
26 import java.util.Optional;
27
28 import org.apache.maven.api.annotations.Experimental;
29 import org.apache.maven.api.annotations.Immutable;
30 import org.apache.maven.api.annotations.Nonnull;
31 import org.apache.maven.api.cli.extensions.CoreExtension;
32 import org.apache.maven.api.services.Lookup;
33 import org.apache.maven.api.services.MessageBuilderFactory;
34
35 /**
36 * Represents a Maven invocation request, encapsulating all necessary information
37 * for invoking a Maven build or command. Arguments are parsed and exposed via methods.
38 *
39 * @since 4.0.0
40 */
41 @Immutable
42 @Experimental
43 public interface InvokerRequest {
44 /**
45 * The parser request this instance was created from.
46 */
47 @Nonnull
48 ParserRequest parserRequest();
49
50 /**
51 * Returns the current working directory for the Maven execution.
52 * This is typically the directory from which Maven was invoked.
53 *
54 * @return the current working directory path
55 */
56 @Nonnull
57 Path cwd();
58
59 /**
60 * Returns the Maven installation directory.
61 * This is usually set by the Maven launcher script using the "maven.home" system property.
62 *
63 * @return the Maven installation directory path
64 */
65 @Nonnull
66 Path installationDirectory();
67
68 /**
69 * Returns the user's home directory.
70 * This is typically obtained from the "user.home" system property.
71 *
72 * @return the user's home directory path
73 */
74 @Nonnull
75 Path userHomeDirectory();
76
77 /**
78 * Returns the list of extra JVM arguments to be passed to the forked process.
79 * These arguments allow for customization of the JVM environment in which tool will run.
80 * This property is used ONLY by executors and invokers that spawn a new JVM.
81 *
82 * @return an Optional containing the list of extra JVM arguments, or empty if not specified
83 */
84 @Nonnull
85 Optional<List<String>> jvmArguments();
86
87 /**
88 * Shorthand for {@link Logger} to use.
89 */
90 default Logger logger() {
91 return parserRequest().logger();
92 }
93
94 /**
95 * Shorthand for {@link MessageBuilderFactory}.
96 */
97 default MessageBuilderFactory messageBuilderFactory() {
98 return parserRequest().messageBuilderFactory();
99 }
100
101 /**
102 * Shorthand for {@link Lookup}.
103 */
104 default Lookup lookup() {
105 return parserRequest().lookup();
106 }
107
108 /**
109 * Returns a map of user-defined properties for the Maven execution.
110 * These properties can be set using the -D command-line option.
111 *
112 * @return an unmodifiable map of user properties
113 */
114 @Nonnull
115 Map<String, String> userProperties();
116
117 /**
118 * Returns a map of system properties for the Maven execution.
119 * These include both Java system properties and Maven-specific system properties.
120 *
121 * @return an unmodifiable map of system properties
122 */
123 @Nonnull
124 Map<String, String> systemProperties();
125
126 /**
127 * Returns the top-level directory of the Maven invocation.
128 * This is typically the directory containing the POM file being executed.
129 *
130 * @return the top-level directory path
131 */
132 @Nonnull
133 Path topDirectory();
134
135 /**
136 * Returns the root directory of the Maven invocation, if found. This is determined by the presence of a
137 * {@code .mvn} directory or a POM with the root="true" property but is not always applicable (ie invocation
138 * from outside a checkout).
139 *
140 * @return the root directory path, if present
141 */
142 @Nonnull
143 Optional<Path> rootDirectory();
144
145 /**
146 * Returns the input stream for the Maven execution, if running in embedded mode.
147 *
148 * @return an {@link Optional} containing the input stream, or empty if not applicable
149 */
150 @Nonnull
151 Optional<InputStream> in();
152
153 /**
154 * Returns the output stream for the Maven execution, if running in embedded mode.
155 *
156 * @return an {@link Optional} containing the output stream, or empty if not applicable
157 */
158 @Nonnull
159 Optional<OutputStream> out();
160
161 /**
162 * Returns the error stream for the Maven execution, if running in embedded mode.
163 *
164 * @return an {@link Optional} containing the error stream, or empty if not applicable
165 */
166 @Nonnull
167 Optional<OutputStream> err();
168
169 /**
170 * Returns a list of core extensions, if configured in the .mvn/extensions.xml file.
171 *
172 * @return an {@link Optional} containing the list of core extensions, or empty if not configured
173 */
174 @Nonnull
175 Optional<List<CoreExtension>> coreExtensions();
176
177 /**
178 * Returns the options associated with this invocation request.
179 *
180 * @return the options object
181 */
182 @Nonnull
183 Options options();
184 }