====== Java Tuning ======
After the initial setup and importing of records, you may notice a significant degradation of performance. This means its time to do some JVM tuning. However, if you look around the Internet, you'll quickly realize performance tuning for Java applications is a bit of a black art. However, we'll provide some basic settings to help improve your performance, as well as resources for more in-depth tuning settings.

As a short side-note, these recommendations are for a "server-class" machine with at least 2 GB RAM and 2 processors. There are limits on the architecture that may require editing the sizes provided in the settings.

===== JAVA_OPTIONS =====

If you are using the included distribution of Jetty, the tuning options are set in the JAVA_OPTIONS environmental variable. You can either set this for the user running the instance of Jetty (recommended) or in /etc/profile.

It's recommended that you run the most recent [[http://java.sun.com | Sun JDK]] as there is an important switch (-server) that you use that is not in the JRE. 



==== Heap Space ====

The heap space in Java is the amount of memory allocated to Java for objects. One of the more common issues with a full index of records is an java.lang.OutOfMemoryError exception due to the heap space size. By default, the lower limit is set to 1/64th of the server's physical memory and the max is set at 1/4 the physical memory with a max of 1GB. 

It's a good idea to set both of these to the same value as follows (assumes 4GB of RAM):

<code>
-Xms3800m -Xmx3800m
</code>

Note: For very large indices (> 4 million documents) you will need more than 4GB of RAM, and a 64 bit OS to utilize it.  You must also tell java to use the 64 bit "memory model" the setting would then look like:

<code>
-d64 -Xms8192m -Xmx8192m
</code>

Failure to use the "-b64" flag will result in an error message:
 "Invalid initial heap size: -Xms8192M
 The specified size exceeds the maximum representable size.
 Could not create the Java virtual machine."

==== Garbage Collection ====
Garbage collection is how aggressive the JVM is with clearing out unneeded objects. For the purposes of Vufind, parallel garbage collection should work nicely, but read Sun's [[http://java.sun.com/docs/hotspot/gc5.0/gc_tuning_5.html | Tuning Garbage Collection]] for more in-depth information.

<code>
-XX:+UseParallelGC
</code>

=== Young Generation ===
Young generation is a type of garbage collection that has three object spaces, the new object space (Eden) and two survivor spaces. Newer objects are created in Eden, while longer lived objects are moved to the old generation survivor (tenured) spaces. Young generation uses fast copying garbage collection for more frequent clearing of Eden, and more spaced out full garbage collections in the tenured space (which is slower). There are a few switches that will help with this.

<code>
-XX:NewRatio=5 -XX:+UseParNewGC
</code>

Note: if you use the -XX:+UseParNewGC, don't use -XX:+UseParallelGC.




==== Setting JAVA_OPTIONS ====
For a good base setting for JAVA_OPTIONS, this is a good set to begin with:

<code>
JAVA_OPTIONS="-server -Xmx3800m -Xms3800m -XX:+UseParallelGC -XX:+AggressiveOpts -XX:NewRatio=5"
</code>

For more information on Java Tuning, see [[http://java.sun.com/performance/reference/whitepapers/tuning.html | Java Tuning White Paper]] and experiment with the settings.

 NOTE: The -server switch needs to be the first argument in the string in order for the JDK to pick up the setting.

==== Reminders ====
Be sure to check that the settings are getting applied by running 

<code>
./vufind.sh check
</code>

If all went well, you should see output along the lines of

<code>
Checking arguments to VuFind: 
VUFIND_HOME    =  /usr/local/vufind
SOLR_HOME      =  /usr/local/vufind/solr
SOLR_DATA_DIR  =  /usr/local/vufind/solr/data
JETTY_HOME     =  /usr/local/vufind/solr/jetty
JETTY_LOG      =  /usr/local/vufind/solr/jetty/logs
JETTY_CONF     =  
JETTY_RUN      =  /tmp
JETTY_PID      =  /tmp/vufind.pid
JETTY_CONSOLE  =  /dev/tty
JETTY_PORT     =  
CONFIGS        =  /usr/local/vufind/solr/jetty/etc/jetty.xml
JAVA_OPTIONS   =  -server -Xmx3800 -Xms3800 -XX:+UseParallelGC -XX:+AggressiveOpts -Dsolr.solr.home=/usr/local/vufind/solr -Dsolr.data.dir=/usr/local/vufind/solr/data -Djetty.logs=/usr/local/vufind/solr/jetty/logs -Djetty.home=/usr/local/vufind/solr/jetty 
JAVA           =  /usr/lib/jvm/java-6-sun/bin/java
CLASSPATH      =  
RUN_CMD        =  /usr/lib/jvm/java-6-sun/bin/java -server -Xmx3800 -Xms3800 -XX:+UseParallelGC -XX:+AggressiveOpts -Dsolr.solr.home=/usr/local/vufind/solr -Dsolr.data.dir=/usr/local/vufind/solr/data -Djetty.logs=/usr/local/vufind/solr/jetty/logs -Djetty.home=/usr/local/vufind/solr/jetty  -jar /usr/local/vufind/solr/jetty/start.jar  /usr/local/vufind/solr/jetty/etc/jetty.xml
</code>

====== User Contributed Settings ======
William and Mary: Dell Precision 2950, 2x2 dual core Xeon 3.2 GHz processors, 4GB RAM
<code>
JAVA_OPTIONS="-server -Xmx3800 -Xms3800 -XX:+UseParallelGC -XX:+AggressiveOpts -XX:NewRatio=5"
</code>

====== Resources ======
Here's a list of useful websites on Java performance tuning:

  * [[http://www.petefreitag.com/articles/gctuning/ | Tuning Garbage Collection Outline]] - older information on the 1.4.2 garbage collection, but still applicable for 1.5+.
  * [[http://java.sun.com/performance/reference/whitepapers/tuning.html | Java Tuning White Paper]]