1. Introduction
JDK_JAVA_OPTIONS and JAVA_TOOL_OPTIONS are environment variables used to pass Java Virtual Machine (JVM) options to configure the JVM without modifying the scripts. In this article, I will demonstrate the JVM options configuration between JDK_JAVA_OPTIONS vs JAVA_TOOL_OPTIONS via the command line interface (CLI).
2. What is JDK_JAVA_OPTIONS?
JDK 9 introduced JDK_JAVA_OPTIONS that prepends its content to the options parsed from the CLI arguments passed to the Java launcher. The content of the JDK_JAVA_OPTIONS environment variable is a list of arguments separated by white-space characters and is treated as same as any other CLI arguments.
Single (') or double (") quotes can be used to enclose arguments that contain whitespace characters. In case a matching quote is not found, the launcher will abort with an error message.
@-files are supported as they are specified in the command line. However, a wildcard is not supported. To mitigate potential misuse of JDK_JAVA_OPTIONS behavior, options that specify the main class (such as -jar) or cause the java launcher to exit without executing the main class (such as -h) are disallowed in the environment variable. If any of these options appear in the environment variable, the launcher will abort with an error message. When JDK_JAVA_OPTIONS is set, the launcher prints a message as a reminder.
Figure 1 shows the environment variable for JDK_JAVA_OPTIONS .
2.1 Java with JDK_JAVA_OPTIONS Example
In this step, I will demonstrate a simple Java -version command when JDK_JAVA_OPTIONS is defined.
JDK_JAVA_OPTIONS with java -version
01 02 03 04 05 06 07 08 09 10 11 12 | C:\Users\azpm0>java -versionopenjdk version "17" 2021-09-14OpenJDK Runtime Environment (build 17+35-2724)OpenJDK 64-Bit Server VM (build 17+35-2724, mixed mode, sharing)C:\Users\azpm0>set JDK_JAVA_OPTIONS="-Xms1g"C:\Users\azpm0>java -versionNOTE: Picked up JDK_JAVA_OPTIONS: "-Xms1g"openjdk version "17" 2021-09-14OpenJDK Runtime Environment (build 17+35-2724)OpenJDK 64-Bit Server VM (build 17+35-2724, mixed mode, sharing) |
- Line 6: set
JDK_JAVA_OPTIONSto-Xms1g. It configures Java processes with-Xms1gJVM options. - Line 9:
NOTE: Picked up JDK_JAVA_OPTIONS: "-Xms1g". It prints out the JVM options defined by theJDK_JAVA_OPTIONSenvironment variable. - Line 10: print out the JDK version: 17.
2.2 Invalid JDK_JAVA_OPTIONS Example
In this step, I will demonstrate a simple Java -version command with an invalid JDK_JAVA_OPTIONS.
Invalid JDK_JAVA_OPTIONS with java -version
1 2 3 4 5 6 7 8 9 | C:\Users\azpm0>C:\Users\azpm0>set JDK_JAVA_OPTIONS="-Xms2gbad"C:\Users\azpm0>java -versionNOTE: Picked up JDK_JAVA_OPTIONS: "-Xms2gbad"Invalid initial heap size: -Xms2gbadError: Could not create the Java Virtual Machine.Error: A fatal exception has occurred. Program will exit.C:\Users\azpm0> |
- Line 5: detects the JVM option defined in the
JDK_JAVA_OPTIONSis invalid. - Line 6-7: Error is printed and the
java -versioncommand is not started.
2.3 No JDK_JAVA_OPTIONS Example
In this step, I will demonstrate a simple Java -version command without any JDK_JAVA_OPTIONS.
No JDK_JAVA_OPTIONS with java -version
1 2 3 4 5 6 | C\Users\azpm0>C:\Users\azpm0>set JDK_JAVA_OPTIONS=C:\Users\azpm0>java -versionopenjdk version "17" 2021-09-14OpenJDK Runtime Environment (build 17+35-2724)OpenJDK 64-Bit Server VM (build 17+35-2724, mixed mode, sharing) |
- Line 1: delete the
JDK_JAVA_OPTIONSby setting it to empty. - Line 4: the
java versioncommand is executed successfully.
2.4 Gradle With JDK_JAVA_OPTIONS Example
In this step, I will execute the gradle command with JDK_JAVA_OPTIONS for the example I built.
JDK_JAVA_OPTIONS with gradle command
1 2 3 4 5 6 7 8 | C:\MaryTools\workspace\postgresDateDemo>set JDK_JAVA_OPTIONS='-Xms1g'C:\MaryTools\workspace\postgresDateDemo>gradlew javadocNOTE: Picked up JDK_JAVA_OPTIONS: '-Xms1g'BUILD SUCCESSFUL in 2s3 actionable tasks: 3 up-to-dateC:\MaryTools\workspace\postgresDateDemo> |
- Line 1: set the
JDK_JAVA_OPTIONSvalue. - Line 4:
gradlew javadocis executed successfully with the ‘-Xms1g‘ option.
3. What is JAVA_TOOL_OPTIONS?
The earlier version of JDK ( before JDK 9 ) defines the JAVA_TOOL_OPTIONS environment variable that is appended to the CLI arguments to specify the initialization of tools, specifically the launching of native or Java programming language agents using the -agentlib or -javaagent options. It’s recognized by both JVM and Java tools ( java, javac, and javadoc ).
3.1 Java with JAVA_TOOL_OPTIONS Example
In this step, I will demonstrate a simple Java -version command with JAVA_TOOL_OPTIONS.
JAVA_TOOL_OPTIONS with java -version
1 2 3 4 5 6 | C:\Java\jdk8\bin>set JAVA_TOOL_OPTIONS="-Xms1g"C:\Java\jdk8\bin>java -versionjava version "1.8.0_361"Java(TM) SE Runtime Environment (build 1.8.0_361-b26)Java HotSpot(TM) 64-Bit Server VM (build 25.361-b26, mixed mode) |
- Line 1: the
JAVA_TOOL_OPTIONSis set to-Xms1g. - Line 4: the Java version
1.8.0_361is printed out.
3.2 Invalid JAVA_TOOL_OPTIONS Example
In this step, I will demonstrate a simple Java -version command with an invalid JAVA_TOOL_OPTIONS.
Invalid JAVA_TOOL_OPTIONS with java -version
1 2 3 4 5 6 7 | C:\Java\jdk8\bin>set JAVA_TOOL_OPTIONS='bad' C:\Java\jdk8\bin>java -versionUnrecognized option: badError: Could not create the Java Virtual Machine.Error: A fatal exception has occurred. Program will exit.C:\Java\jdk8\bin> |
- Line 4: the
JAVA_TOOL_OPTIONSis detected as a “unrecognized option”. - Line 5-6: Error is printed out. Program exits.
3.3 No JAVA_TOOL_OPTIONS Example
Same as step 2.3, I will delete the invalid JAVA_TOOL_OPTIONS by setting it to empty.
No JAVA_TOOL_OPTIONS with java -version
1 2 3 4 5 6 | C:\Java\jdk8\bin>set JAVA_TOOL_OPTIONS= C:\Java\jdk8\bin>java -versionjava version "1.8.0_361"Java(TM) SE Runtime Environment (build 1.8.0_361-b26)Java HotSpot(TM) 64-Bit Server VM (build 25.361-b26, mixed mode)C:\Java\jdk8\bin> |
- Line 1: the
JAVA_TOOL_OPTIONSis cleared. - Line 4:
java -versioncommand executed successfully.
4. Differences Between JDK_JAVA_OPTIONS vs JAVA_TOOL_OPTIONS
Here are the key differences between JDK_JAVA_OPTIONS and JAVA_TOOL_OPTIONS based on the exercises outlined in step 2 and step 3:
| Feature | JDK_JAVA_OPTIONS | JAVA_TOOL_OPTIONS |
| JDK version | Since JDK 9 | Prior JDK 9 |
| Applied to | only java launchers | JVM and Java tools |
| CLI Order | Prepended to CLI arguments | Appended to CLI arguments |
5. JDK_JAVA_OPTIONS vs JAVA_TOOL_OPTIONS Usages
Recommend using JDK_JAVA_OPTIONS for JDK 9+ with stricter JVM option enforcement. If any of the options is invalid for any Java processes, then don’t include it as these JVM options apply to all the Java processes in that environment. JDK_JAVA_OPTIONS and JAVA_TOOL_OPTIONS are useful when you are certain that all Java processes need to be enforced with the same JVM options configuration. Here are common usages of these environment variables:
- CI/CD – ensure JVM options ( e.g. memory size) are applied consistently across different builds without modifying
Jenkinsfile,bamboo-specs, and scripts. - Enterprise – admin to enforce JVM setting for all Java applications without modifying each script.
- Cloud/Docker – avoid long command-line options in Kubernetes or Docker.
6. Conclusion
In this article, I compared the JVM options configuration between JDK_JAVA_OPTIONS vs JAVA_TOOL_OPTIONS via CLI examples. If developing in JDK 9+, then recommend JDK_JAVA_OPTIONS for global JVM configuration options.
