System Installation: Required command-line options for Java 21
With the upgrade to Java 21 in FNZ Studio 2025, you need to take further installation information into account.
Quick instructions for Apache Tomcat
- Download the file jvm-options-java-21.txt to every server where FNZ Studio is installed.
- Store the file in the "conf" directory of your Tomcat installation.
- Make sure that the Tomcat user has read access to this file.
- Add the following line to the file "setenv.sh" in Tomcat's "bin" directory:
JDK_JAVA_OPTIONS=@/opt/tomcat/conf/jvm-options-java-21.txtAdapt the absolute file path to your installation.
Introduction
Many features in FNZ Studio depend on the ability to introspect object instances of Java core classes and JDK internal classes using Java's Reflection API. In addition, Java application servers like Apache Tomcat and third-party Java libraries like Hazelcast use reflective access to improve their performance.
Unfortunately, reflective access to such classes has been restricted in Java 17. By default, every attempt to use reflection to access members of such a class leads to an IllegalAccessException. In order to have reflective access to a given class, a special command-line option has to be used to "open" the Java package of this class. Every command-line option grants access to classes from one Java package.
FNZ Studio alone needs access to classes from 30+ Java packages, and extensions can come with their own list of required packages. Furthermore, the list of packages could change with every future version of FNZ Studio or an extension. Therefore, we strongly recommend to allow reflective access to ALL packages of Java 21.
Even though this means to add more than 1000 options to the command-line, performance tests have shown that JVM startup time increases by less than 0.2 seconds.
Configuration
The following setup has been tested with Apache Tomcat, JBoss EAP, and WebSphere Liberty.
Step 1: Download JVM options file
The easiest way to pass a lot of command-line options to Java is using a command-line argument file. All the required command-line options are stored in a simple text file with one option per line. The path to this file is then added to the command-line, prefixed with an "@" sign to mark it as an argument file.
We have already prepared such a file with command-line options for all Java and JDK packages of Java 21:
Step 2: Store JVM options file on server
The file with the JVM options has to be stored on every FNZ Studio node. We recommend putting the file into the "conf" directory of the Java application server or the FNZ Studio data home.
Step 3: Add JVM options file to command-line
The simplest way to add the JVM options file to the command-line when starting the Java application server is to use the environment variable JDK_JAVA_OPTIONS:
JDK_JAVA_OPTIONS=@/opt/tomcat/conf/jvm-options-java-21.txt
The value of this environment variable is treated by Java as if the options in this file would have been passed directly on the command-line.
Step 4: Check server startup logs
The Java application server will automatically pick up the command-line options from the arguments file during JVM startup. This can be verified by looking for a startup log message like the following:
NOTE: Picked up JDK_JAVA_OPTIONS: @/opt/tomcat/conf/jvm-options-java-21.txt
Potential Problems
If the path to the argument file is incorrect, or if the JVM process does not have read access to this file, JVM startup is aborted with an error message:
Error: could not open '/opt/tomcat/conf/jvm-options-java-21.txt'
If a command-line option refers to a Java package which is not present in the local Java 21 installation, a warning like the following can be found in the startup log:
WARNING: package com.ibm.lang.management.internal not in jdk.management
Such warnings can be ignored. If they cause problems, the corresponding command-line options can be removed from the argument file.
FNZ Studio will also perform some access tests during startup for a limited set of Java packages. If it detects that reflective access to one or more of these Java packages has not been granted, it assumes that the required command-line options are missing. Startup is then aborted with a message like the following:
FNZ Studio does not have access to some required JDK packages.
Please add the following JVM command-line options:
[...]
Note that there is an upper limit of 1000 command-line options for --add-exports and --add-opens which can be passed to a JVM. If this limit is exceeded, JVM startup is aborted:
Property count limit exceeded: jdk.module.addopens, limit=1000
Error: Could not create the Java Virtual Machine.
Error: A fatal exception has occurred. Program will exit.
This should not happen when using the JVM options file offered for download above. That file currently contains 402 --add-exports options and 605 --add-opens options. The most likely reason for the above error is that the same JVM options file is passed more than once to the JVM.