[frs-280] Setting VM Options via FRAPI

[frs-237] Creating Daily FusionReactor Log Files
[frs-232] Capturing ColdFusion’s Debug Output in FusionReactor

Setting VM Options via FRAPI

The Sun Java VM (JVM) offers many options to allow the user to control how the VM behaves. The HeapDumpOnOutOfMemoryError option for example is very useful if your server is suffering from heap memory problems and crashing.

By turning on HeapDumpOnOutOfMemoryError the JVM will create a dump file when java.lang.OutOfMemoryError is thrown that can be used in Memory Analysis tools such as MAT to track down memory problems.

A list of VM manageable runtime options includes:

Option Description
-XX:-HeapDumpOnOutOfMemoryError Dump heap to file when java.lang.OutOfMemoryError is thrown
-XX:-PrintClassHistogram Print a histogram of class instances on Ctrl-Break
-XX:-PrintConcurrentLocks Print java.util.concurrent locks in Ctrl-Break thread dump
-XX:-PrintGC Print messages at garbage collection
-XX:-PrintGCDetails Print more details at garbage collection
-XX:-PrintGCTimeStamps Print timestamps at garbage collection

Typically these options are added to the command line that starts the VM in the form of -XX:<optionname>.

There are however major problems with this:

  • Typically you have to edit the file that sets the command line options (e.g. jvm.conf) to change the settings.
  • If the -XX command line option wasn't added to the command line options at start-up then you can't set the option without restarting the server


It would be great if you control these VM options using code instead of the command line. FRAPI is a powerful and easy to use API that allows you to take control of FusionReactor programatically. Using FRAPI you can change the running configuration of FusionReactor or add extra debugging information to requests using just a few lines of code. We can also use FRAPI to set any "Managable" VM Option on the Sun JVM. (take a look at the following VM Options for details of all of the VM Options and look for "Manageable").

<cfset frapi = createObject("java", "com.intergral.fusionreactor.api.FRAPI").getInstance()>
<cfset frapi.setVMOption("HeapDumpOnOutOfMemoryError","true")>
<cfset frapi.setVMOption("PrintConcurrentLocks","true")>
<cfset frapi.setVMOption("PrintGCDetails","true")>   
<%@ page import="com.intergral.fusionreactor.api.*" %>
    FRAPI frapi = FRAPI.getInstance();


You must be using a version of FRAPI that includes the setVMOption method (introduced in FRAPI 4.0) and a Sun JVM 1.5 or higher.


  • Due to a Bug in Java the HeapDumpPath VM Option may throw a NullPointerException and typically cannot be used.
  • Only VM Options that are known as "Manageble" can be set/changed at runtime. Manageable means that the option is dynamically writeable through the JDK management interface.


FRAPI is a easy way to set powerful VM Options while the server is running, without having to restart the server or edit configuration files.

Issue Details

Type: DevNet
Issue Number: FRS-280
Components: FRAPI
Resolution: Fixed
Last Updated: 03/Nov/11 5:35 PM
Affects Version: 4.0.0
Fixed Version: 4.0.0
Platform: Windows XP, Windows 2000, Windows 2003, Linux, MacOS, Solaris, Windows Vista, Windows x64, AIX, Windows 7, Windows 2008
Related Issues:

FRS-232: Capturing ColdFusion’s Debug Output in FusionReactor