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 }