ArcGIS Java Configuration Tool

---

ArcGIS Java Configuration Tool (henceforth Configuration Tool) is a tool that is used to configure the Java runtime environment for running ArcGIS Java extensions in ArcMap and  ArcCatalog. In addition, this tool can be used to enable options for troubleshooting problems in Java extensions running in these applications. The Configuration Tool is an executable program (JavaConfigTool.exe) that can be found in the $AGSENGINEJAVA%/bin location. Below is a screen shot of the tool launched on a Windows computer. Note that on Windows Vista and Window Server 2008, this tool should be run with administrator privileges ("Run As Administrator").

There are two reasons for using the Configuration Tool.

ArcGIS applications like ArcMap, ArcCatalog and are inherently non-Java applications that load a Java virtual machine (JVM) into their process space in order to create instances of Java extensions and dispatch method calls into them. These applications use the JVM that is installed on the computer for this purpose. When the Configuration tool is invoked for the first time, it will default values for runtime options currently being used by ArcGIS. The screenshot below shows that the JVM provided for ArcMap and ArcCatalog to use has a default minimum heap of 3MB, maximum heap of 64MB and thread stack size of 512KB.

However, the need to modify the defaults used by ArcGIS can arise in some situations. For example, the default thread stack size may be too small and a larger stack size is required to ensure the correct working of an XML parsing library that makes a long chain of method calls to parse an XML string, or the default heap size needs to be increased to accommodate the large number of Java objects that an extension might create during its lifetime. Such changes can be made using the Configuration Tool. It allows you to modify the heap size or the stack size by entering valid values in the appropriate fields. The screenshot below shows values for memory sizes that are different from the initial defaults. Other JVM runtime options (except–Xdebug, which is automatically set if you choose to enable debugging of Java extensions on the “Debugging option” section of the Configuration Tool) can be entered in the “Java VM Arguments” text area with every option entered on a separate line. The screenshot also shows the “-Xnoclassgc” and ”-Xincgc” options specified in the new configuration.

Finally, the changes made to the JVM Runtime Options will take effect the next time an ArcGIS application starts up. If an application is already running at the time of modifying the configuration, then it needs to be restarted for the changes to apply. Note that configuration changes to the JVM Runtime options do not apply to ArcGIS Engine Java applications.

A second usage of the Configuration Tool is to enable and configure options for troubleshooting Java extensions running in ArcGIS applications. The screenshot below shows the available troubleshooting options on the Configuration Tool.

Through these options you can enable Java Interop logging to obtain log files that show problems in a running extension, enable a console window in ArcMap and ArcCatalog to print out trace statements from an extension and enable the option of attaching a debugger to an extension running in ArcGIS and stepping through its code. For more information on the use of each troubleshooting option on the Configuration Tool and how they apply to troubleshooting Java extensions in various ArcGIS applications, please refer topic How to troubleshoot ArcGIS Java extensions.