Enabling filtering

Variables in a resource are written with the ${...} or @...@ delimiters. They can come from the system properties, the project properties, filter files, and the command line.

For example, take a resource src/main/resources/hello.txt that contains

Hello ${name}

and a POM that declares the resource directory:

<project>
  ...
  <name>My Resources Plugin Practice Project</name>
  ...
  <build>
    ...
    <resources>
      <resource>
        <directory>src/main/resources</directory>
      </resource>
      ...
    </resources>
    ...
  </build>
  ...
</project>

Running

mvn resources:resources

copies the file to target/classes/hello.txt unchanged, because filtering is off by default:

Hello ${name}

Add a <filtering> element to the resource and set it to true:

<project>
  ...
  <resource>
    <directory>src/main/resources</directory>
    <filtering>true</filtering>
  </resource>
  ...
</project>

Now target/classes/hello.txt contains the project name from the POM:

Hello My Resources Plugin Practice Project

Setting values

A value given on the command line with -D replaces the project's value. To change name to world:

mvn resources:resources -Dname="world"

The result in target/classes/hello.txt is

Hello world

You can also define your own variables in the <properties> element of the POM. If hello.txt uses ${your.name}, this POM supplies the value:

<project>
  ...
  <properties>
    <your.name>world</your.name>
  </properties>
  ...
</project>

your.name = world

<project>
  ...
  <build>
    ...
    <filters>
      <filter>my-filter-values.properties</filter>
    </filters>
    ...
  </build>
  ...
</project>

Binary files

Do not filter files with binary content such as images, because that most likely corrupts them.

If you have both text and binary resources, keep them in two directories: the default src/main/resources for the files that are not filtered, and for example src/main/resources-filtered for the files that are:

<project>
  ...
  <build>
    ...
    <resources>
      <resource>
        <directory>src/main/resources-filtered</directory>
        <filtering>true</filtering>
      </resource>
      ...
    </resources>
    ...
  </build>
  ...
</project>

Alternatively, configure the file extensions that are not filtered. The nonFilteredFileExtensions parameter adds to the built-in list.

Escaping

To keep an expression from being replaced, precede it with an escape string. Set the escape string with the escapeString parameter:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-resources-plugin</artifactId>
        <version>3.5.0</version>
        <configuration>
          ...
          <escapeString>\</escapeString>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>

With the escape string \, an escaped expression is not interpolated, and the escape string is removed from the output:

Anything else preceded by the escape string is passed through unchanged. The same applies to expressions delimited by @.

Encoding

A character encoding such as US-ASCII, UTF-8 or UTF-16 is used to read and write filtered files. The best practice is to define the encoding through the ${project.build.sourceEncoding} property, which the resources plugin uses by default for its encoding parameter:

<project>
  ...
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    ...
  </properties>
  ...
</project>

To use a different encoding for the resources only, set the encoding parameter in the plugin configuration:

<project>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-resources-plugin</artifactId>
        <version>3.5.0</version>
        <configuration>
          ...
          <encoding>UTF-8</encoding>
          ...
        </configuration>
      </plugin>
    </plugins>
    ...
  </build>
  ...
</project>

Filtered .properties files can use their own encoding through the propertiesEncoding parameter (since 3.2.0); it defaults to encoding.

See also

• Filtering properties files
• Custom resources filters
• Specifying resource directories