Filtering Files

Some files of the sub projects can be filtered, i.e. special tokens will be replaced by some other string before the actual build is started. In detail, the following files will be filtered:

• POM files selected by the include/exclude patterns. The tokens to be filtered must be enclosed in @...@ to avoid interferences with Maven's normal POM interpolation, i.e. use @project.version@ instead of ${project.version}. Starting with version 1.3, the plugin will also (recursively) filter all POM files referenced via <parent> or <module> tags, if the projects are cloned to a temporary location.
• The custom user setting file. Again, the tokens to be filtered in this file must be enclosed in @...@.
• The invoker properties, the goals file and the profiles file. Tokens in these files must use the usual Maven syntax ${...}.

The following example directory structure highlights the files which are filtered by the Invoker Plugin:

./
+- pom.xml
+- src/
   +- it/
      +- settings.xml                  <- Filtered
      +- aggregator-project/
         +- child-module-1/
         |  +- pom.xml                 <- Filtered
         +- child-module-2/
         |  +- pom.xml                 <- Filtered
         +- pom.xml                    <- Filtered
         +- invoker.properties         <- Filtered
         +- goals.txt                  <- Filtered
         +- profiles.txt               <- Filtered

Below is the corresponding POM snippet for the plugin configuration:

<project>
  <properties>
    <projectPropertyUsedForFiltering>another-value</projectPropertyUsedForFiltering>
  </properties>
  ...
  <build>
    <plugins>
      <plugin>
        <artifactId>maven-invoker-plugin</artifactId>
        <version>1.3</version>
        <configuration>
          <projectsDirectory>src/it</projectsDirectory>
          <cloneProjectsTo>${project.build.directory}/it</cloneProjectsTo>
          <pomIncludes>
            <pomInclude>*/pom.xml</pomInclude>
          </pomIncludes>
          <settingsFile>src/it/settings.xml</settingsFile>
          <filterProperties>
            <pluginPropertyUsedForFiltering>some-value</pluginPropertyUsedForFiltering>
          </filterProperties>
        </configuration>
        <executions>
          <execution>
            <id>integration-test</id>
            <goals>
              <goal>run</goal>
            </goals>
          </execution>
       </executions>
      </plugin>
    </plugins>
  </build>
</project>

When filtering the files, the plugin searches various data sources for a token's replacement value in the order indicated below. The search terminates as soon as an existing replacement value has been found, i.e. the value is not null.

1. Tokens of the form project.* and pom.* will be expanded to the referenced POM value if possible, e.g. project.version refers to the version given in pom.xml. If no such POM element exists, the value lookup continues as outlined next.
2. Built-in properties defined by the Invoker Plugin will be processed. See this table for a list of available built-in properties:

   Built-in Property	Value	Since
   localRepository	The absolute path to the local repository used for the main build.	1.2
   localRepositoryUrl	The file: URL to the local repository used for the main build.	1.3

3. The properties given by the parameter filterProperties in the plugin configuration will be consulted for a property whose key equals the token. For the example POM shown above, the value some-value has been associated with the token pluginPropertyUsedForFiltering.
4. The properties given by the POM's <properties> section will be searched for a property whose key equals the token. Regarding the example POM, the value another-value has been associated with the token projectPropertyUsedForFiltering.

Tokens for which no replacement value could be determined will be left unchanged.