Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 41 ยท The POM

Properties and Build Settings

Use Maven properties and ${...} interpolation, set UTF-8 encoding and maven.compiler.release, and configure a Java 25 build that behaves the same everywhere.

A POM that repeats the same value in five places is a POM waiting for a typo. Maven solves this with properties: named values you define once and refer to as ${name} anywhere in the file. Properties also carry the build's basic settings: which character encoding your source files use, and which Java version you compile for.

This lesson shows how properties are defined and resolved, which ones Maven gives you for free, and how to set up a clean Java 25 build. The real Maven cannot run on this site, so every mvn command and POM here is read-only. The runnable examples are small Java stand-ins that mimic what Maven does internally, and each one says so.

One value, many uses

Define once Put the value in properties.
Use anywhere Write ${name} in the POM.
Override Pass -Dname=value on the command line.
1 / 2

Defining your own properties

Properties live in a <properties> element directly under <project>. The element name is the property name, and the text is the value.

XML
<properties>
  <junit.version>5.11.4</junit.version>
  <app.title>Inventory Service</app.title>
</properties>

You use a property by wrapping its name in ${ and }. Maven replaces the reference before it uses the value, a step called interpolation.

XML
<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <version>${junit.version}</version>
  <scope>test</scope>
</dependency>

Dots in names are only a convention. They group related values (junit.version, junit.platform.version), and a dot has no special meaning. Properties can refer to other properties, so <jar.name>${project.artifactId}-${project.version}</jar.name> works.

If a name is not defined anywhere, Maven leaves the text ${name} untouched. That is a common source of confusing errors, such as a version literally called ${junit.versoin}. Always read the exact error message: it usually quotes the unresolved text.

Properties Maven gives you

Without defining anything, you can use several families of built-in names.

Prefix Example What it gives you
project.* ${project.version}, ${project.groupId}, ${project.artifactId} Values from the POM itself.
project.build.* ${project.build.directory} Build paths such as target and target/classes.
project.basedir ${project.basedir} The folder that contains this pom.xml.
env.* ${env.JAVA_HOME} Operating-system environment variables.
settings.* ${settings.localRepository} Values from settings.xml.
Java system properties ${java.version}, ${user.home}, ${os.name} Whatever the running JVM reports.

The older ${pom.version} form is deprecated; use ${project.version}. A bare ${version} also still works in some places but is deprecated for the same reason.

Who wins when names collide

Maven builds one lookup table from several sources. In rough order of strength, the winner is the value from the command line (-Dname=value, called a user property), then the POM's <properties> (including inherited ones), then system properties and environment. This is why a team can write <skipITs>false</skipITs> in the POM and a developer can still run mvn verify -DskipITs=true without editing a file.

A stand-in for interpolation

The real interpolator is Java code inside Maven. The stand-in below does the essential job: it looks up ${...} references in a table, resolves nested ones, leaves unknown names unchanged and refuses to loop forever on a cycle.

