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 {p

Answer 1

It refers to the context in which the property applies. There are, for example, system properties such as JVM version, OS name, etc., which are not "user properties" because the user shouldn't be setting them. Note that this isn't a Maven specific concept, it's a more general way that Java treats various pieces of information that are configuration related (i.e. usually a characteristic of the platform or context a process is running in). "User property" just implies that the user, i.e. the person running Maven or configuring the Maven pom.xml, is setting the property values.

Answer 2

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 3

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.