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 1395369 2012-10-07 19:14:10Z rfscholte $
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 * A list of specified reactor projects to build instead of all projects.
89 * A project can be specified by [groupId]:artifactId or by its relative path.
90 *
91 * @return the list of projects to add to reactor build, otherwise {@code null}
92 * @since 2.1
93 */
94 public List<String> getProjects();
95
96 /**
97 * Get the value of the {@code also-make} argument.
98 *
99 * @return {@code true} if the argument {@code also-make} was specified, otherwise {@code false}
100 * @since 2.1
101 */
102 boolean isAlsoMake();
103
104 /**
105 * Get the value of the {@code also-make-dependents}
106 *
107 * @return {@code true} if the argument {@code also-make-dependents} was specified, otherwise {@code false}
108 * @since 2.1
109 */
110 boolean isAlsoMakeDependents();
111
112 /**
113 * Get the value of {@code resume-from}
114 *
115 * @return specified reactor project to resume from
116 * @since 2.1
117 */
118 String getResumeFrom();
119
120 /**
121 * Gets the debug mode of the Maven invocation. By default, Maven is executed in normal mode.
122 *
123 * @return <code>true</code> if Maven should be executed in debug mode, <code>false</code> if the normal mode
124 * should be used.
125 */
126 boolean isDebug();
127
128 /**
129 * Gets the exception output mode of the Maven invocation. By default, Maven will not print stack traces of build
130 * exceptions.
131 *
132 * @return <code>true</code> if Maven should print stack traces, <code>false</code> otherwise.
133 */
134 boolean isShowErrors();
135
136 /**
137 * Indicates whether the environment variables of the current process should be propagated to the Maven invocation.
138 * By default, the current environment variables are inherited by the new Maven invocation.
139 *
140 * @return <code>true</code> if the environment variables should be propagated, <code>false</code> otherwise.
141 */
142 boolean isShellEnvironmentInherited();
143
144 /**
145 * Indicates whether Maven should check for plugin updates. By default, plugin updates are not suppressed.
146 *
147 * @return <code>true</code> if plugin updates should be suppressed, <code>false</code> otherwise.
148 */
149 boolean isNonPluginUpdates();
150
151 /**
152 * Gets the failure mode of the Maven invocation. By default, the mode {@link #REACTOR_FAIL_FAST} is used.
153 *
154 * @return The failure mode, one of {@link #REACTOR_FAIL_FAST}, {@link #REACTOR_FAIL_AT_END} and
155 * {@link #REACTOR_FAIL_NEVER}.
156 */
157 String getFailureBehavior();
158
159 /**
160 * Gets the path to the base directory of the local repository to use for the Maven invocation.
161 *
162 * @param defaultDirectory The default location to use if no location is configured for this request, may be
163 * <code>null</code>.
164 * @return The path to the base directory of the local repository or <code>null</code> to use the location from
165 * the <code>settings.xml</code>.
166 */
167 File getLocalRepositoryDirectory( File defaultDirectory );
168
169 /**
170 * Gets the input stream used to provide input for the invoked Maven build. This is in particular useful when
171 * invoking Maven in interactive mode.
172 *
173 * @return The input stream used to provide input for the invoked Maven build or <code>null</code> if not set.
174 */
175 InputStream getInputStream( InputStream defaultStream );
176
177 /**
178 * Gets the handler used to capture the standard output from the Maven build.
179 *
180 * @return The output handler or <code>null</code> if not set.
181 */
182 InvocationOutputHandler getOutputHandler( InvocationOutputHandler defaultHandler );
183
184 /**
185 * Gets the handler used to capture the error output from the Maven build.
186 *
187 * @return The error handler or <code>null</code> if not set.
188 */
189 InvocationOutputHandler getErrorHandler( InvocationOutputHandler defaultHandler );
190
191 /**
192 * Gets the path to the POM for the Maven invocation. If no base directory is set, the parent directory of this POM
193 * will be used as the working directory for the Maven invocation.
194 *
195 * @return The path to the POM for the Maven invocation or <code>null</code> if not set.
196 */
197 File getPomFile();
198
199 /**
200 * Gets the (unqualified) filename of the POM for the Maven invocation. This setting is ignored if
201 * {@link #getPomFile()} does not return <code>null</code>. Otherwise, the base directory is assumed to contain a
202 * POM with this name. By default, a file named <code>pom.xml</code> is used.
203 *
204 * @return The (unqualified) filename of the POM for the Maven invocation or <code>null</code> if not set.
205 */
206 String getPomFileName();
207
208 /**
209 * Gets the path to the base directory of the POM for the Maven invocation. If {@link #getPomFile()} does not return
210 * <code>null</code>, this setting only affects the working directory for the Maven invocation.
211 *
212 * @return The path to the base directory of the POM or <code>null</code> if not set.
213 */
214 File getBaseDirectory();
215
216 /**
217 * Gets the path to the base directory of the POM for the Maven invocation. If {@link #getPomFile()} does not return
218 * <code>null</code>, this setting only affects the working directory for the Maven invocation.
219 *
220 * @param defaultDirectory The default base directory to use if none is configured for this request, may be
221 * <code>null</code>.
222 * @return The path to the base directory of the POM or <code>null</code> if not set.
223 */
224 File getBaseDirectory( File defaultDirectory );
225
226 /**
227 * Gets the path to the base directory of the Java installation used to run Maven.
228 *
229 * @return The path to the base directory of the Java installation used to run Maven or <code>null</code> to use
230 * the default Java home.
231 */
232 File getJavaHome();
233
234 /**
235 * Gets the system properties for the Maven invocation.
236 *
237 * @return The system properties for the Maven invocation or <code>null</code> if not set.
238 */
239 Properties getProperties();
240
241 /**
242 * Gets the goals for the Maven invocation.
243 *
244 * @return The goals for the Maven invocation or <code>null</code> if not set.
245 */
246 List<String> getGoals();
247
248 /**
249 * Gets the path to the user settings for the Maven invocation.
250 *
251 * @return The path to the user settings for the Maven invocation or <code>null</code> to load the user settings
252 * from the default location.
253 */
254 File getUserSettingsFile();
255
256 /**
257 * Gets the path to the global settings for the Maven invocation.
258 *
259 * @return The path to the global settings for the Maven invocation or <code>null</code> to load the global settings
260 * from the default location.
261 * @since 2.1
262 */
263 File getGlobalSettingsFile();
264
265 /**
266 * Gets the path to the custom toolchains file
267 *
268 * @return The path to the custom toolchains file or <code>null</code> to load the toolchains from the default location
269 * @since 2.1
270 */
271 File getToolchainsFile();
272
273 /**
274 * Gets the checksum mode of the Maven invocation.
275 *
276 * @return The checksum mode, one of {@link #CHECKSUM_POLICY_WARN} and {@link #CHECKSUM_POLICY_FAIL}.
277 */
278 String getGlobalChecksumPolicy();
279
280 /**
281 * Gets the profiles for the Maven invocation.
282 *
283 * @return The profiles for the Maven invocation or <code>null</code> if not set.
284 */
285 List<String> getProfiles();
286
287 /**
288 * Gets the environment variables for the Maven invocation.
289 *
290 * @return The environment variables for the Maven invocation or <code>null</code> if not set.
291 */
292 Map<String, String> getShellEnvironments();
293
294 /**
295 * Gets the value of the <code>MAVEN_OPTS</code> environment variable.
296 *
297 * @return The value of the <code>MAVEN_OPTS</code> environment variable or <code>null</code> if not set.
298 */
299 String getMavenOpts();
300
301 /**
302 * The show version behaviour (-V option)
303 * @return The show version behaviour
304 * @since 2.0.11
305 */
306 boolean isShowVersion();
307
308 /**
309 * Get the value of the {@code threads} argument.
310 *
311 * @return the value of the {@code threads} argument or {@code null} if not set
312 * @since 2.1
313 */
314 String getThreads();
315
316 // ----------------------------------------------------------------------
317 // Reactor Failure Mode
318 // ----------------------------------------------------------------------
319
320 /**
321 * The failure mode "fail-fast" where the build is stopped by the first failure.
322 */
323 static final String REACTOR_FAIL_FAST = "fail-fast";
324
325 /**
326 * The failure mode "fail-at-end" where the build is only failed at its very end if necessary.
327 */
328 static final String REACTOR_FAIL_AT_END = "fail-at-end";
329
330 /**
331 * The failure mode "fail-never" in which Maven will always exit with code 0 regardless of build failures.
332 */
333 static final String REACTOR_FAIL_NEVER = "fail-never";
334
335 // ----------------------------------------------------------------------
336 // Artifact repository policies
337 // ----------------------------------------------------------------------
338
339 /**
340 * The strict checksum policy which fails the build if a corrupt artifact is detected.
341 */
342 static final String CHECKSUM_POLICY_FAIL = "fail";
343
344 /**
345 * The lax checksum policy which only outputs a warning if a corrupt artifact is detected.
346 */
347 static final String CHECKSUM_POLICY_WARN = "warn";
348
349 // ----------------------------------------------------------------------
350 //
351 // ----------------------------------------------------------------------
352
353 /**
354 * Sets the interaction mode of the Maven invocation.
355 * <em>Inverse</em> equivalent of {@code -B} and {@code --batch-mode}
356 *
357 * @param interactive <code>true</code> if Maven should be executed in interactive mode, <code>false</code> if
358 * the batch mode is used.
359 * @return This invocation request.
360 */
361 InvocationRequest setInteractive( boolean interactive );
362
363 /**
364 * Sets the network mode of the Maven invocation.
365 * Equivalent of {@code -o} and {@code --offline}
366 *
367 * @param offline <code>true</code> if Maven should be executed in offline mode, <code>false</code> if the
368 * online mode is used.
369 * @return This invocation request.
370 */
371 InvocationRequest setOffline( boolean offline );
372
373 /**
374 * Sets the debug mode of the Maven invocation.
375 * Equivalent of {@code -X} and {@code --debug}
376 *
377 * @param debug <code>true</code> if Maven should be executed in debug mode, <code>false</code> if the normal
378 * mode should be used.
379 * @return This invocation request.
380 */
381 InvocationRequest setDebug( boolean debug );
382
383 /**
384 * Sets the exception output mode of the Maven invocation.
385 * Equivalent of {@code -e} and {@code --errors}
386 *
387 * @param showErrors <code>true</code> if Maven should print stack traces, <code>false</code> otherwise.
388 * @return This invocation request.
389 */
390 InvocationRequest setShowErrors( boolean showErrors );
391
392 /**
393 * Specifies whether Maven should enforce an update check for plugins and snapshots.
394 * Equivalent of {@code -U} and {@code --update-snapshots}
395 *
396 * @param updateSnapshots <code>true</code> if plugins and snapshots should be updated, <code>false</code>
397 * otherwise.
398 * @return This invocation request.
399 */
400 InvocationRequest setUpdateSnapshots( boolean updateSnapshots );
401
402 /**
403 * Sets the failure mode of the Maven invocation.
404 * Equivalent of {@code -ff} and {@code --fail-fast}, {@code -fae} and {@code --fail-at-end}, {@code -fn} and {@code --fail-never}
405 *
406 * @param failureBehavior The failure mode, must be one of {@link #REACTOR_FAIL_FAST}, {@link #REACTOR_FAIL_AT_END}
407 * and {@link #REACTOR_FAIL_NEVER}.
408 * @return This invocation request.
409 */
410 InvocationRequest setFailureBehavior( String failureBehavior );
411
412 /**
413 * Dynamically constructs a reactor using the subdirectories of the current directory
414 * @param includes a list of filename patterns to include, or null, in which case the default is */pom.xml
415 * @param excludes a list of filename patterns to exclude, or null, in which case nothing is excluded
416 * @return This invocation request
417 */
418 InvocationRequest activateReactor( String[] includes, String[] excludes );
419
420 /**
421 * Sets the path to the base directory of the local repository to use for the Maven invocation.
422 *
423 * @param localRepository The path to the base directory of the local repository, may be <code>null</code>.
424 * @return This invocation request.
425 */
426 InvocationRequest setLocalRepositoryDirectory( File localRepository );
427
428 /**
429 * Sets the input stream used to provide input for the invoked Maven build. This is in particular useful when
430 * invoking Maven in interactive mode.
431 *
432 * @param inputStream The input stream used to provide input for the invoked Maven build, may be <code>null</code>
433 * if not required.
434 * @return This invocation request.
435 */
436 InvocationRequest setInputStream( InputStream inputStream );
437
438 /**
439 * Sets the handler used to capture the standard output from the Maven build.
440 *
441 * @param outputHandler The output handler, may be <code>null</code> if the output is not of interest.
442 * @return This invocation request.
443 */
444 InvocationRequest setOutputHandler( InvocationOutputHandler outputHandler );
445
446 /**
447 * Sets the handler used to capture the error output from the Maven build.
448 *
449 * @param errorHandler The error handler, may be <code>null</code> if the output is not of interest.
450 * @return This invocation request.
451 */
452 InvocationRequest setErrorHandler( InvocationOutputHandler errorHandler );
453
454 /**
455 * Sets the path to the POM for the Maven invocation. If no base directory is set, the parent directory of this POM
456 * will be used as the working directory for the Maven invocation.
457 *
458 * @param pomFile The path to the POM for the Maven invocation, may be <code>null</code> if not used.
459 * @return This invocation request.
460 */
461 InvocationRequest setPomFile( File pomFile );
462
463 /**
464 * Sets the (unqualified) filename of the POM for the Maven invocation. This setting is ignored if
465 * {@link #getPomFile()} does not return <code>null</code>. Otherwise, the base directory is assumed to contain a
466 * POM with this name.
467 *
468 * @param pomFilename The (unqualified) filename of the POM for the Maven invocation, may be <code>null</code> if
469 * not used.
470 * @return This invocation request.
471 */
472 InvocationRequest setPomFileName( String pomFilename );
473
474 /**
475 * Sets the path to the base directory of the POM for the Maven invocation. If {@link #getPomFile()} does not return
476 * <code>null</code>, this setting only affects the working directory for the Maven invocation.
477 *
478 * @param basedir The path to the base directory of the POM, may be <code>null</code> if not used.
479 * @return This invocation request.
480 */
481 InvocationRequest setBaseDirectory( File basedir );
482
483 /**
484 * Sets the path to the base directory of the Java installation used to run Maven.
485 *
486 * @param javaHome The path to the base directory of the Java installation used to run Maven, may be
487 * <code>null</code> to use the default Java home.
488 * @return This invocation request.
489 */
490 InvocationRequest setJavaHome( File javaHome );
491
492 /**
493 * Sets the system properties for the Maven invocation.
494 *
495 * @param properties The system properties for the Maven invocation, may be <code>null</code> if not set.
496 * @return This invocation request.
497 */
498 InvocationRequest setProperties( Properties properties );
499
500 /**
501 * Sets the goals for the Maven invocation.
502 *
503 * @param goals The goals for the Maven invocation, may be <code>null</code> to execute the POMs default goal.
504 * @return This invocation request.
505 */
506 InvocationRequest setGoals( List<String> goals );
507
508 /**
509 * Sets the profiles for the Maven invocation.
510 * Equivalent of {@code -P} and {@code --active-profiles}
511 *
512 * @param profiles The profiles for the Maven invocation, may be <code>null</code> to use the default profiles.
513 * @return This invocation request.
514 */
515 InvocationRequest setProfiles( List<String> profiles );
516
517 /**
518 * Specifies whether the environment variables of the current process should be propagated to the Maven invocation.
519 *
520 * @param shellEnvironmentInherited <code>true</code> if the environment variables should be propagated,
521 * <code>false</code> otherwise.
522 * @return This invocation request.
523 */
524 InvocationRequest setShellEnvironmentInherited( boolean shellEnvironmentInherited );
525
526 /**
527 * Sets the path to the user settings for the Maven invocation.
528 * Equivalent of {@code -s} and {@code --settings}
529 *
530 * @param userSettings The path to the user settings for the Maven invocation, may be <code>null</code> to load
531 * the user settings from the default location.
532 * @return This invocation request.
533 */
534 InvocationRequest setUserSettingsFile( File userSettings );
535
536 /**
537 * Sets the path to the global settings for the Maven invocation.
538 * Equivalent of {@code -gs} and {@code --global-settings}
539 *
540 * @param globalSettings The path to the global settings for the Maven invocation, may be <code>null</code> to load
541 * the global settings from the default location.
542 * @return This invocation request.
543 * @since 2.1
544 */
545 InvocationRequest setGlobalSettingsFile( File globalSettings );
546
547 /**
548 * Sets the alternate path for the user toolchains file
549 * Equivalent of {@code -t} or {@code --toolchains}
550 * <p>
551 * <strong>note: </strong>available since Maven3
552 * </p>
553 *
554 * @param toolchains the alternate path for the user toolchains file
555 * @return This invocation request
556 * @since 2.1
557 */
558 InvocationRequest setToolchainsFile( File toolchains );
559 /**
560 * Sets the checksum mode of the Maven invocation.
561 * Equivalent of {@code -c} or {@code --lax-checksums}, {@code -C} or {@code --strict-checksums}
562 *
563 * @param globalChecksumPolicy The checksum mode, must be one of {@link #CHECKSUM_POLICY_WARN} and
564 * {@link #CHECKSUM_POLICY_FAIL}.
565 * @return This invocation request.
566 */
567 InvocationRequest setGlobalChecksumPolicy( String globalChecksumPolicy );
568
569 /**
570 * Specifies whether Maven should check for plugin updates.
571 * <p>
572 * Equivalent of {@code -npu} or {@code --no-plugin-updates}<br/>
573 * <strong>note: </strong>Ineffective with Maven3, only kept for backward compatibility
574 * </p>
575 * @param nonPluginUpdates <code>true</code> if plugin updates should be suppressed, <code>false</code>
576 * otherwise.
577 * @return This invocation request.
578 */
579 InvocationRequest setNonPluginUpdates( boolean nonPluginUpdates );
580
581 /**
582 * Sets the recursion behavior of a reactor invocation.
583 * <em>Inverse</em> equivalent of {@code -N} and {@code --non-recursive}
584 *
585 * @param recursive <code>true</code> if sub modules should be build, <code>false</code> otherwise.
586 * @return This invocation request.
587 */
588 InvocationRequest setRecursive( boolean recursive );
589
590 /**
591 * Adds the specified environment variable to the Maven invocation.
592 *
593 * @param name The name of the environment variable, must not be <code>null</code>.
594 * @param value The value of the environment variable, must not be <code>null</code>.
595 * @return This invocation request.
596 */
597 InvocationRequest addShellEnvironment( String name, String value );
598
599 /**
600 * Sets the value of the <code>MAVEN_OPTS</code> environment variable.
601 *
602 * @param mavenOpts The value of the <code>MAVEN_OPTS</code> environment variable, may be <code>null</code> to
603 * use the default options.
604 * @return This invocation request.
605 */
606 InvocationRequest setMavenOpts( String mavenOpts );
607
608 /**
609 * enable displaying version without stopping the build
610 * Equivalent of {@code -V} or {@code --show-version}
611 *
612 * @param showVersion enable displaying version
613 * @return This invocation request.
614 * @since 2.0.11
615 */
616 InvocationRequest setShowVersion( boolean showVersion );
617
618 /**
619 * Thread count, for instance 2.0C where C is core multiplied
620 * Equivalent of {@code -T} or {@code --threads}
621 * <p>
622 * <strong>note: </strong>available since Maven3
623 * </p>
624 *
625 * @param threads the threadcount
626 * @return This invocation request.
627 * @since 2.1
628 */
629 InvocationRequest setThreads( String threads );
630
631 /**
632 * Sets the reactor project list.
633 * Equivalent of {@code -P} or {@code --projects}
634 *
635 * @param projects the reactor project list
636 * @return This invocation request.
637 * @since 2.1
638 */
639 InvocationRequest setProjects( List<String> projects );
640
641 /**
642 * Enable the 'also make' mode.
643 * Equivalent of {@code -am} or {@code --also-make}
644 *
645 * @param alsoMake enable 'also make' mode
646 * @return This invocation request.
647 * @since 2.1
648 */
649 InvocationRequest setAlsoMake( boolean alsoMake );
650
651 /**
652 * Enable the 'also make dependents' mode.
653 * Equivalent of {@code -amd} or {@code --also-make-dependents}
654 *
655 * @param alsoMake enable 'also make' mode
656 * @return This invocation request.
657 * @since 2.1
658 */
659 InvocationRequest setAlsoMakeDependents( boolean alsoMakeDependents );
660
661 /**
662 * Resume reactor from specified project.
663 * Equivalent of {@code -rf} or {@code --resume-from}
664 *
665 * @param resumeFrom set the project to resume from
666 * @return This invocation request
667 * @since 2.1
668 */
669 InvocationRequest setResumeFrom( String resumeFrom );
670
671 }