Setting Java Version used by Maven Compiler

The Java version of a Maven project is set with properties of the Maven compiler plugin, which decide the language level of the source code and the bytecode version of the compiled classes. The properties maven.compiler.source, maven.compiler.target and maven.compiler.release configure this plugin, and Spring Boot projects use the property java.version. This tutorial covers each approach, the pitfall of a version mismatch and the default Java version of Spring Boot.

1. Using the Maven Compiler Plugin

The Java version of the project is set with the properties of the Maven compiler plugin. The following configuration compiles the project using Java 17.

• maven.compiler.source allows the language features of Java 17 and earlier versions in the source code.
• maven.compiler.target generates compiled classes that are compatible with Java 17. The application runs on Java 17 and later versions, but not on earlier versions.

The default value for both properties is Java 1.8 in the latest version of the Maven compiler plugin.

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
    ...

	<properties>
	    <maven.compiler.source>17</maven.compiler.source>
	    <maven.compiler.target>17</maven.compiler.target>
	</properties>

	...
</project>

We can also set the same values in the configuration of the compiler plugin.

<?xml version="1.0" encoding="UTF-8"?>
<project ...>
    ...

	<plugins>
	    <plugin>    
	        <artifactId>maven-compiler-plugin</artifactId>
	        <configuration>
	            <source>17</source>
	            <target>17</target>
	        </configuration>
	    </plugin>
	</plugins>

	...
</project>

Avoid Pitfall due to Version Mismatch

Setting the target option does not guarantee that the application runs on a JRE with the specified version. If the source option is set to a later version and the code uses new language features, the code fails at runtime with a linkage error.

The following configuration sets source to Java 17 and target to Java 11.

<properties>
	<maven.compiler.source>17</maven.compiler.source>
	<maven.compiler.target>11</maven.compiler.target>
</properties>

If the code uses language features that are specific to Java 17 (such as Sealed Classes), the project fails with a linkage error at runtime.

2. Cross-Compilation Support Since Java 9

As the previous section shows, the attributes source and target do not guarantee that the application runs on an older JDK version.

The property maven.compiler.release enables cross-compilation, so the application runs on older Java versions.

<properties>
    <maven.compiler.release>8</maven.compiler.release>
</properties>

We can also write the same configuration with the release attribute in the configuration of the Maven compiler plugin.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.8.0</version>
    <configuration>
        <release>8</release>
    </configuration>
</plugin>

Cross-compilation requires Java 9 or later on the machine. We can check the Java version used by Maven with the command mvn -v. Maven uses the JAVA_HOME environment variable to find the Java version that runs Maven.

mvn -v

Apache Maven 3.8.1 (05c21c65bdfed0f71a2f2ada8b84da59348c4c5d)
Maven home: C:\devsetup\maven\bin\..
Java version: 19-loom, vendor: Oracle Corporation, runtime: C:\devsetup\JDKs\jdk19
Default locale: en_IN, platform encoding: UTF-8
OS name: "windows 11", version: "10.0", arch: "amd64", family: "windows"

3. Set Java Version in a Spring Boot Project

The Spring Boot applications use the property java.version to compile the source code of the project. The property java.version is specific to Spring Boot.

We set the property java.version in the pom.xml file.

<properties>
    <java.version>17</java.version>
</properties>

If we do not define the property java.version, Spring Boot reads its value from the starter POM file.

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
</parent>

• The default and minimum Java version for Spring Boot 2.x projects is Java 1.8.
• The default and minimum Java version for Spring Boot 3.x projects is Java 17.

4. Changing the Java Version from Command Line

If the pom.xml file does not override the Java version, Maven uses its default Java version. We can still compile the project with a different Java version by changing the JAVA_HOME environment variable in the command prompt and then building the application binary with the mvn build command.

JAVA_HOME=/path/to/jdk17/ mvn build

5. Conclusion

We can summarize the Java version settings as follows.

• Use the property java.version to configure the Java version of a Spring Boot application.
• Use the properties maven.compiler.source and maven.compiler.target for other Java applications.
• Use the property maven.compiler.release for cross-compilation, because source and target do not guarantee that the application runs on older Java versions.

Happy Learning !!