1 package org.apache.maven.shared.invoker;
2
3 /*
4 * Licensed to the Apache Software Foundation (ASF) under one
5 * or more contributor license agreements. See the NOTICE file
6 * distributed with this work for additional information
7 * regarding copyright ownership. The ASF licenses this file
8 * to you under the Apache License, Version 2.0 (the
9 * "License"); you may not use this file except in compliance
10 * with the License. You may obtain a copy of the License at
11 *
12 * http://www.apache.org/licenses/LICENSE-2.0
13 *
14 * Unless required by applicable law or agreed to in writing,
15 * software distributed under the License is distributed on an
16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17 * KIND, either express or implied. See the License for the
18 * specific language governing permissions and limitations
19 * under the License.
20 */
21
22 import java.io.File;
23 import java.io.InputStream;
24 import java.util.List;
25 import java.util.Map;
26 import java.util.Properties;
27
28 /**
29 * Specifies the parameters used to control a Maven invocation.
30 *
31 * @version $Id: InvocationRequest.java 807415 2009-08-24 22:32:16Z olamy $
32 */
33 public interface InvocationRequest
34 {
35
36 // TODO: handle forced-reactor executions using -r/includes/excludes
37
38 /**
39 * Gets the interaction mode of the Maven invocation. By default, Maven is executed in batch mode.
40 *
41 * @return <code>true</code> if Maven should be executed in interactive mode, <code>false</code> if the batch
42 * mode is used.
43 */
44 boolean isInteractive();
45
46 /**
47 * Gets the network mode of the Maven invocation. By default, Maven is executed in online mode.
48 *
49 * @return <code>true</code> if Maven should be executed in offline mode, <code>false</code> if the online mode
50 * is used.
51 */
52 boolean isOffline();
53
54 /**
55 * Indicates whether Maven should enforce an update check for plugins and snapshots. By default, no update check is
56 * performed.
57 *
58 * @return <code>true</code> if plugins and snapshots should be updated, <code>false</code> otherwise.
59 */
60 boolean isUpdateSnapshots();
61
62 /**
63 * Gets the recursion behavior of a reactor invocation. By default, Maven will recursive the build into sub modules.
64 *
65 * @return <code>true</code> if sub modules should be build, <code>false</code> otherwise.
66 */
67 boolean isRecursive();
68
69 /**
70 * Gets whether Maven should search subdirectories to build a dynamic reactor
71 * @return <code>true</code> if we should search subdirectories, <code>false</code> otherwise
72 */
73 public boolean isActivatedReactor();
74
75 /**
76 * Gets the list of subdirectory patterns to search
77 * @return list of subdirectory patterns to search, or <code>null</code> in which case defaults should be used
78 */
79 public String[] getActivatedReactorIncludes();
80
81 /**
82 * Gets the list of subdirectory patterns to exclude from search
83 * @return list of subdirectory patterns to exclude search, or <code>null</code> in which case nothing should be excluded
84 */
85 public String[] getActivatedReactorExcludes();
86
87
88 /**
89 * Gets the debug mode of the Maven invocation. By default, Maven is executed in normal mode.
90 *
91 * @return <code>true</code> if Maven should be executed in debug mode, <code>false</code> if the normal mode
92 * should be used.
93 */
94 boolean isDebug();
95
96 /**
97 * Gets the exception output mode of the Maven invocation. By default, Maven will not print stack traces of build
98 * exceptions.
99 *
100 * @return <code>true</code> if Maven should print stack traces, <code>false</code> otherwise.
101 */
102 boolean isShowErrors();
103
104 /**
105 * Indicates whether the environment variables of the current process should be propagated to the Maven invocation.
106 * By default, the current environment variables are inherited by the new Maven invocation.
107 *
108 * @return <code>true</code> if the environment variables should be propagated, <code>false</code> otherwise.
109 */
110 boolean isShellEnvironmentInherited();
111
112 /**
113 * Indicates whether Maven should check for plugin updates. By default, plugin updates are not suppressed.
114 *
115 * @return <code>true</code> if plugin updates should be suppressed, <code>false</code> otherwise.
116 */
117 boolean isNonPluginUpdates();
118
119 /**
120 * Gets the failure mode of the Maven invocation. By default, the mode {@link #REACTOR_FAIL_FAST} is used.
121 *
122 * @return The failure mode, one of {@link #REACTOR_FAIL_FAST}, {@link #REACTOR_FAIL_AT_END} and
123 * {@link #REACTOR_FAIL_NEVER}.
124 */
125 String getFailureBehavior();
126
127 /**
128 * Gets the path to the base directory of the local repository to use for the Maven invocation.
129 *
130 * @param defaultDirectory The default location to use if no location is configured for this request, may be
131 * <code>null</code>.
132 * @return The path to the base directory of the local repository or <code>null</code> to use the location from
133 * the <code>settings.xml</code>.
134 */
135 File getLocalRepositoryDirectory( File defaultDirectory );
136
137 /**
138 * Gets the input stream used to provide input for the invoked Maven build. This is in particular useful when
139 * invoking Maven in interactive mode.
140 *
141 * @return The input stream used to provide input for the invoked Maven build or <code>null</code> if not set.
142 */
143 InputStream getInputStream( InputStream defaultStream );
144
145 /**
146 * Gets the handler used to capture the standard output from the Maven build.
147 *
148 * @return The output handler or <code>null</code> if not set.
149 */
150 InvocationOutputHandler getOutputHandler( InvocationOutputHandler defaultHandler );
151
152 /**
153 * Gets the handler used to capture the error output from the Maven build.
154 *
155 * @return The error handler or <code>null</code> if not set.
156 */
157 InvocationOutputHandler getErrorHandler( InvocationOutputHandler defaultHandler );
158
159 /**
160 * Gets the path to the POM for the Maven invocation. If no base directory is set, the parent directory of this POM
161 * will be used as the working directory for the Maven invocation.
162 *
163 * @return The path to the POM for the Maven invocation or <code>null</code> if not set.
164 */
165 File getPomFile();
166
167 /**
168 * Gets the (unqualified) filename of the POM for the Maven invocation. This setting is ignored if
169 * {@link #getPomFile()} does not return <code>null</code>. Otherwise, the base directory is assumed to contain a
170 * POM with this name. By default, a file named <code>pom.xml</code> is used.
171 *
172 * @return The (unqualified) filename of the POM for the Maven invocation or <code>null</code> if not set.
173 */
174 String getPomFileName();
175
176 /**
177 * Gets the path to the base directory of the POM for the Maven invocation. If {@link #getPomFile()} does not return
178 * <code>null</code>, this setting only affects the working directory for the Maven invocation.
179 *
180 * @return The path to the base directory of the POM or <code>null</code> if not set.
181 */
182 File getBaseDirectory();
183
184 /**
185 * Gets the path to the base directory of the POM for the Maven invocation. If {@link #getPomFile()} does not return
186 * <code>null</code>, this setting only affects the working directory for the Maven invocation.
187 *
188 * @param defaultDirectory The default base directory to use if none is configured for this request, may be
189 * <code>null</code>.
190 * @return The path to the base directory of the POM or <code>null</code> if not set.
191 */
192 File getBaseDirectory( File defaultDirectory );
193
194 /**
195 * Gets the path to the base directory of the Java installation used to run Maven.
196 *
197 * @return The path to the base directory of the Java installation used to run Maven or <code>null</code> to use
198 * the default Java home.
199 */
200 File getJavaHome();
201
202 /**
203 * Gets the system properties for the Maven invocation.
204 *
205 * @return The system properties for the Maven invocation or <code>null</code> if not set.
206 */
207 Properties getProperties();
208
209 /**
210 * Gets the goals for the Maven invocation.
211 *
212 * @return The goals for the Maven invocation or <code>null</code> if not set.
213 */
214 List getGoals();
215
216 /**
217 * Gets the path to the user settings for the Maven invocation.
218 *
219 * @return The path to the user settings for the Maven invocation or <code>null</code> to load the user settings
220 * from the default location.
221 */
222 File getUserSettingsFile();
223
224 /**
225 * Gets the checksum mode of the Maven invocation.
226 *
227 * @return The checksum mode, one of {@link #CHECKSUM_POLICY_WARN} and {@link #CHECKSUM_POLICY_FAIL}.
228 */
229 String getGlobalChecksumPolicy();
230
231 /**
232 * Gets the profiles for the Maven invocation.
233 *
234 * @return The profiles for the Maven invocation or <code>null</code> if not set.
235 */
236 List getProfiles();
237
238 /**
239 * Gets the environment variables for the Maven invocation.
240 *
241 * @return The environment variables for the Maven invocation or <code>null</code> if not set.
242 */
243 Map getShellEnvironments();
244
245 /**
246 * Gets the value of the <code>MAVEN_OPTS</code> environment variable.
247 *
248 * @return The value of the <code>MAVEN_OPTS</code> environment variable or <code>null</code> if not set.
249 */
250 String getMavenOpts();
251
252 /**
253 * The show version behaviour (-V option)
254 * @return The show version behaviour
255 * @since 2.0.11
256 */
257 boolean isShowVersion();
258
259 // ----------------------------------------------------------------------
260 // Reactor Failure Mode
261 // ----------------------------------------------------------------------
262
263 /**
264 * The failure mode "fail-fast" where the build is stopped by the first failure.
265 */
266 static final String REACTOR_FAIL_FAST = "fail-fast";
267
268 /**
269 * The failure mode "fail-at-end" where the build is only failed at its very end if necessary.
270 */
271 static final String REACTOR_FAIL_AT_END = "fail-at-end";
272
273 /**
274 * The failure mode "fail-never" in which Maven will always exit with code 0 regardless of build failures.
275 */
276 static final String REACTOR_FAIL_NEVER = "fail-never";
277
278 // ----------------------------------------------------------------------
279 // Artifact repository policies
280 // ----------------------------------------------------------------------
281
282 /**
283 * The strict checksum policy which fails the build if a corrupt artifact is detected.
284 */
285 static final String CHECKSUM_POLICY_FAIL = "fail";
286
287 /**
288 * The lax checksum policy which only outputs a warning if a corrupt artifact is detected.
289 */
290 static final String CHECKSUM_POLICY_WARN = "warn";
291
292 // ----------------------------------------------------------------------
293 //
294 // ----------------------------------------------------------------------
295
296 /**
297 * Sets the interaction mode of the Maven invocation.
298 *
299 * @param interactive <code>true</code> if Maven should be executed in interactive mode, <code>false</code> if
300 * the batch mode is used.
301 * @return This invocation request.
302 */
303 InvocationRequest setInteractive( boolean interactive );
304
305 /**
306 * Sets the network mode of the Maven invocation.
307 *
308 * @param offline <code>true</code> if Maven should be executed in offline mode, <code>false</code> if the
309 * online mode is used.
310 * @return This invocation request.
311 */
312 InvocationRequest setOffline( boolean offline );
313
314 /**
315 * Sets the debug mode of the Maven invocation.
316 *
317 * @param debug <code>true</code> if Maven should be executed in debug mode, <code>false</code> if the normal
318 * mode should be used.
319 * @return This invocation request.
320 */
321 InvocationRequest setDebug( boolean debug );
322
323 /**
324 * Sets the exception output mode of the Maven invocation.
325 *
326 * @param showErrors <code>true</code> if Maven should print stack traces, <code>false</code> otherwise.
327 * @return This invocation request.
328 */
329 InvocationRequest setShowErrors( boolean showErrors );
330
331 /**
332 * Specifies whether Maven should enforce an update check for plugins and snapshots.
333 *
334 * @param updateSnapshots <code>true</code> if plugins and snapshots should be updated, <code>false</code>
335 * otherwise.
336 * @return This invocation request.
337 */
338 InvocationRequest setUpdateSnapshots( boolean updateSnapshots );
339
340 /**
341 * Sets the failure mode of the Maven invocation.
342 *
343 * @param failureBehavior The failure mode, must be one of {@link #REACTOR_FAIL_FAST}, {@link #REACTOR_FAIL_AT_END}
344 * and {@link #REACTOR_FAIL_NEVER}.
345 * @return This invocation request.
346 */
347 InvocationRequest setFailureBehavior( String failureBehavior );
348
349 /**
350 * Dynamically constructs a reactor using the subdirectories of the current directory
351 * @param includes a list of filename patterns to include, or null, in which case the default is */pom.xml
352 * @param excludes a list of filename patterns to exclude, or null, in which case nothing is excluded
353 * @return This invocation request
354 */
355 InvocationRequest activateReactor( String[] includes, String[] excludes );
356
357 /**
358 * Sets the path to the base directory of the local repository to use for the Maven invocation.
359 *
360 * @param localRepository The path to the base directory of the local repository, may be <code>null</code>.
361 * @return This invocation request.
362 */
363 InvocationRequest setLocalRepositoryDirectory( File localRepository );
364
365 /**
366 * Sets the input stream used to provide input for the invoked Maven build. This is in particular useful when
367 * invoking Maven in interactive mode.
368 *
369 * @param inputStream The input stream used to provide input for the invoked Maven build, may be <code>null</code>
370 * if not required.
371 * @return This invocation request.
372 */
373 InvocationRequest setInputStream( InputStream inputStream );
374
375 /**
376 * Sets the handler used to capture the standard output from the Maven build.
377 *
378 * @param outputHandler The output handler, may be <code>null</code> if the output is not of interest.
379 * @return This invocation request.
380 */
381 InvocationRequest setOutputHandler( InvocationOutputHandler outputHandler );
382
383 /**
384 * Sets the handler used to capture the error output from the Maven build.
385 *
386 * @param errorHandler The error handler, may be <code>null</code> if the output is not of interest.
387 * @return This invocation request.
388 */
389 InvocationRequest setErrorHandler( InvocationOutputHandler errorHandler );
390
391 /**
392 * Sets the path to the POM for the Maven invocation. If no base directory is set, the parent directory of this POM
393 * will be used as the working directory for the Maven invocation.
394 *
395 * @param pomFile The path to the POM for the Maven invocation, may be <code>null</code> if not used.
396 * @return This invocation request.
397 */
398 InvocationRequest setPomFile( File pomFile );
399
400 /**
401 * Sets the (unqualified) filename of the POM for the Maven invocation. This setting is ignored if
402 * {@link #getPomFile()} does not return <code>null</code>. Otherwise, the base directory is assumed to contain a
403 * POM with this name.
404 *
405 * @param pomFilename The (unqualified) filename of the POM for the Maven invocation, may be <code>null</code> if
406 * not used.
407 * @return This invocation request.
408 */
409 InvocationRequest setPomFileName( String pomFilename );
410
411 /**
412 * Sets the path to the base directory of the POM for the Maven invocation. If {@link #getPomFile()} does not return
413 * <code>null</code>, this setting only affects the working directory for the Maven invocation.
414 *
415 * @param basedir The path to the base directory of the POM, may be <code>null</code> if not used.
416 * @return This invocation request.
417 */
418 InvocationRequest setBaseDirectory( File basedir );
419
420 /**
421 * Sets the path to the base directory of the Java installation used to run Maven.
422 *
423 * @param javaHome The path to the base directory of the Java installation used to run Maven, may be
424 * <code>null</code> to use the default Java home.
425 * @return This invocation request.
426 */
427 InvocationRequest setJavaHome( File javaHome );
428
429 /**
430 * Sets the system properties for the Maven invocation.
431 *
432 * @param properties The system properties for the Maven invocation, may be <code>null</code> if not set.
433 * @return This invocation request.
434 */
435 InvocationRequest setProperties( Properties properties );
436
437 /**
438 * Sets the goals for the Maven invocation.
439 *
440 * @param goals The goals for the Maven invocation, may be <code>null</code> to execute the POMs default goal.
441 * @return This invocation request.
442 */
443 InvocationRequest setGoals( List goals );
444
445 /**
446 * Sets the profiles for the Maven invocation.
447 *
448 * @param profiles The profiles for the Maven invocation, may be <code>null</code> to use the default profiles.
449 * @return This invocation request.
450 */
451 InvocationRequest setProfiles( List profiles );
452
453 /**
454 * Specifies whether the environment variables of the current process should be propagated to the Maven invocation.
455 *
456 * @param shellEnvironmentInherited <code>true</code> if the environment variables should be propagated,
457 * <code>false</code> otherwise.
458 * @return This invocation request.
459 */
460 InvocationRequest setShellEnvironmentInherited( boolean shellEnvironmentInherited );
461
462 /**
463 * Sets the path to the user settings for the Maven invocation.
464 *
465 * @param userSettings The path to the user settings for the Maven invocation, may be <code>null</code> to load
466 * the user settings from the default location.
467 * @return This invocation request.
468 */
469 InvocationRequest setUserSettingsFile( File userSettings );
470
471 /**
472 * Sets the checksum mode of the Maven invocation.
473 *
474 * @param globalChecksumPolicy The checksum mode, must be one of {@link #CHECKSUM_POLICY_WARN} and
475 * {@link #CHECKSUM_POLICY_FAIL}.
476 * @return This invocation request.
477 */
478 InvocationRequest setGlobalChecksumPolicy( String globalChecksumPolicy );
479
480 /**
481 * Specifies whether Maven should check for plugin updates.
482 *
483 * @param nonPluginUpdates <code>true</code> if plugin updates should be suppressed, <code>false</code>
484 * otherwise.
485 * @return This invocation request.
486 */
487 InvocationRequest setNonPluginUpdates( boolean nonPluginUpdates );
488
489 /**
490 * Sets the recursion behavior of a reactor invocation.
491 *
492 * @param recursive <code>true</code> if sub modules should be build, <code>false</code> otherwise.
493 * @return This invocation request.
494 */
495 InvocationRequest setRecursive( boolean recursive );
496
497 /**
498 * Adds the specified environment variable to the Maven invocation.
499 *
500 * @param name The name of the environment variable, must not be <code>null</code>.
501 * @param value The value of the environment variable, must not be <code>null</code>.
502 * @return This invocation request.
503 */
504 InvocationRequest addShellEnvironment( String name, String value );
505
506 /**
507 * Sets the value of the <code>MAVEN_OPTS</code> environment variable.
508 *
509 * @param mavenOpts The value of the <code>MAVEN_OPTS</code> environment variable, may be <code>null</code> to
510 * use the default options.
511 * @return This invocation request.
512 */
513 InvocationRequest setMavenOpts( String mavenOpts );
514
515 /**
516 * enable displaying version without stopping the build (-V cli option)
517 * @param showVersion enable displaying version
518 * @since 2.0.11
519 * @return This invocation request.
520 */
521 InvocationRequest setShowVersion( boolean showVersion );
522
523 }