Java A tiny property resolver (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The output shows nested resolution (inventory-1.4.0-SNAPSHOT.jar), the command-line override (6.0.0), the typo left visible, and a cycle reported instead of hanging. Real Maven reports a cycle as an error and stops the build; the marker text here is only for illustration.

Source encoding

Java source files are text, and text needs an encoding. If you do not say which one, javac falls back to the platform default, and that differs between machines. A file with an accented letter can compile on your laptop and produce garbled strings on the build server.

The fix is one property:

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

Plugins such as the compiler and resources plugins read this value, so one line covers compiling, copying resources and filtering. If you forget it, Maven 3 prints a warning like "Using platform encoding to copy filtered resources", which is a hint to add the property. Newer Java versions (18 and later) default to UTF-8 for file reading, but the property still makes the intent explicit, and builds also run on older tooling.

You can see the failure mode without Maven. The stand-in below takes bytes written as UTF-8 and reads them with a different charset, which is exactly what a wrong encoding setting does to your source.

Java What a wrong encoding does (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

The letter รฉ is two bytes in UTF-8. Read as ISO-8859-1 each byte becomes its own character, so you see cafรƒยฉ. Setting project.build.sourceEncoding tells every plugin to read your files the right way.

Choosing the Java version

For years the standard recipe was two properties, maven.compiler.source and maven.compiler.target. They only set the language level and the bytecode level. They do not restrict which library classes you may call, so compiling with JDK 25 for "Java 11" could still use methods that exist only in newer JDKs, and the result would crash on a real Java 11 runtime.

The modern setting is maven.compiler.release. It maps to javac --release, which sets the language level, the bytecode level and the available API all at once.

XML
<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <maven.compiler.release>25</maven.compiler.release>
</properties>

release requires a JDK 9 or newer to run Maven, which is no problem today. Use it instead of source/target; setting both is redundant, and release takes priority. The next lessons (Lifecycles and Phases and The Core Plugins in Practice) show how the compiler plugin applies it.

A complete Java 25 starting 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>com.example</groupId>
  <artifactId>inventory</artifactId>
  <version>1.0.0-SNAPSHOT</version>

  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.release>25</maven.compiler.release>
    <junit.version>5.11.4</junit.version>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>${junit.version}</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

To run this you need a JDK 25 (check with java -version and mvn -v, which prints the Java version Maven uses). If Maven runs on a different JDK than you expect, the usual cause is JAVA_HOME; see Installing Maven and the Wrapper.

Keep versions of related libraries in properties (jackson.version, junit.version). When one number must change, you edit one line, and mvn versions:display-property-updates can even tell you which ones are outdated.

Properties versus resource filtering

Properties are also available inside resource files such as application.properties, but only when you turn on filtering for that folder. Then ${project.version} in a resource is replaced during the build.

XML
<build>
  <resources>
    <resource>
      <directory>src/main/resources</directory>
      <filtering>true</filtering>
    </resource>
  </resources>
</build>

Filtering is off by default so binary files and text that contains ${...} for other reasons are not damaged. Turn it on only for folders that need it, and beware that Spring Boot projects use @name@ delimiters instead, to avoid clashes with Spring's own ${...}.

Common mistakes

  • Using a property before defining it, or misspelling its name; the unresolved ${...} text appears in an error.
  • Forgetting project.build.sourceEncoding, and getting different bytes on different machines.
  • Setting maven.compiler.source and target only, and so allowing newer APIs by accident.
  • Defining a property in a child POM and expecting the parent to see it. Parents never see child values; children inherit from parents. See Parent POMs and the Effective POM.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. A POM contains <version>${junit.versoin}</version> but only junit.version is defined. What does Maven do with the misspelled reference?

    Maven only replaces names it knows. An unknown name stays as literal text, which usually shows up in an error message about an invalid version.
  2. 2. The POM sets <junit.version>5.11.4</junit.version> and you run mvn test -Djunit.version=6.0.0. Which value is used?

    User properties given with -D take priority over properties defined in the POM, which makes per-run overrides easy.
  3. 3. Why is maven.compiler.release preferred over maven.compiler.source plus maven.compiler.target?

    release maps to javac --release, which sets language level, bytecode level and the API signatures. source and target do not stop you from calling newer JDK methods.
  4. 4. What problem does project.build.sourceEncoding solve?

    Without it, plugins use the platform default encoding, so accented characters can be read differently on different machines.

Summary

  • Properties are named values defined in <properties> and used as ${name}; unknown names stay as literal text.
  • Built-in families include project.*, project.basedir, env.*, settings.* and Java system properties.
  • Command-line -D values override properties in the POM.
  • Always set project.build.sourceEncoding to UTF-8.
  • Use maven.compiler.release (for example 25) instead of source and target.
  • Filtering of resource files is opt-in. The resolver and encoding demos above are stand-ins for Maven's internals.

Next, see how properties and everything else are inherited: Parent POMs and the Effective POM.