Read an External Properties File in Maven

Mary ZhengMarch 26th, 2025Last Updated: March 24th, 2025

0 89 5 minutes read

1. Introduction

Reading external properties in a maven project is useful when accessing secure credential configuration, or logging settings, etc. In this article, I will demonstrate how to read an external properties file in a Maven project.

2. Setup

In this step, I will create a maven project in an Eclipse IDE.

read external properties — Figure 1. Create a Maven Project

2.1. Maven Project Folder Structure

This generated project follows the Maven project folder structure.

The external properties file is stored in the “external-config” folder in the project root directory.
The maven-resources-plugin filters files in the src/main/resources directory and places the result under ${project.build.outputDirectory}/filtered-result.

2.2 External Properties

The “external-config” folder in the project root is added to store the external properties. There are four properties defined: “my.custom.property“, “server.log“, “database.login“, and “apikey“.

external.properties

my.custom.property=This is a custom value under external-config/external.properties
server.log=server log location different at environment
database.login=database credentials should not in source code
apikey=apikey should not in source repository

2.3 Result.txt

The “src/main/resource/result.txt” file contains the properties defined in the external.properties file. The property’s value will be replaced when the “process-resources” task is executed.

result.txt

Properties from pom.xml: ${greeting}
-----------------------------
External Properties: ${my.custom.property}
server log location: ${server.log}
database credentials: ${database.login}
apikey: ${apikey}

3. POM.XML File

In this step, I will update the generated pom.xml by adding two build plugins: maven-resource-plugin and properties-maven-plugin to read the “my.custom.property“, “server.log“, “database.login“, and “apikey” properties from the external file and the result.txt is updated with their values.

pom.xml

<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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>org.zheng.demo</groupId>
    <artifactId>maven-external-properties</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>maven-external-properties</name>
    <description>demo for maven external properties</description>
 
    <packaging>jar</packaging>
 
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <greeting>Hi there, how are you</greeting>
        <user.properties.file>external-config/external.properties</user.properties.file>
    </properties>
 
    <build>
        <resources>
            <resource>
                <directory>src/main/resources</directory>
                <filtering>true</filtering>
            </resource>
        </resources>
        <plugins>
            <plugin>
                <artifactId>maven-resources-plugin</artifactId>
                <version>3.3.1</version>
                <configuration>
                    <outputDirectory>
                        ${project.build.outputDirectory}/filtered-result</outputDirectory>
                </configuration>
            </plugin>
 
            <!-- Properties Maven Plugin to load external properties -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>properties-maven-plugin</artifactId>
                <version>1.2.1</version>
                <executions>
                    <execution>
                        <phase>initialize</phase> <!-- This phase reads
                        properties -->
                        <goals>
                            <goal>read-project-properties</goal>
                        </goals>
                        <configuration>
                            <files>
                                <file>${user.properties.file}</file> <!--
                                Path to
                                external properties file -->
                            </files>
                        </configuration>
 
                    </execution>
                </executions>
            </plugin>
 
        </plugins>
    </build>
</project>

Line 16: defines the greeting property with the "Hi there, how are you" value.
Line 17: defines the user.properties file with the external-config/external.properties value.
Line 24: enable the resource filtering.
Line 29: configure maven-resources-plugin for the build process.
Line 40: configure properties-maven-plugin for the build process.
Line 51: access the external file location via user.properties.file.

4. Read External Properties Demo

In this step, I will execute the mvn clean install command and capture the output.

mvn clean install output

C:\MaryTools\workspace\maven-external-properties>mvn clean install
[INFO] Scanning for projects...
[INFO]
[INFO] --------------< org.zheng.demo:maven-external-properties >--------------
[INFO] Building maven-external-properties 0.0.1-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- clean:3.2.0:clean (default-clean) @ maven-external-properties ---
[INFO] Deleting C:\MaryTools\workspace\maven-external-properties\target
[INFO]
[INFO] --- properties:1.2.1:read-project-properties (default) @ maven-external-properties ---
[INFO] Loading 4 properties from File: C:\MaryTools\workspace\maven-external-properties\external-config\external.properties
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ maven-external-properties ---
[WARNING] File encoding has not been set, using platform encoding Cp1252. Build is platform dependent!
[WARNING] See https://maven.apache.org/general.html#encoding-warning
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 1 resource from src\main\resources to target\classes\filtered-result
[INFO]
[INFO] --- compiler:3.11.0:compile (default-compile) @ maven-external-properties ---
[INFO] Nothing to compile - all classes are up to date
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ maven-external-properties ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 0 resource from src\test\resources to target\classes\filtered-result
[INFO]
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ maven-external-properties ---
[INFO] Nothing to compile - all classes are up to date
[INFO]
[INFO] --- surefire:3.2.2:test (default-test) @ maven-external-properties ---
[INFO] No tests to run.
[INFO]
[INFO] --- jar:3.3.0:jar (default-jar) @ maven-external-properties ---
[INFO] Building jar: C:\MaryTools\workspace\maven-external-properties\target\maven-external-properties-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- install:3.1.1:install (default-install) @ maven-external-properties ---
[INFO] Installing C:\MaryTools\workspace\maven-external-properties\pom.xml to C:\Users\azpm0\.m2\repository\org\zheng\demo\maven-external-properties\0.0.1-SNAPSHOT\maven-external-properties-0.0.1-SNAPSHOT.pom
[INFO] Installing C:\MaryTools\workspace\maven-external-properties\target\maven-external-properties-0.0.1-SNAPSHOT.jar to C:\Users\azpm0\.m2\repository\org\zheng\demo\maven-external-properties\0.0.1-SNAPSHOT\maven-external-properties-0.0.1-SNAPSHOT.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  9.652 s
[INFO] Finished at: 2025-03-22T12:46:38-05:00
[INFO] ------------------------------------------------------------------------
 
