javadoc: improve description of systemPropertyVariables and

systemPropertiesFile clarify order of precedence
apache · Jul 9, 2024 · cd72eaa · cd72eaa
1 parent 43f0980
commit cd72eaa
Show file tree

Hide file tree

Showing 3 changed files with 22 additions and 1 deletion.
diff --git a/...n-failsafe-plugin/src/main/java/org/apache/maven/plugin/failsafe/IntegrationTestMojo.java b/...n-failsafe-plugin/src/main/java/org/apache/maven/plugin/failsafe/IntegrationTestMojo.java
@@ -525,6 +525,11 @@ public class IntegrationTestMojo extends AbstractSurefireMojo {
  @Parameter(property = "failsafe.enableProcessChecker")
  private String enableProcessChecker;
 
+ /**
+ * Properties file being used as system properties passed to the provider.
+ *
+ * @see AbstractSurefireMojo#systemPropertyVariables {@code systemPropertyVariables} for how the effective provider properties are calculated
+ */
  @Parameter(property = "failsafe.systemPropertiesFile")
  private File systemPropertiesFile;
 

diff --git a/...-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java b/...-surefire-common/src/main/java/org/apache/maven/plugin/surefire/AbstractSurefireMojo.java
@@ -314,16 +314,27 @@ public abstract class AbstractSurefireMojo extends AbstractMojo implements Suref
  /**
  * List of System properties to pass to a provider.
  *
- * @deprecated Use systemPropertyVariables instead.
+ * @deprecated Use {@link #systemPropertyVariables} instead.
+ * @see #systemPropertyVariables {@code systemPropertyVariables} for how the effective provider properties are calculated
  */
  @Deprecated
  @Parameter
  private Properties systemProperties;
 
  /**
  * List of System properties to pass to a provider.
+ * The effective system properties given to a provider are contributed from several sources:
+ * <ol>
+ * <li>{@link #systemProperties}</li>
+ * <li>{@link AbstractSurefireMojo#getSystemPropertiesFile()} (set via parameter {@code systemPropertiesFile} on some goals)</li>
+ * <li>{@link #systemPropertyVariables}</li>
+ * <li>User properties from {@link MavenSession#getUserProperties()}, usually set via CLI options given with {@code -D}</li>
+ * </ol>
+ * Later sources may overwrite same named properties from earlier sources, that means for example that one cannot overwrite user properties with either
+ * {@link #systemProperties}, {@link AbstractSurefireMojo#getSystemPropertiesFile()} or {@link #systemPropertyVariables}.
  *
  * @since 2.5
+ * @see #systemProperties
  */
  @Parameter
  private Map<String, String> systemPropertyVariables;

diff --git a/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java b/maven-surefire-plugin/src/main/java/org/apache/maven/plugin/surefire/SurefirePlugin.java
@@ -502,6 +502,11 @@ public class SurefirePlugin extends AbstractSurefireMojo implements SurefireRepo
  @Parameter(property = "surefire.enableProcessChecker")
  private String enableProcessChecker;
 
+ /**
+ * Properties file being used as system properties passed to the provider.
+ *
+ * @see AbstractSurefireMojo#systemPropertyVariables {@code systemPropertyVariables} for how the effective provider properties are calculated
+ */
  @Parameter(property = "surefire.systemPropertiesFile")
  private File systemPropertiesFile;