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