What's the meaning of user property of maven plugin parameter

Question

I am a newbie to Maven. When I try to refer to any maven plugin document, I always see following format for the parameter definition: Name Description {parameter name} {description} Default Value is: ... User property is: ...

For most cases, I saw the user property is the same with parameter name. I wonder here what's the difference between "User Property" and "Parameter Name". I think the parameter name should be element tag name when specify the parameter value of the correspond plugin when configure them, but what's the usage of "User Property"?

Answer 1

Note: This is for Maven 3. Earlier versions are (a bit) different.

TL;DR:

"User property" specifies the name of the Maven property that can be used to set a plugin parameter. This allows configuring a plugin from outside the <configuration> section. Note that this only works if the parameter is not specified in the <configuration> section (see MNG-4979 - Cannot override configuration parameter from command line).

Maven properties can be set in the POM in the section <properties>, or on the command line as -DmyProperty=myValue.

---

Long version

In Maven, the parameters of a plugin are usually set in an <configuration> section in the POM. The "parameter name" given in the plugin's documentation is the name to be used in the configuration setting.

For example, the Surefire goal surefire:test has a parameter "failIfNoSpecifiedTests". To set it in the POM, use:

<configuration> <failIfNoSpecifiedTests>false</failIfNoSpecifiedTests> </configuration> 

However, sometimes it is useful to set a plugin parameter from outside the <configuration> section, for example to set it on the command line, or in a Maven profile. To allow this, a plugin can also declare that it will read the parameter value from a Maven property (if set). This property is what the docs list as the User property.

The User property for failIfNoSpecifiedTests is surefire.failIfNoSpecifiedTests. So instead of the <configuration> section above, one could also use the property surefire.failIfNoSpecifiedTests. For example:

• on the command line, by specifying -Dsurefire.failIfNoSpecifiedTests=false
• in a POM profile: <properties> <surefire.failIfNoSpecifiedTests> false </surefire.failIfNoSpecifiedTests> ...

Note that the User property must be declared by the plugin for each parameter, so not all parameters will have one. For example, the parameter basedir does not have a User property, so can not be set on the command line.

---

In the source code of the plugin, the parameter name not explicitly declared; it is taken from the name of the Java field. The source code for "failIfNoSpecifiedTests" is:

/**  * Set this to "true" to cause a failure if the none of the tests  * specified in -Dtest=... are run. Defaults to "true".  *  * @since 2.12  */ @Parameter( property = "surefire.failIfNoSpecifiedTests" ) private Boolean failIfNoSpecifiedTests; 

You can see that the parameter name "failIfNoSpecifiedTests" is taken from the field name. The annotation parameter "property" defines the Maven property to use.

Answer 2

I guess I may have got the answer, but still not assure. The answer lies on the annotation type Parameter in package org.apache.maven.plugins.annotations. In this annotation type, it defines several fields. Among them:

1. alias: this should define the Parameter Name in plugin document.
2. defaultValue: this define the default value specified for each parameter in plugin document.
3. property: this define the user property. According to the comment of this field, it is said this property can be specified from -D execution, setting properties or pom properties.
4. readonly: read only flag.
5. required: whether is mandatory.