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"?

Shanty

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.

Withers

I'd like to add that any properties supplied on the command line overwrite properties defined in the <properties /> pom section (source). So for maximum flexibility I'd suggest to specify default user property values in <properties />, with the possibility to overwrite them on the command line, instead of hardcoding them in the <configuration /> section. E.g. one such property maven.compiler.source and maven.compiler.target. – Cordillera

@Cordillera Update to the compiler example: For maximum consistency specify the compiler versions in the <configuration/> explicitly again, so that javadoc links to the correct java api version: <source>${maven.compiler.source}</source> and <target>${maven.compiler.target}</target>. – Cordillera

If property is not defined, what will the user property be? From where is the prefix derived? – Sporulate

@OrangeDog: That sounds like a new question. Consider asking it as such, with some context. – Withers

@Withers well you almost answered it here, but then used the wrong example – Sporulate

Sorry, I don't quite understand your question. Are you referring to the annotation paramter "property"? If that is not set, then no "user property" will be available for the setting, as explained in my answer. – Withers

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.

Shanty

Answer 3

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.

Peculation

Hi, Robs, thanks for your answer. However,judging from your answer, the "user property" should be a flag with boolean value which indicate whether it is, but what I saw in plugin doc reveal it is a string value. For example, the plugin tomcat7, goal deploy, it has one parameter mode, but its user property is maven.tomcat.mode. – Shanty

This answer is wrong. Apparently the author confused Maven properties with Java system properties, which can be manipulated using System.getProperty() / System.setProperty(). – Withers

The confusion is understandable, since Maven properties are modeled after System properties; for example, all System properties are available as Maven properties, and Maven properties can be set on the command line using -D, just like System properties (only for System properties the -D must be a JVM argument rather than a Java argument). – Withers