One of many strengths of Java platform is its backward compatibility with the language. As language keeps evolving and moving forward, the good old syntax is still supported for backward compatibility. However, the compiler adds certain indicative options for specifying version details. The --source, --target are two such compiler (javac) options. From Java 9 onwards a third option --release got added to this mix. Getting a good understanding of these options is not trivial without actually experiencing all three. When compiling source code of a single class you may not need to specify these options. But in Java project when building with maven like build system, one needs to understand these options and their implications.
Environment: Java 20, Spring Boot 2.7.15, maven 3.9.3 on macOS Catalina 10.15.7
The maven-compiler-plugin
Maven build system uses maven-compiler-plugin for compiling source code. This plugin documentation upfront talks about source and target options and highly recommends to change these in plugin configuration. In order to change these per application/module needs, one needs to look under the hood for understanding.
Various extra Java compiler options can be specified in the maven-compiler-plugin configuration. The actual Java compiler options related to version are: --source, --target and --release that can be specified and passed to the compiler during code compilation through maven-compiler-plugin configuration. This can be done in two different ways in pom.xml:
1. Through maven properties: maven.compiler.source, maven.compiler.target and maven.compiler.release as highlighted below:
<properties>
<maven.compiler.source>20</maven.compiler.source>
<maven.compiler.target>20</maven.compiler.target>
<maven.compiler.target>20</maven.compiler.target>
</properties>
If these properties are not explicitly defined, maven compiler plugin uses 1.8 for source and target.
...
<properties>
<java.version>20</java.version>
<javac.source.version>${java.version}</javac.source.version>
<javac.target.version>${java.version}</javac.target.version>
<javac.release.version>${java.version}</javac.release.version>
<!-- Maven plugins -->
<maven-compiler-plugin.version>3.11.0</maven-compiler-plugin.version>
</properties>
<build>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>${maven-compiler-plugin.version}</version>
<configuration>
<source>${javac.source.version}</source>
<target>${javac.target.version}</target>
<release>${javac.release.version}</release>
<compilerArgs>
<arg>-Xlint:all</arg>
</compilerArgs>
</configuration>
</plugin>
</plugins>
</pluginManagement>
...
If no special configuration is required, it doesn't require even to specify maven-compiler-plugin. If specified, the above are two ways to control/change default 1.8 set by the plugin for these options which eventually get passed to the Java compiler (javac) during code compilation of sources (both under src and test.
Note from Java 9 onwards, the values to these options are not like 1.7, 1.8 but must be 7 and 8.
Java 20
Java 20 compiler doesn't support version 7 for source, target anymore. The supported releases are 8 through 20. So, for any reason if maven compiler plugin is set explicitly with 1.7, build fails with ERRORS saying: Source option 7 is no longer supported. Use 8 or later. , and Target option 7 is no longer supported. Use 8 or later.
Now it's time to understand what these options actually tell the compiler, javac. The compiler's help option (javac -help) lists all available options and a brief description about each option. The -source, -target, -release options descriptions are helpful to some extent.
--source <release>, -source <release>
Provide source compatibility with the specified Java SE release. Supported releases: 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20
--target <release>, -target <release>
Generate class files suitable for the specified Java SE release. Supported releases: 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20
--release <release>
Compile for the specified Java SE release. Supported releases: 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20
To understand these compiler options better, we can compile a simple Java application class with just main method.
import java.util.Properties;
public class HelloJava {
public static void main(String[] args) {
Properties systemProperties = System.getProperties();
System.out.println(String.format("Hello Java %s!", systemProperties.getProperty("java.vm.specification.version")));
systemProperties.entrySet().stream()
.filter(entry -> entry.getKey().toString().startsWith("java"))
.toList().stream()
.forEach(entry ->
System.out.println(entry.getKey() + "=" + systemProperties.getProperty(entry.getKey().toString()))
);
}
}
Note - The above class prints system properties that start with "java" with their values. It uses toList() method that Java 16 added to Stream class. With this the expectation is- the code should not be compiled for Java/JVM version less than 16.Java compiler version options
Let's compile the class with different Java versions and compiler options.
// compile with Java 20: no options specified
$ sdk use java 20.0.2-amzn
// check: major version
$ javap -verbose HelloJava.class | grep major
major version: 64
// run on Java 20: works
$ javac HelloJava.java
"Hello Java 20!"
// switch to Java 17 and run: fails with LinkageError
$ sdk use java 17.0.1.12.1-amzn
$ java HelloJava
Error: LinkageError occurred while loading main class HelloJava
java.lang.UnsupportedClassVersionError: HelloJava has been compiled by a more recent version of the Java Runtime (class file version 64.0), this version of the Java Runtime only recognizes class file versions up to 61.0
// switch to Java 15 and run: fails with LinkageError
$ sdk use java 15.0.2.7.1-amzn
$ java HelloJava
Error: LinkageError occurred while loading main class HelloJava
java.lang.UnsupportedClassVersionError: HelloJava has been compiled by a more recent version of the Java Runtime (class file version 64.0), this version of the Java Runtime only recognizes class file versions up to 59.0
// switch to Java 8 and run: fails with UnsupportedClassVersionError Exception
$ sdk use java 8.0.352-amzn
$ java HelloJava
Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main" java.lang.UnsupportedClassVersionError: HelloJava has been compiled by a more recent version of the Java Runtime (class file version 64.0), this version of the Java Runtime only recognizes class file versions up to 52.0
at java.lang.ClassLoader.defineClass1(Native Method)
at java.lang.ClassLoader.defineClass(ClassLoader.java:756)
at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142)
at java.net.URLClassLoader.defineClass(URLClassLoader.java:473)
at java.net.URLClassLoader.access$100(URLClassLoader.java:74)
at java.net.URLClassLoader$1.run(URLClassLoader.java:369)
at java.net.URLClassLoader$1.run(URLClassLoader.java:363)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(URLClassLoader.java:362)
at java.lang.ClassLoader.loadClass(ClassLoader.java:418)
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:352)
at java.lang.ClassLoader.loadClass(ClassLoader.java:351)
at sun.launcher.LauncherHelper.checkAndLoadMain(LauncherHelper.java:601)
So. when compiled with a specific version of java compiler (in this case Java 20 and no version options are specified), it gets compiled with default target of the Java compiler which is 20. The class generated cannot be run on prior JVM versions (prior to 20). To find the target of JVM code the byte-code is generated for, use javap -verbose HelloJava.class | grep major.
Now, let's try compiling for target 17 and try to run on different JVM versions.
// compile with Java 20 for target 17: --source and --target options specified
$ sdk use java 20.0.2-amzn
$ javac --source=17 --target=17 HelloJava.java
warning: [options] system modules path not set in conjunction with -source 17
1 warning
// check: major version
$ javap -verbose HelloJava.class | grep major
major version: 61
// run on Java 20: works
$ java HelloJava
Hello Java 20!
// switch to Java 17 and run: works
$ sdk use java 17.0.1.12.1-amzn
// run on Java 17: works
$ java HelloJava
Hello Java 17!
// swicth to Java 15 and run: fails with LinkageError
$ sdk use java 15.0.2.7.1-amzn
$ java HelloJava
Error: LinkageError occurred while loading main class HelloJava
java.lang.UnsupportedClassVersionError: HelloJava has been compiled by a more recent version of the Java Runtime (class file version 61.0), this version of the Java Runtime only recognizes class file versions up to 59.0
// compile with Java 20 for target 17: --source and --target options specified
$ sdk use java 20.0.2-amzn
$ javac --source=15 --target=15 HelloJava.java
warning: [options] system modules path not set in conjunction with -source 15
1 warning
// check: major version
$ javap -verbose HelloJava.class | grep major
major version: 59
// switch to Java 17 and run: works
$ sdk use java 17.0.1.12.1-amzn
$ java HelloJava
Hello Java 17!
// swicth to Java 15 and run: fails with NoSuchMethodError
$ sdk use java 15.0.2.7.1-amzn
$ java HelloJava
Hello Java 15!
Exception in thread "main" java.lang.NoSuchMethodError: 'java.util.List java.util.stream.Stream.toList()'
at HelloJava.main(HelloJava.java:15)
// switch to Java 8 and run: fais with UnsupportedClassVersionError
$ sdk use java 8.0.352-amzn
$ java HelloJava
Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main" java.lang.UnsupportedClassVersionError: HelloJava has been compiled by a more recent version of the Java Runtime (class file version 59.0), this version of the Java Runtime only recognizes class file versions up to 52.0
at java.lang.ClassLoader.defineClass1(Native Method)
at java.lang.ClassLoader.defineClass(ClassLoader.java:756)
at java.security.SecureClassLoader.defineClass(SecureClassLoader.java:142)
at java.net.URLClassLoader.defineClass(URLClassLoader.java:473)
at java.net.URLClassLoader.access$100(URLClassLoader.java:74)
at java.net.URLClassLoader$1.run(URLClassLoader.java:369)
at java.net.URLClassLoader$1.run(URLClassLoader.java:363)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(URLClassLoader.java:362)
at java.lang.ClassLoader.loadClass(ClassLoader.java:418)
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:352)
at java.lang.ClassLoader.loadClass(ClassLoader.java:351)
at sun.launcher.LauncherHelper.checkAndLoadMain(LauncherHelper.java:601)
// compile with Java 20 for target 8: --source and --target options specified
$ sdk use java 20.0.2-amzn
$ javac --source=8 --target=8 HelloJava.java
javac --source=8 --target=8 HelloJava.java
warning: [options] bootstrap class path not set in conjunction with -source 8
warning: [options] source value 8 is obsolete and will be removed in a future release
warning: [options] target value 8 is obsolete and will be removed in a future release
warning: [options] To suppress warnings about obsolete options, use -Xlint:-options.
4 warnings
// check: major version
$ javap -verbose HelloJava.class | grep major
major version: 52
// switch to Java 20 and run: works
$ sdk use java 20.0.2-amzn
$ java HelloJava
Hello Java 20!
// switch to Java 17 and run: works
$ sdk use java 17.0.1.12.1-amzn
$ java HelloJava
Hello Java 17!
// swicth to Java 15 and run: fails with NoSuchMethodError
$ sdk use java 15.0.2.7.1-amzn
$ java HelloJava
Hello Java 15!
Exception in thread "main" java.lang.NoSuchMethodError: 'java.util.List java.util.stream.Stream.toList()'
at HelloJava.main(HelloJava.java:15)
So, when compiled for a target version, it cannot be run on prior JVM versions.
Let's try target 7.
$ sdk use java 20.0.2-amzn
$ javac --source=7 --target=7 HelloJava.java
warning: [options] bootstrap class path not set in conjunction with -source 7
error: Source option 7 is no longer supported. Use 8 or later.
error: Target option 7 is no longer supported. Use 8 or later.
Java version 7 is not supported anymore.Let's experience --release option.
// compile with Java 20 using options --source and --target options specified
$ sdk use java 20.0.2-amzn
$ javac --source=17 --target=17 --release=17 HelloJava.java
error: option --source cannot be used together with --release
error: option --target cannot be used together with --release
Usage: javac <options> <source files>
use --help for a list of possible options
// compile with Java 20 for target 17: --release options specified
$ sdk use java 20.0.2-amzn
$ javac --release=17 HelloJava.java
// check: major version
$ javap -verbose HelloJava.class | grep major
major version: 61
// switch to Java 20 and run: works
$ sdk use java 20.0.2-amzn
$ java HelloJava
Hello Java 20!
// switch to Java 17 and run: works
$ sdk use java 17.0.1.12.1-amzn
$ java HelloJava
Hello Java 17!
// switch to Java 15 and run: fails with NoSuchMethodError
$ sdk use java 15.0.2.7.1-amzn
$ java HelloJava
Hello Java
Exception in thread "main" java.lang.NoSuchMethodError: 'java.util.List java.util.stream.Stream.toList()'
at HelloJava.main(HelloJava.java:14)
// compile with Java 20 for target 15: --release options specified
$ sdk use java 20.0.2-amzn
$ javac --release=15 HelloJava.java
HelloJava.java:14: error: cannot find symbol
.toList().stream()
^
symbol: method toList()
location: interface Stream<Entry<Object,Object>>
1 error
// compile with Java 20 for target 15: --source --target options specified
$ sdk use java 20.0.2-amzn
$ javac --source=15 --target=15 HelloJava.java
warning: [options] system modules path not set in conjunction with -source 15
1 warning
// switch to Java 15 and run: fails with NoSuchMethodError
$ sdk use java 15.0.2.7.1-amzn
$ java HelloJava
Exception in thread "main" java.lang.NoSuchMethodError: 'java.util.List java.util.stream.Stream.toList()'
at HelloJava.main(HelloJava.java:14)
So, --release option does a strict compilation time checks to see if the code is compliant with the release target and fails to compile if a method not supported in target version is used in the code. This makes sure the compiled class works on target release (the target JVM version that the code is released to run on). Whereas, the --target option doesn't do code compliance checks during compilation time, it simply compiles code but fails during runtime. So, --release seems like better option to leverage when specifying.
Implications of version options
- No compiler options specified: The code gets compiled with default target as the version of the Java compiler.
- All 3 options --source, --target and --release specified: Not allowed.
- Options --source, --target specified: 1) Both can be same (e.g. 17, 17). 2) The option: --source can be lower version (e.g. 15) and --target can be higher version (e.g. 17), but not the other way. If --source is higher version (e.g.17) and --target is lower version (e.g.15), compiler fails with a warning: warning: source release 17 requires target release 17, it doesn't get compiled.
- Only option --source: The option --source can be any version but default target would be the version of Java compiler being used.
- Only option --target: The option: --target cannot be lower than the version of Java compiler being used because default source would be the version of the compiler being used. A lower target version gets into compiler option source higher, target lower and fails compilation. E.g javac --target=19 HelloJava.java with Java 20 compiler fails with warning: target release 19 conflicts with default source release 20 and code doesn't get compiled.
- Only option --release: Strict code check during compilation to make sure that compiled code gets compiled and works on the target version. Also, the byte-code generated runs only on the release specified and higher, but doesn't run on any lower versions.
- Compiling using Java 20, and no --release option or --release=20 results with major version 64 (Java 20).
- Compiling using Java 20 with --release=19 results with major version 63 (Java 19).
- Compiling using Java 20 with --release=17 results with major version 61 (Java 17) and would result with LinkageError when run on lower version other than 17. Works on 17 and higher.
The maven-compiler-plugin variations with these options
Maven, out of the box with no maven-compiler-plugin specified in pom.xml, has the following variations with it's compiler version option properties (maven.compiler.source, maven.compiler.target and maven.compiler.release).
<properties>
<maven.compiler.source>20</maven.compiler.source>
<maven.compiler.target>20</maven.compiler.target>
<maven.compiler.release>20</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
- No version properties are specified: (No maven.compiler.source, maven.compiler.target and maven.compiler.release properties): Build fails with compilation ERRORS: Source option 5 is no longer supported. Use 8 or later. and Target option 5 is no longer supported. Use 8 or later.
- All 3 version properties are specified: The option: maven.compiler.release is ignored, it can be any junk. Only source and target properties matter. The value for target option cannot be less than the source. For instance, source 20, target 19 fails build with warning: source release 20 requires target release 20.
- Only source version property is specified: When only source is specified, target must also be specified. Otherwise, maven build fails with: Fatal error compiling: warning: source release 20 requires target release 20
- Only target version property is specified: When only target is specified, source must also be specified. Otherwise, maven build fails with: Source option 5 is no longer supported. Use 8 or later.
- The release property specified: When release is specified and is 8 or later, this takes the precedence. Make a special NOTE of it. When release is specified, it takes the precedence and source, target options are ignored. In this case, any non-sense value will make the build work and code gets compiled for the release version specified. But this must be 8 or later.
With maven-compiler-plugin specified in pom.xml, has the following variations with these options specified in the plugin configuration (<configuration>):
<properties>
<maven.compiler.source>20</maven.compiler.source>
<maven.compiler.target>20</maven.compiler.target>
<maven.compiler.release>20</maven.compiler.release>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
...
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>3.11.0</version>
<configuration>
<source>20</source>
<target>20</target>
<release>20</release>
</configuration>
</plugin>
</plugins>
</build>
With the above way of having both defined set of properties, and maven-compiler-plugin configuration, the configuration values override the property values defined. If no configuration is specified for the maven-compiler-plugin, it uses the set of properties defined. With configuration <source>, <target>, and <release> taking the precedence, the variations are as follows:
- No <configuration> specified for the plugin, but set of properties are defined: It uses defined set of properties if exist, release takes the precedence over target and source.
- No properties are defined, and no <configuration> is specified for the plugin : It defaults to target 1.8.
- All 3 configuration options are specified: The release configuration takes the precedence and is built for the release version.
- No properties are set, and only source configuration option is specified: When only source is specified, target must also be specified. Otherwise, maven build fails with: Fatal error compiling: warning: source release 20 requires target release 20
- No properties are set, and only target configuration option is specified: Code gets compiled for the target specified.
- No properties are set, and both target and release configuration options are specified: The release option takes the precedence and code gets compiled for the release specified.
Summary
For Java 9 and after, use --release option.
For older versions prior to Java 9 use --source and --target options.
TIPS
- Use SDKMAN to install multiple Java versions and easily switch between different versions.
- If You see noisy warning: Using deprecated '-debug' fallback for parameter name resolution. Compile the affected code with '-parameters' instead or avoid its introspection:, then add compiler argument <arg>-parameters</arg> to the maven-compiler-plugin configuration as shown below:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>${maven-compiler-plugin.version}</version>
<configuration>
<source>${javac.source.version}</source>
<target>${javac.target.version}</target>
<release>${javac.release.version}</release>
<compilerArgs>
<arg>-Xlint:all</arg>
<arg>-parameters</arg>
</compilerArgs>
</configuration>
</plugin>
Posts
No comments:
Post a Comment