TDS Reference: Summary of JAVA_OPTS


Note: This page focuses on Tomcat running on a Unix/Linux OS but much of it is appropriate for other servlet containers and other OSs. How and where the various options are configured will depend on the servlet container and OS you are using.


You can set JAVA_OPTS in the ${TOMCAT_HOME}/bin/setenv.sh file. The options discussed below are the ones we set on our production server.

Memory Available to the Java JVM

Increasing the memory available to the Java JVM can help TDS performance (see more on TDS performance here). Try to give your server as much memory as you can. The following are reasonable numbers to start with but if you have more memory increase these numbers. [Note: 32-bit JVMs max out around 1500m.)

JAVA_OPTS="-Xmx1024m -Xms256m"
export JAVA_OPT

What the options mean:

Run Java JVM in Server Mode

The Java JVM can optimize a number of things for server environments. [Since Java 5, the launcher tries to detect whether it is running on a "server-class" machine and set this for you (more on this here). But ...] You can explicitly select the Java HotSpot Server VM with the -server option.

JAVA_OPTS="-Xmx1024m -Xms256m -server"
export JAVA_OPT

What the option means:

PermGen Memory

If you start getting java.lang.OutOfMemoryError: PermGen space error messages. You may want to include a "-XX:MaxPermSize" option in your JAVA_OPTS. See the PermGen FAQ entry for more information on this problem.

JAVA_OPTS="-Xmx1024m -Xms256m -server -XX:MaxPermSize=128m"
export JAVA_OPT

What the option means:

If Using WMS, Tell Graphics Engine There is No Console

An obscure bug concerning X servers and graphics rendering code can cause WMS requests to fail or, in certain situations, cause Tomcat to crash. You may see error messages like the following:

"java.lang.NoClassDefFoundError: Could not initialize class sun.awt.X11GraphicsEnvironment"

To avoid this situation, the graphics code needs to be told that there is no graphics console available. This can be done by setting the java.awt.headless system property to true which can be done using JAVA_OPTS:

JAVA_OPTS="-Xmx1024m -Xms256m -server -Djava.awt.headless=true"
export JAVA_OPT

What the option means:

More on using the headless mode in Java SE here.

If Using WMS, Setup Writable Directory for System java.util.prefs.

Some libraries that WMS depends on use the java.util.prefs package and there are some known issues that can crop up with storing system preferences. This problem can be avoided by setting the java.util.prefs.systemRoot system property to point to a directory in which the TDS can write. The given directory must exist and must contain a directory named ".systemPrefs" which must be writable by the user under which Tomcat is run.

JAVA_OPTS="-Xmx1024m -Xms256m -server -Djava.util.prefs.systemRoot=$CATALINA_HOME/content/thredds/javaUtilPrefs"
export JAVA_OPT

What the option means:

More information on the issue can be found on the TDS FAQ page.


Our production setenv.sh file looks like:

#!/bin/sh
#
ulimit -n 2048

CATALINA_HOME="/opt/tomcat"
export CATALINA_HOME

JAVA_HOME="/opt/jdk"
export JAVA_HOME

# Some commonly used JAVA_OPTS settings:
#
NORMAL="-d64 -Xmx4090m -Xms512m -server"
MAX_PERM_GEN="-XX:MaxPermSize=256m"
HEADLESS="-Djava.awt.headless=true"
JAVA_PREFS_SYSTEM_ROOT="-Djava.util.prefs.systemRoot=$CATALINA_HOME/content/thredds/javaUtilPrefs"

# Standard setup.
#
JAVA_OPTS="$NORMAL $MAX_PERM_GEN $HEADLESS $JAVA_PREFS_SYSTEM_ROOT"
export JAVA_OPTS
TDSThis document is maintained by Unidata and was last updated May, 2010. Send comments to THREDDS support.