JVM Startup Recommendations

The following are recommended Java Virtual Machine (JVM) parameter settings for use with SuperWEB2 and Open Data API Tomcat to optimise Java programs and program memory when using Windows and Linux.

Configure Startup Settings

Windows: Manual Startup

If you are using the startup script sw2.bat to run SuperWEB2 manually, then you can configure the startup settings by editing the value of CATALINA_OPTS in the sw2.bat file.

In the supplied installation files, sw2.bat is located in <tomcat_home>\webapps\webapi\tomcat-scripts, but if you have completed the SuperWEB2 install the version to edit is now located in <tomcat_home>\bin.

JVM startup settings can also be applied to Job Queue Manager (JQM). If you have installed JQM in a separate Tomcat instance then you will need to copy sw2.bat to the JQM <tomcat_home>\bin, update the value of the JAVA_HOME variable to match the location of the JRE installed on your system, (for example: set JAVA_HOME=C:\Program Files\Java\jre7) and edit this file with the startup settings to apply to JQM.

In a text editor, open <tomcat_home>\bin\sw2.bat.
Locate the following variable:
CODE
```
set CATALINA_OPTS=
```
Edit or add the required values of the CATALINA_OPTS variable. See Recommended Settings below.
Restart Tomcat or the SuperWEB2 service.

Windows: Running as a Service

If you are running Tomcat as a service, then the startup parameters defined in the supplied script sw2-service.bat are configured as part of the service when you run sw2-install-service.bat to create it. Editing the values in the script will not change the settings for the existing service.

To update the settings after the service has been installed, you have two options: delete and recreate the service, or use the Tomcat service configuration tool.

Option 1 - Delete and Recreate the Service

If you decide to delete and recreate the service, do the following:

Edit the JvmOptions at the bottom of sw2-service.bat.
Run sw2-uninstall-service.bat from the <tomcat_home>\bin directory to delete the service.
Run sw2-install-service.bat to recreate the service.

Option 2 - Edit the Service Directly

There is a tool supplied with Tomcat for editing the service. For Tomcat 9 this tool is named Tomcat9w.exe and is located in the <tomcat_home>\bin directory.

To use the tool, you first need to rename it, replacing Tomcat in the filename with the name of the configured service. For example, if the service is installed as SuperWEB2, rename the tool to SuperWEB2w.exe.

Once you have renamed it, double-click the tool and select the Java tab to set the startup and memory options.

Linux

On Linux you will need to apply the settings to the CATALINA_OPTS system variables as follows:

CODE

export CATALINA_OPTS='-Xmx20g -javaagent:/<path>/spring-agent.jar -Djacorb.home=/<tomcat_home>/webapps/webapi -Djava.net.preferIPv4Stack=true -Dfile.encoding=UTF-8 -Djava.awt.headless=true'

Example

CODE

export CATALINA_OPTS='-Xmx20g -javaagent:/java/lib/spring-agent.jar -Djacorb.home=/usr/local/jakarta-tomcat/webapps/webapi -Djava.net.preferIPv4Stack=true -Dfile.encoding=UTF-8 -Djava.awt.headless=true'

For more information about these parameters, see Required Settings and Memory Usage Settings below.

If you require assistance with these settings, please contact WingArc Support.

Recommended Settings

Required Settings

CODE

-javaagent:/<path>/spring-agent.jar
-Djacorb.home=/<tomcat_home>/webapps/webapi
-Djava.net.preferIPv4Stack=true
-Dfile.encoding=UTF-8
-Djava.awt.headless=true

Parameter	Description
-javaagent:/<path>/spring-agent.jar	Location of spring-agent.jar. Replace `<path>` with the directory path to the file location.
-Djacorb.home=/<tomcat_home>/webapps/webapi	Location of application folder. Replace `<tomcat_home>` with the path to your Tomcat installation. For more information, see Java and Tomcat.
-Djava.net.preferIPv4Stack=true	Sets IPv4 as the preferred protocol stack. IPv6 support is not yet fully implemented due to an old library.
-Dfile.encoding=UTF-8	Default file encoding format.
-Djava.awt.headless=true	Set headless mode.

Memory Usage Settings

If you use the supplied version of Tomcat to run SuperWEB2 then the supplied scripts allocate 4GB of RAM to Tomcat when it starts up, using the following Catalina options: -Xms4g -Xmx4g.

We recommend increasing this to at least 8GB RAM where possible. Please contact us for assistance if you want to discuss Tomcat RAM requirements.

CODE

-Xmx20g

Parameter	Description
-Xmx<size><unit>	Maximum heap space. The amount of memory allocated to applications running in the JVM. Replace `<size><unit>` with amount and unit type of memory. `g` = GB. The figure set depends on your environment. Determine how much memory is available for Tomcat and set it to just below that leaving some leeway.

Useful Debugging Settings

CODE

-XX:+CrashOnOutOfMemoryError
-Xloggc:/<path>/java-gc-$(date +%Y-%h-%d-%I-%M-%S-%P).log'
-XX:+PrintGCDetails 
-XX:+PrintGCDateStamps

Parameter	Description
-XX:+CrashOnOutOfMemoryError	Prevents the server from hanging when it gets stuck in a garbage collection loop by terminating Java. You also need to ensure the service is configured to restart automatically for this to be useful. This is only triggered when there has been no progress for a period of time in which case the server is not likely to recover. It writes the entire heap (up to size of Xmx) to disk on crash so this can take a up lot of disk space. This can be useful if you find you are running out of memory. If you don’t want to write the entire heap out, you can use `-XX:+ExitOnOutOfMemoryError` instead.
-Xloggc:/<path>/java-gc-$(date +%Y-%h-%d-%I-%M-%S-%P).log	Writes garbage collection information to a logfile. Produces one line of text per garbage collection run so this not very intensive. The `$(date …)` component in the log filename is required for use with Linux otherwise the file overwrites itself every time Java is restarted.
-XX:+PrintGCDetails	Collects more verbose garbage collection statistics. This option only takes effect if `-Xloggc:/<path>/java-gc-$(date +%Y-%h-%d-%I-%M-%S-%P).log` is present.
-XX:+PrintGCDateStamps	Adds time-stamp information to the garbage collection statistics collected by `-XX:+PrintGCDetails`.