C:\MaryTools\workspace\maven-external-properties>

Line 12: read-project-properties reads the properties from the external file.
Line 15: default-resources replaces the property value and copies it to the filter-result folder.
Line 19: outline the details when copying resources.

4.1 Verify the Result.txt is Updated

In this step, I will verify that property values in the result.txt file are replaced.

repalced result.txt

Properties from pom.xml: Hi there, how are you
-----------------------------
External Properties: This is a custom value under external-config/external.properties
server log location: server log location different at environment
database credentials: database credentials should not in source code
apikey: apikey should not in source repository

As expected, the properties are replaced with the value in the external.properties file.

5. Read External Properties via Argument

In this step, I will prepare user.properties in a different location:

user.properteies

my.custom.property=This is a custom value under user.properties
server.log=server.log
database.login=unknown
apikey=guess

I will execute the mvn clean install and overwrite the external property file.

mvn clean install -Dgreeting=Mary -Duser.properties.file=C:\MaryTools\workspace\config\props\user.properties

C:\MaryTools\workspace\maven-external-properties>mvn clean install -Dgreeting=Mary -Duser.properties.file=C:\MaryTools\workspace\config\props\user.properties
[INFO] Scanning for projects...
[INFO]
[INFO] --------------< org.zheng.demo:maven-external-properties >--------------
[INFO] Building maven-external-properties 0.0.1-SNAPSHOT
[INFO]   from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- clean:3.2.0:clean (default-clean) @ maven-external-properties ---
[INFO] Deleting C:\MaryTools\workspace\maven-external-properties\target
[INFO]
[INFO] --- properties:1.2.1:read-project-properties (default) @ maven-external-properties ---
[INFO] Loading 4 properties from File: C:\MaryTools\workspace\config\props\user.properties
[INFO]
[INFO] --- resources:3.3.1:resources (default-resources) @ maven-external-properties ---
[WARNING] File encoding has not been set, using platform encoding Cp1252. Build is platform dependent!
[WARNING] See https://maven.apache.org/general.html#encoding-warning
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 1 resource from src\main\resources to target\classes\filtered-result
[INFO]
[INFO] --- compiler:3.11.0:compile (default-compile) @ maven-external-properties ---
[INFO] Nothing to compile - all classes are up to date
[INFO]
[INFO] --- resources:3.3.1:testResources (default-testResources) @ maven-external-properties ---
[WARNING] Using platform encoding (Cp1252 actually) to copy filtered resources, i.e. build is platform dependent!
[INFO] Copying 0 resource from src\test\resources to target\classes\filtered-result
[INFO]
[INFO] --- compiler:3.11.0:testCompile (default-testCompile) @ maven-external-properties ---
[INFO] Nothing to compile - all classes are up to date
[INFO]
[INFO] --- surefire:3.2.2:test (default-test) @ maven-external-properties ---
[INFO] No tests to run.
[INFO]
[INFO] --- jar:3.3.0:jar (default-jar) @ maven-external-properties ---
[INFO] Building jar: C:\MaryTools\workspace\maven-external-properties\target\maven-external-properties-0.0.1-SNAPSHOT.jar
[INFO]
[INFO] --- install:3.1.1:install (default-install) @ maven-external-properties ---
[INFO] Installing C:\MaryTools\workspace\maven-external-properties\pom.xml to C:\Users\azpm0\.m2\repository\org\zheng\demo\maven-external-properties\0.0.1-SNAPSHOT\maven-external-properties-0.0.1-SNAPSHOT.pom
[INFO] Installing C:\MaryTools\workspace\maven-external-properties\target\maven-external-properties-0.0.1-SNAPSHOT.jar to C:\Users\azpm0\.m2\repository\org\zheng\demo\maven-external-properties\0.0.1-SNAPSHOT\maven-external-properties-0.0.1-SNAPSHOT.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  1.348 s
[INFO] Finished at: 2025-03-22T12:54:22-05:00
[INFO] ------------------------------------------------------------------------
 
C:\MaryTools\workspace\maven-external-properties>

Line 1: the “-Dgreeting=Mary” overwrites the greeting property value defined in the pom.xml
Line 1: the “-Duser.properties.file=C:\MaryTools\workspace\config\props\user.properties” overwrites the external properties with a different external file.

5.1 Verify the Result.txt is Updated

In this step, I will verify that property values in the result.txt are replaced.

replaced result.txt

Properties from pom.xml: Mary
-----------------------------
External Properties: This is a custom value under user.properties
server log location: server.log
database credentials: unknown
apikey: guess

As expected, the properties are replaced with the values in the user.properties file.

6. Conclusion

In this article, I demonstrated how to read external properties by leveraging the properties Maven plugin. It helps manage environment-specific builds, ensuring projects remain clean, maintainable, and adaptable.

7. Download

This was an example of a maven project that used properties-maven-plugin to read external properties.

Download
You can download the full source code of this example here: Read an External Properties File in Maven

Read an External Properties File in Maven

1. Introduction

2. Setup

2.1. Maven Project Folder Structure

2.2 External Properties

2.3 Result.txt

3. POM.XML File

4. Read External Properties Demo

4.1 Verify the Result.txt is Updated

5. Read External Properties via Argument

5.1 Verify the Result.txt is Updated

6. Conclusion

7. Download

Thank you!

Mary Zheng

Thank you!

1. Introduction

2. Setup

2.1. Maven Project Folder Structure

2.2 External Properties

2.3 Result.txt

3. POM.XML File

4. Read External Properties Demo

4.1 Verify the Result.txt is Updated

5. Read External Properties via Argument

5.1 Verify the Result.txt is Updated

6. Conclusion

7. Download

Thank you!

Related Articles

Thank you!