jvm - What is the difference between JDK_JAVA_OPTIONS and JAVA_TOOL_OPTIONS when using Java 11?

Question

What is the exact difference between JDK_JAVA_OPTIONS and JAVA_TOOL_OPTIONS when using Java 11?

I'm using a tiny test program:

public class Foo {
  public static final void main(String[] args) {
    System.out.println("arg: " + System.getProperty("arg"));
  }
}

The two environment variables seem to do the same, but the output is slightly different. That makes me believe they might have different use cases:

$ JDK_JAVA_OPTIONS="-Darg=jdk" java Foo
NOTE: Picked up JDK_JAVA_OPTIONS: -Darg
arg: jdk

$ JAVA_TOOL_OPTIONS="-Darg=tool" java Foo
Picked up JAVA_TOOL_OPTIONS: -Darg
arg: tool

$ JDK_JAVA_OPTIONS="illegalArg" java Foo
NOTE: Picked up JDK_JAVA_OPTIONS: illegalArg
Error: Cannot specify main class in environment variable JDK_JAVA_OPTIONS

$ JAVA_TOOL_OPTIONS="illegalArg" java Foo
Picked up JAVA_TOOL_OPTIONS: illegalArg
Unrecognized option: illegalArg
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.

It seems like JDK_JAVA_OPTIONS have precedence over JAVA_TOOL_OPTIONS:

$ JDK_JAVA_OPTIONS="-Darg=jdk" JAVA_TOOL_OPTIONS="-Darg=tool" java Foo
NOTE: Picked up JDK_JAVA_OPTIONS: -Darg=jdk
Picked up JAVA_TOOL_OPTIONS: -Darg=tool
arg: jdk

But ultimately the command line wins:

$ JDK_JAVA_OPTIONS="-Darg=jdk" JAVA_TOOL_OPTIONS="-Darg=tool" java -Darg=cmd Foo
NOTE: Picked up JDK_JAVA_OPTIONS: -Darg=jdk
Picked up JAVA_TOOL_OPTIONS: -Darg=tool
arg: cmd

When building, though, only JAVA_TOOL_OPTIONS is read:

$ JDK_JAVA_OPTIONS="-Darg=jdk" JAVA_TOOL_OPTIONS="-Darg=tool" javac Foo.java
Picked up JAVA_TOOL_OPTIONS: -Darg=tool

I'm currently using AdoptOpenJDK 11 build 28.

Answer 1

• JDK_JAVA_OPTIONS is only picked up by the java launcher, so use it for options that you only want to apply (or only make sense for) the java startup command. This variable is also new on JDK 9+, and will be ignored by earlier JDK versions. Hence, it's useful when migrating from older versions to 9+.
• JAVA_TOOL_OPTIONS is picked up also by other java tools like jar and javac so it should be used for flags that you want to apply (and are valid) to all those java tools.