Configurable JDK Versions for JVM Options

Since Payara Server 5.182

It is possible to allow specific JVM options configured for a Payara Server Enterprise instance to be applied only on specific JDK versions. The configuration is flexible since it allows the user to define minimum and maximum versions of all JDKs upon which each JVM option should be applied.

If no minimum and/or maximum JDK versions are set for a particular JVM option, it shall be applied no matter which JDK is being used to run the server’s instance (which is the default behaviour).

Versioning Syntax

JDK versions must follow the standard JDK versioning scheme (1.$MAJOR.$MINOR.$UPDATE). The syntax that can be used is a bit flexible, allowing the following variants to be correctly interpreted:

  • 1.8.0.162

  • 1.8.0u162

  • 1.8.0

  • 1.8

Configuring JDK Versions

JDK Versions for JVM Options can be configured in three different ways: Using the admin console or running asadmin commands from a console terminal.

Using the Admin Console

To configure the JDK versions for JVM options in the admin console, head to the Configurations → <instance configuration> → JVM Settings and on the JVM Options tab specify the versions in the table:

Configure JDK versions for JVM options in Admin console

You can omit either the minimum or maximum versions by leaving the fields blank.

Using Asadmin commands

JVM options can be configured using the 'create-jvm-options' asadmin command. The jvm option key value pair must be enclosed in quotation marks as follows: asadmin create-jvm-options --target=server-config "-Djava.awt.headless\=true"

The create-jvm-options asadmin command has been modified to set the miminum and maximum JDK versions in the following ways:

  1. Use the --min-jvm and --max-jvm arguments to set the versions when running the command:

    asadmin create-jvm-options --target=server-config --min-jvm=1.8.0u162 "-Djava.awt.headless\=true"
    
    asadmin create-jvm-options --target=server-config --max-jvm=1.8.0u172 "-XX\:+UnlockDiagnosticVMOptions"
    When using these arguments to set multiple JVM options, the specified versions will be applied for each option.
  2. Specify the versions using the [MIN_VERSION | MAX_VERSION] text syntax for the inclusive version range before each JVM option:

    asadmin create-jvm-options --target=server-config "[1.8.0u162|]-Djava.awt.headless\=true"
    
    asadmin create-jvm-options --target=server-config "[|1.8.0u172]-XX\:+UnlockDiagnosticVMOptions"
    
    asadmin create-jvm-options --target=server-config "[1.8.0u168|1.8.0u172]-XX\:NewRatio\=2"

    You can specify the range for each JVM option when specifying multiple options too:

    asadmin create-jvm-options --target=server-config "-Djava.awt.headless\=true:[|1.8.0u172]-XX\:+UnlockDiagnosticVMOptions:[1.8.0u168|1.8.0u172]-XX\:NewRatio\=2"

Multimode double escaping

Since Payara Server 5.193

When creating JVM options in the multimode of asadmin, you need to perform a double escaping of the values.

So first, start up asadmin in multimode.

asadmin

Execute the create_jvm_options but perform a double escaping of the special characters. Otherwise, the command fails with the error "JVM option …​ is invalid because it does not start with a '-'".

asadmin> create-jvm-options "-XX\\:MaxPermSize=512m"

Deleting JVM Options

Deleting JVM options is done using either the Admin Console, or the delete-jvm-options asadmin command. It is not required for you to specify the JDK version braces for deleting a JVM option, though you can if you wish.

For example, given the option "[1.8.0.160|1.8.0.200]XX\:NewRatio=3", either of the following will work:

asadmin> delete-jvm-options "XX\:NewRatio=3"
asadmin> delete-jvm-options "[1.8.0.160|1.8.0.200]XX\:NewRatio=3"