How to Read an External Properties File in Maven

1. Overview

Maven, a popular build and dependency manager, is widely used in Java development. Also, we can create custom properties in Maven.

When building Java applications, we often rely on properties files to store configuration values.

In this tutorial, we’ll explore how we can read an external properties file in Maven and use it effectively.

2. Introduction to the Problem

To understand the problem, let’s create a simple Maven project:

.
├── pom.xml
├── props
│   └── user.properties
└── src
    └── main
        └── resources
            └── result.txt

Since we want to focus on Maven, our project doesn’t contain any Java code. The project contains a pom.xml and a result.txt file under the src/main/resources directory.

We prepared a properties file props/user.properties:

$ cat props/user.properties
my.name=Kai
my.hobbies=Reading, Tennis, Football
my.signature=vim rocks

We’ll try to ask Maven to read this properties file when building the project.

To simply verify if Maven can load the users.properties file, we’ll first create a text file src/main/resources/result.txt with some ${…} placeholders:

Greeting message: ${greeting}
-----------------------------
Username is ${my.name}
His hobbies are ${my.hobbies}
He came in and said: "${my.signature}"

Then, we’ll leverage the resources Maven plugin, one of Maven’s core plugins, to filter the result.txt in the src/main/resources directory. It’s worth mentioning that the resources filtering is performed at the process-resources phase by default.

Next, let’s look at how we configure the resources plugin in the pom.xml file:

<project>
    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>${maven.resources.version}</version>
                <configuration>
                    <outputDirectory>${project.build.outputDirectory}/filtered-result</outputDirectory>
                </configuration>
            </plugin>
        </plugins>
    </build>

    <properties>
        <greeting>Hi there, how are you</greeting>
    </properties>
</project>

We declare a property named greeting in pom.xml. Further, we ask the resources plugin to filter files in the src/main/resources directory and place the result under ${project.build.outputDirectory}/filtered-result.

Now, if we execute the Maven command to process-resources, Maven only knows the greeting property that we defined in the pom.xml file:

$ mvn clean process-resources
[INFO] Scanning for projects...
[INFO] ------------------< com.baeldung:external-properties >------------------
[INFO] Building external-properties 0.0.1-SNAPSHOT
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
...
$ cat target/classes/filtered-result/result.txt
Greeting message: Hi there, how are you
-----------------------------
Username is ${my.name}
His hobbies are ${my.hobbies}
He came in and said: "${my.signature}"

Next, let’s see how to ask Maven to read the external properties file during the build process and make its values available for use.

3. Using the Properties Maven Plugin

The properties Maven plugin is a powerful tool for reading and injecting properties into the build process. Next, let’s see how to use this plugin to solve our problem.

3.1. Configuring the Properties Maven Plugin

First, let’s configure the properties plugin in our pom.xml file and read our user.properties file:

<project>
    <build>
        <plugins>
           <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>properties-maven-plugin</artifactId>
                <version>${properties.plugin.version}</version>
                <executions>
                    <execution>
                        <phase>initialize</phase>
                        <goals>
                            <goal>read-project-properties</goal>
                        </goals>
                        <configuration>
                            <files>
                                <file>${user.properties.file}</file>
                            </files>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

    <properties>
        <greeting>Hi there, how are you</greeting>
        <user.properties.file>props/user.properties</user.properties.file>
        <properties.plugin.version>1.2.1</properties.plugin.version>
    </properties>
</project>

As we can see, we declare the properties plugin in the <plugins> tag. Since we want to load the properties file when the build starts, we set the plugin to run the read-project-properties goal during the initialize phase.

Further, in this example, we specify the file in the <configuration> tag through an internal property, ${user.properties.file}.

Next, let’s build the project:

$ mvn clean process-resources
[INFO] Scanning for projects...
[INFO] ------------------< com.baeldung:external-properties >------------------
[INFO] Building external-properties 0.0.1-SNAPSHOT
...
[INFO] --- properties:1.2.1:read-project-properties (default) @ external-properties ---
[INFO] Loading 3 properties from File: /.../external-properties-file/props/user.properties
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
...

The build log shows that the properties plugin has loaded three properties from the expected file. But let’s verify if result.txt gets filtered correctly:

$ cat target/classes/filtered-result/result.txt
Greeting message: Hi there, how are you
-----------------------------
Username is Kai
His hobbies are Reading, Tennis, Football
He came in and said: "vim rocks"

As the output shows, the build process has effectively loaded both internal and external properties.

3.2. Passing Properties File to the Maven Command Line

We’ve seen how to load an external properties file using the properties Maven plugin. However, sometimes, hardcoding the file path in pom.xml is inconvenient. For example, we may want to dynamically pick a properties file to build our project.

Let’s create a new properties file:

props
├── liam.properties
└── user.properties

$ cat props/liam.properties
my.name=Liam
my.hobbies=Music, Football, Computer Games
my.signature=Maven rocks

Now, we want Maven to load liam.properties. To achieve that, we can pass the file to the Maven command line as we build the project:

$ mvn -Duser.properties.file=props/liam.properties clean process-resources
[INFO] Scanning for projects...
[INFO] ------------------< com.baeldung:external-properties >------------------
[INFO] Building external-properties 0.0.1-SNAPSHOT
...
[INFO] --- properties:1.2.1:read-project-properties (default) @ external-properties ---
[INFO] Loading 3 properties from File: /.../external-properties-file/props/liam.properties
...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
...

Then, we get the expected result.txt in the target directory:

$ cat target/classes/filtered-result/result.txt
Greeting message: Hi there, how are you
-----------------------------
Username is Liam
His hobbies are Music, Football, Computer Games
He came in and said: "Maven rocks"

This approach makes the build process more flexible.

4. Conclusion

In this article, we explored how to integrate external properties into our Maven build by leveraging the properties Maven plugin. This approach helps manage environment-specific builds, ensuring our projects remain clean, maintainable, and adaptable.