Update Properties

This goal is useful when you define dependency versions using properties. For example if you have a suite of projects and you want to ensure that you use the same version of each dependency in the suite, you might have a dependency section that looks like this:

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>com.foo.bar</groupId>
      <artifactId>manchu-core</artifactId>
      <version>[${manchu.version}]</version>
    </dependency>
    ...
    <dependency>
      <groupId>com.foo.bar</groupId>
      <artifactId>manchu-extra</artifactId>
      <version>[${manchu.version}]</version>
    </dependency>
    ...
  </dependencies>
  ...
  <properties>
    ...
    <manchu.version>1.5.0</manchu.version>
    ...
  </properties>
  ...
</project>

The aim being to allow updating the version of all the suite components in one go. The versions-maven-plugin can help you to automate these updates.

By default, the versions-maven-plugin will look at the dependencies in your POM. If any dependencies declare a version which depends on evaluating a single property that is defined in the POM, for example:

    <!-- strongly recommend this version -->
    <dependency>
      <groupId>com.foo.bar</groupId>
      <artifactId>manchu-core</artifactId>
      <version>${manchu.version}</version>
    </dependency>

    <!-- force this version -->
    <dependency>
      <groupId>com.foo.bar</groupId>
      <artifactId>manchu-core</artifactId>
      <version>[${manchu.version}]</version>
    </dependency>

    <!-- any version between this version and 2.0.0, excluding 2.0.0 and 2.0.0-SNAPSHOT -->
    <dependency>
      <groupId>com.foo.bar</groupId>
      <artifactId>manchu-core</artifactId>
      <version>[${manchu.version},2.0.0-!)</version>
    </dependency>

    <!-- any version between version 1.0.0 and this version inclusive -->
    <dependency>
      <groupId>com.foo.bar</groupId>
      <artifactId>manchu-core</artifactId>
      <version>[1.0.0,${manchu.version}]</version>
    </dependency>

If multiple dependencies use the property to define the version, then the all dependencies will be used to determine what versions are available (and consequently what version to update the property to). The version chosen in such cases must be available for all associated dependencies.

The automatic detection can be assisted by adding a version-maven-plugin configuration section to the POM, for example if we add the following to the POM:

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version>2.16.2</version>
        <configuration>
          ...
          <properties>
            ...
            <property>
              <name>manchu.version</name>
              ...
              <dependencies>
                <dependency>
                  <groupId>com.foo.bar</groupId>
                  <artifactId>manchu-wibble</artifactId>
                </dependency>
                ...
              </dependencies>
              ...
            </property>
          </properties>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

Then executing the update-properties goal will update the manchu.version property to the latest common version of both manchu-core and manchu-wibble available to you (i.e. based on your local repository and all currently active remote repositories).

If you want to restrict updates to within a specific range, for example, suppose we only want the 1.5 stream of manchu:

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version>2.16.2</version>
        <configuration>
          ...
          <properties>
            ...
            <property>
              <name>manchu.version</name>
              ...
              <version>[1.5.0,1.6.0-!)</version>
              ...
            </property>
            ...
          </properties>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

Additionally, if you want to disable the automatic detection of properties set the autoLinkItemDependencies to false

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version>2.16.2</version>
        <configuration>
          ...
          <properties>
            ...
            <property>
              <name>manchu.version</name>
              ...
              <autoLinkDependencies>false</autoLinkDependencies>
              ...
            </property>
            ...
          </properties>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

By default, the reactor will also be searched to see if it can satisfy the property's associated dependencies. If you want to disable the preference given to the reactor (i.e. stop the reactor version always winning)

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version>2.16.2</version>
        <configuration>
          ...
          <properties>
            ...
            <property>
              <name>manchu.version</name>
              ...
              <preferReactor>false</preferReactor>
              ...
            </property>
            ...
          </properties>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

If you want to disable the searching the reactor at all:

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version>2.16.2</version>
        <configuration>
          ...
          <properties>
            ...
            <property>
              <name>manchu.version</name>
              ...
              <searchReactor>false</searchReactor>
              ...
            </property>
            ...
          </properties>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

The allowSnapshots property and configuration option allow the inclusion of snapshots, if you want to ensure that snapshots are never resolved,

<project>
  ...
  <build>
    ...
    <plugins>
      ...
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>versions-maven-plugin</artifactId>
        <version>2.16.2</version>
        <configuration>
          ...
          <allowSnapshots>true</allowSnapshots> <!-- in general allow them -->          
          ...
          <properties>
            ...
            <property>
              <name>manchu.version</name>
              ...
              <banSnapshots>true</banSnapshots> <!-- but never for this property -->
              ...
            </property>
            ...
          </properties>
          ...
        </configuration>
      </plugin>
      ...
    </plugins>
    ...
  </build>
  ...
</project>

The includes and **excludesparameters follow the formatgroupId:artifactId:type:classifier`. Use a comma separated separated list to specify multiple includes. Wildcards (*) can also be used to match multiple values.

This example will match anything with the groupId “org.codehaus.plexus” and anything with the groupId and artifactId matching “junit”.

Only properties that map to artifacts that are allowed by the inclusion and exclusion patterns will be updated.

With a project that looks like this:

<project>
  ...
  <dependencies>
    ...
    <dependency>
      <groupId>com.foo.bar</groupId>
      <artifactId>manchu-core</artifactId>
      <version>[${manchu.version}]</version>
    </dependency>
    ...
    <dependency>
      <groupId>com.foo.bar</groupId>
      <artifactId>manchu-extra</artifactId>
      <version>[${manchu.version}]</version>
    </dependency>
    ...
    <dependency>
      <groupId>org.blarg</groupId>
      <artifactId>blarg-framework</artifactId>
      <version>[${blarg.version}]</version>
    </dependency>
    ...
  </dependencies>
  ...
  <properties>
    ...
    <manchu.version>1.5.0</manchu.version>
    <blarg.version>3.1.0.RELEASE</blarg.version>
    ...
  </properties>
  ...
</project>

To update the property for only the “com.foo.bar” dependencies, you can run:

mvn versions:update-properties -Dincludes=com.foo.bar:*

Would result in the property for the manchu.version being updated, but not the blarg.version property.

In the above example, you could achieve the same result using:

mvn versions:update-properties -Dexcludes=org.blarg:*

If a property is used by artifacts that are not allowed by the set of specified includes and excludes then the property will not be updated.