From b40f042fa3471de6c594289aef5c1f89f328f3e4 Mon Sep 17 00:00:00 2001
From: Tara Drwenski <tdrwenski@ucar.edu>
Date: Fri, 19 Jul 2024 15:08:00 -0600
Subject: [PATCH] Add Chronicle cache JVM args to documentation

---
 docs/userguide/src/site/pages/tds_tutorial/faq/faq.md | 11 +++++++++++
 .../tds_tutorial/getting_started/RunningTomcat.md     |  4 +++-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/docs/userguide/src/site/pages/tds_tutorial/faq/faq.md b/docs/userguide/src/site/pages/tds_tutorial/faq/faq.md
index 5086758947..7fc9ca75b7 100644
--- a/docs/userguide/src/site/pages/tds_tutorial/faq/faq.md
+++ b/docs/userguide/src/site/pages/tds_tutorial/faq/faq.md
@@ -301,6 +301,17 @@ com.google.common.util.concurrent.UncheckedExecutionException: java.lang.Illegal
 
 then you may need to adjust your [FMRC cache settings](https://docs.unidata.ucar.edu/tds/current/userguide/tds_config_ref.html#featurecollection-cache).
 
+### Failed to start up with JDK 17
+
+If you are upgrading to JDK 17 and your serverStartup.log contains an error like
+~~~
+ERROR org.springframework.web.context.ContextLoader: Context initialization failed
+java.lang.ExceptionInInitializerError: null
+    at net.openhft.chronicle.core.internal.ClassUtil.getSetAccessible0Method(ClassUtil.java:32) ~[chronicle-core-2.25ea15.jar:?]
+    ...
+~~~
+You may be missing the JVM arguments need by the chronicle library. Please see `$CHRONICLE_CACHE` in [`${tomcat_home}/bin/setenv.sh`](running_tomcat.html#setting-java_home-java_opts-catalina_home-catalina_base-and-content_root)
+
 ## Caching
 
 ### We use compressed netCDF files, and the very first access to them are quite slow, although subsequent accesses are much faster, then become slow again after a while. 
diff --git a/docs/userguide/src/site/pages/tds_tutorial/getting_started/RunningTomcat.md b/docs/userguide/src/site/pages/tds_tutorial/getting_started/RunningTomcat.md
index ef20909d1e..640d781179 100644
--- a/docs/userguide/src/site/pages/tds_tutorial/getting_started/RunningTomcat.md
+++ b/docs/userguide/src/site/pages/tds_tutorial/getting_started/RunningTomcat.md
@@ -128,11 +128,12 @@ Download an {% include link_file.html file="tds_tutorial/getting_started/setenv.
    NORMAL="-d64 -Xmx4096m -Xms512m -server"
    HEAP_DUMP="-XX:+HeapDumpOnOutOfMemoryError"
    HEADLESS="-Djava.awt.headless=true"
+   CHRONICLE_CACHE="--add-exports java.base/jdk.internal.ref=ALL-UNNAMED --add-exports java.base/sun.nio.ch=ALL-UNNAMED --add-exports jdk.unsupported/sun.misc=ALL-UNNAMED --add-exports jdk.compiler/com.sun.tools.javac.file=ALL-UNNAMED --add-opens jdk.compiler/com.sun.tools.javac=ALL-UNNAMED --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.lang.reflect=ALL-UNNAMED --add-opens java.base/java.io=ALL-UNNAMED --add-opens java.base/java.util=ALL-UNNAMED"
 
    #
    # Standard setup.
    #
-   JAVA_OPTS="$CONTENT_ROOT $NORMAL $HEAP_DUMP $HEADLESS $JAVA_PREFS_ROOTS"
+   JAVA_OPTS="$CONTENT_ROOT $NORMAL $HEAP_DUMP $HEADLESS $JAVA_PREFS_ROOTS $CHRONICLE_CACHE"
 
    export JAVA_OPTS
    ~~~
@@ -153,6 +154,7 @@ Download an {% include link_file.html file="tds_tutorial/getting_started/setenv.
     * `-Djava.awt.headless=true` is needed to prevent graphics rendering code from assuming a graphics console exists.
     Without this, WMS code will crash the server in some circumstances.
     * `-Djava.util.prefs.systemRoot=$CONTENT_ROOT/thredds/javaUtilPrefs -Djava.util.prefs.userRoot=$CONTENT_ROOT/thredds/javaUtilPrefs` allows the java.util.prefs of the TDS WMS to write system preferences to a location that is writable by the Tomcat user.
+    * The parameters in `$CHRONICLE_CACHE` are required by the [chronicle libraries](https://chronicle.software/chronicle-support-java-17/) to run with JDK 17
 
     {%include note.html content="
     For more information about the possible options/arguments available for `$JAVA_OPTS`, please consult the [Oracle Documentation](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html#BABDJJFI){:target='_blank'}.