Resources and filtering

A resource is a file the code reads at run time, and the resources plugin is the goal that copies it from src/main/resources into target/classes. Copying is the default. Filtering is the option that turns the copy into a rewrite: every ${...} in a resource is replaced with the property it names, which is how a properties file can carry the version of the project without anybody editing it. This article builds the same application twice, with filtering on and off, and reads the difference from the program.

The project

One resource with a placeholder in it, and one class that reads it from the class path:

src/main/resources/app.properties

app.name=Demo app.version=${project.version}

src/main/java/com/example/app/Main.java

package com.example.app; import java.io.IOException; import java.io.InputStream; import java.util.Properties; public class Main { static String label() throws IOException { Properties props = new Properties(); try (InputStream in = Main.class.getResourceAsStream("/app.properties")) { props.load(in); } return props.getProperty("app.name") + " " + props.getProperty("app.version"); } public static void main(String[] args) throws IOException { System.out.println(label()); } }

With filtering

Filtering is switched on per resource directory, because a project usually wants it for a properties file and not for a binary. The block below says "the files of src/main/resources, with filtering":

pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>app</artifactId> <version>2.1.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> <build> <resources> <resource> <directory>src/main/resources</directory> <filtering>true</filtering> </resource> </resources> </build> </project>

mvn -B package > build.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" build.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:app >---------------------------
[INFO] Building app 2.1.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ app ---
[INFO] Copying 1 resource from src/main/resources to target/classes
[INFO] The encoding used to copy filtered properties files has not been set. This means that the same encoding will be used to copy filtered properties files as when copying other filtered resources. This might not be what you want! Run your build with --debug to see which files might be affected. Read more at https://maven.apache.org/plugins/maven-resources-plugin/examples/filtering-properties-files.html
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ app ---
[INFO] Recompiling the module because of <REASON>.
[INFO] Compiling 1 source file with javac [debug release 21] to target/classes
[INFO]
[INFO] --- resources:3.4.0:testResources (default-testResources) @ app ---
[INFO] skip non existing resourceDirectory <project>/src/test/resources
[INFO]
[INFO] --- compiler:3.15.0:testCompile (default-testCompile) @ app ---
[INFO] No sources to compile
[INFO]
[INFO] --- surefire:3.5.4:test (default-test) @ app ---
[INFO] No tests to run.
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ app ---
[INFO] Building jar: <project>/target/app-2.1.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

Copying 1 resource from src/main/resources to target/classes is one line for one file, filtered or not. The long warning under it is the plugin telling the project that it does not know which encoding to use for a filtered .properties file: the Java properties format is ISO-8859-1 by specification, the other filtered files are copied in the project encoding, and the plugin wants to be told when the two differ. A project that filters properties files sets the encoding of the plugin:

The setting is propertiesEncoding in the configuration of maven-resources-plugin, next to the version of the plugin that a project pins, and the plugin then uses it for the filtered .properties files and the project encoding for the rest.

With ASCII in the file, as here, the warning is harmless: the bytes are the same in both encodings. With a non-ASCII character in a filtered properties file it is not, and the value a program reads is the one that was mangled.

What the program reads

The copy in target/classes has the placeholder replaced:

cat target/classes/app.properties

app.name=Demo
app.version=2.1.0

java -cp target/classes com.example.app.Main

Demo 2.1.0

Nothing in the source of the program knows the version of the project: it reads the file it was given. The filtering is what filled the file in, from ${project.version}, which is the version of the pom. Every property of the properties article is available to a filter, and so is every value of the settings and of the command line, which is how a build can stamp an environment name into a resource: -Denv=staging and build.env=${env}.

Without filtering

The same pom with false in that element copies the file byte for byte, and the placeholder reaches the program:

pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>app</artifactId> <version>2.1.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> <build> <resources> <resource> <directory>src/main/resources</directory> <filtering>false</filtering> </resource> </resources> </build> </project>

mvn -B clean package > copy.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" copy.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] --------------------------< com.example:app >---------------------------
[INFO] Building app 2.1.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- resources:3.4.0:resources (default-resources) @ app ---
[INFO] Copying 1 resource from src/main/resources to target/classes
[INFO]
[INFO] --- compiler:3.15.0:compile (default-compile) @ app ---
[INFO] Recompiling the module because of <REASON>.
[INFO] Compiling 1 source file with javac [debug release 21] to target/classes
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

cat target/classes/app.properties
java -cp target/classes com.example.app.Main

app.name=Demo
app.version=${project.version}
Demo ${project.version}

No warning either, because nothing is filtered: the plugin is a copy machine at that point. This is the state a resource is in until a project asks for more, and it is the state to check first when a program reads a placeholder it expected to be filled.

The resource rules

Four things about the block are worth knowing before writing one:

Test resources are the same story in src/test/resources, copied into target/test-classes by resources:testResources, the goal the layout article lists among the eleven files of a build.

Where to go next

Surefire and the reports takes the plugin of the test phase: a green run, a red run, one test by name, and the two ways of skipping them.

Article author: Arthur Isaev