How to troubleshoot ArcGIS Java Extensions
How to troubleshoot ArcGIS Java Extensions

About troubleshooting

The JCT resides in the <ArcGIS Home>/bin folder. This tool must be run as Administrator in Windows 7 and Vista. In addition to providing ability to turn on logging, debugging and consoles for ArcGIS Desktop, this tool also allows users to specify JVM runtime options such as heap and stack size, as well as other VM args that users might need to use.
troubleshoot ArcGIS Java Extensions -

Java Interop logging

ArcGIS applications that run Java extensions can generate log files. These log files can report problems that could prevent ArcGIS from loading an extension if the extension could not be registered or show a stack trace of runtime Java exceptions triggered by code running in the extension. The logging feature can be turned on by enabling the “Java Interop Logging” option in the Configuration Tool. The screenshot below shows Enabling Java Interop Logging.
troubleshoot ArcGIS Java Extensions -
Any ArcGIS applications that are currently running will need to be stopped and restarted in order for this setting to take effect. The generated log files have names of the form “ccjw_pid_<pid>.log” where <pid> is the Process identifier of the ArcGIS application and are stored at the following location on a computer:
  • Windows 7, Vista, and Server 2008:
    <Drive>:\Users\<user>\AppData\Local\ESRI\<Product and version>\Java\Log
  • Windows XP and Server 2003:
    <Drive>:\Documents and Settings\<user>\Local Settings\Application Data\ESRI\<Product and version>\Java\Log
  • UNIX:
    <HOME DIR>/.arcgis10.0/Application Data/ESRI/<Product and version>/Java/Log
Thus, for Windows 7 and Vista, that has Server 10.0 installed, the location of log files would be:
Windows Vista - <Drive>:\Users\<user>\AppData\Local\ESRI\Server10.0\Java\Log
For Linux:
<HOME DIR>/.arcgis10.0/Application Data/ESRI/Server10.0/Java/Log
The screenshot below shows the log file reporting an error about an unsupported type defined by a Java Utility Object extension.
troubleshoot ArcGIS Java Extensions -

Tracing the execution of an extension

Java extensions can print messages out to a stream in order to trace their execution. This procedure can help zero in on the offending line of code in the extension.

ArcGIS Engine

Extensions being developed for ArcGIS Engine applications within a Java IDE can simply use the “System.out.println()” function to write messages out. Since the Engine application can itself be launched from the IDE, the trace messages originating from the extension will get displayed in the IDE’s console window.


Extensions that run in ArcMap (and ArcCatalog) cannot assume the presence of a console window by default and may at first find their trace messages written using the “System.out.println()” function are seemingly getting lost. Enabling the “Create console for ArcGIS applications (ArcMap/ArcCatalog)” option on the Configuration Tool will cause ArcMap (and ArcCatalog) to launch a console window and show all trace statements written out by an extension. The screenshots below show enabling a console window and a console window launched by ArcMap showing a trace message.
troubleshoot ArcGIS Java Extensions -
troubleshoot ArcGIS Java Extensions -

ArcGIS Server

Extensions that run in ArcGIS Server cannot write to a console window. Extensions should instead write messages directly to ArcGIS Server’s log files located at $AGSSERVERJAVA/server/user/log through the ILog2 interface in the ArcObjects Java API. This interface can be obtained via the convenience method - com.esri.arcgis.system.ServerUtilities.getServerLogger().

Stepping through the extension code in a debugger

Being able to set breakpoints in the extension code and step through it in a debugger application is an effective and popular method of troubleshooting problems in code. This section describes how to debug Java extensions using the Eclipse IDE debugger. In the Eclipse parlance, Java extensions can be debugged under two configurations - Java application and Remote Java Application - depending on which ArcGIS application is running the extension. The Eclipse debugger considers extensions running within ArcGIS Engine applications as a "Java Application", while those that run within ArcMap, ArcCatalog and ArcGIS Server as "Remote Java Application". A Remote Java Application is simply a non-Java application (ArcMap, ArcCatalog, etc) that is running a JVM (and possibly Java extensions) and is accepting debug connections on a particular network port. Below are instructions on a per application basis on how to attach Eclipse debugger to a running instance of a Java extension and step through its code.

ArcGIS Engine

Debugging an extension in an Engine application is similar to debugging any other Java program that is launched from within Eclipse. Simply set break points in the extension and “Debug” the Engine application.  


For debugging Java extensions in ArcMap (the same applies to ArcCatalog), ArcMap needs to be configured to listen on a network port that will accept connections from an Eclipse debugger running on the same computer. The following steps should be followed in order to set up a debug session.
  1. Close ArcMap.
  2. Enable the “Enable debugging of Java extensions…” option on the Configuration Tool and establish a debug port range. Each instance of ArcMap that is subsequently launched will bind to the next available port in the port range, starting with the first port. An example of a port range would be “8013” to “8014” if at most two instances of ArcMap will be open at any given time. The screenshot below shows enabling debugging of Java extensions.
troubleshoot ArcGIS Java Extensions -
  1. Start ArcMap. Considering that two ports had been configured in step b, ArcMap will bind to port 8013. Subsequently, if a second instance of ArcMap is launched it will bind to port 8014. ArcMap is now ready to accept connections from Eclipse.
  2. Attach Eclipse debugger to ArcMap. 
    1. Set break points in the extension code.
    2. Right click on the Java file containing the extension and choose the “Debug configuration” option. The screenshot below shows the Eclipse Debug Configurations page.
troubleshoot ArcGIS Java Extensions -
    1. From the types of applications that can be debugged from Eclipse, choose “Remote Java Application”. Right-click and choose “New”. Specify the port (example 8013) on which the ArcMap application hosting the extension to be debugged is listening for connections and then choose “Debug”. This will attach Eclipse to ArcMap. The next time the extension code is invoked within ArcMap the break points that were set in Eclipse will be hit allowing you to step through your code thereafter. The screenshot shows a custom feature renderer ready to be debugged and the screenshot below shows a break point that has been hit in a custom renderer running in ArcMap.
troubleshoot ArcGIS Java Extensions -
troubleshoot ArcGIS Java Extensions -

ArcGIS Server

The steps involved in debugging an extension running in ArcGIS Server are mostly similar in nature to debugging in ArcMap. The differences lie in having to specify a sufficiently large port range to accommodate the various ArcSOC.exe processes started by ArcGIS Server and then identifying the particular ArcSOC.exe process that is hosting the Java extension to be debugged (e.g. SOE) and the port number that process is listening on. Below are the steps to be followed in order to set up a debug session.
Debugging an SOE:
  1. In ArcGIS Server, ensure all service instances except the one hosting the SOE to be debugged, are stopped. This will ensure there are no other SOEs running in any other service instances which could otherwise add to the complexity of debugging.
  2. Using an ArcGIS administrative application (ArcCatalog/ArcGIS Manager), set the minimum and maximum number of instances of the service running the SOE, to be 1. This will ensure there is only one instance of the ArcSOC.exe process running the SOE.
  3. Stop ArcGIS Server.
  4. Enable the “Enable debugging of Java extensions…” option on the Configuration Tool and establish a port range large enough to accommodate all the ArcSOC.exe processes started by ArcGIS Server (e.g. a range of ~5 ports). Then enable the “Java Interop logging” option on the Configuration Tool. The screenshot shows Enabling Debugging and Java Interop logging
troubleshoot ArcGIS Java Extensions -
  1. Delete any previous log files generated by ArcGIS on the computer. (The location of ArcGIS log files is stated earlier in this tutorial.)
  2. Start ArcGIS Server.
  3. Upon starting, ArcGIS Server will create several ArcSOC.exe processes, one of which will host the SOE. Because the debugging option was enabled in step 2, each ArcSOC.exe process will bind itself to one of the ports in the specified port range. Moreover, since the logging option was turned on, there will be one log file generated per ArcSOC.exe process. In order to identify the ArcSOC.exe process that is running the SOE look for the log file that contains the name of the offending SOE loaded by an ArcSOC.exe process. This log file will also contain the port number that Eclipse should connect to in order to debug the SOE within this ArcSOC.exe process.
  4. Attach Eclipse to ArcSOC.exe 
    1. Set break points in the extension code.
    2. Right click on the Java file contain the extension and choose the “Debug configuration” option.
    3. From the types of applications that can be debugged from Eclipse, choose
      “Remote Java Application”. Right-click and choose “New”. Specify the port number obtained in step g to establish a connection to ArcSOC.exe hosting the SOE and choose “Debug”. Once attached, break points in the SOE code will be hit when operations are invoked on it the next time.
  1. Note that if you want to debug problems in the initialization methods of the SOE that is preventing the service from starting up, you will have to delay the execution of the SOE initialization code by putting a Thread.sleep() call in the constructor of the SOE. This will give you sufficient time after the SOE is loaded to attach to it from Eclipse and set break points in the initialization methods before code in its constructor begins to run.

About 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, ArcCatalog and ArcGIS Server. 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 ARCGISHOME/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").
ArcGIS Java Configuration Tool
There are two reasons for using the Configuration Tool.
  • To configure the Java runtime environment used by ArcGIS applications.
  • To enable and configure troubleshooting options for Java extensions
Any configurations changes made through this tool apply to all ArcGIS applications on that machine.

Configuring the Java runtime environment

ArcGIS applications like ArcMap, ArcCatalog and ArcGIS Server 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. By default, ArcGIS will 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 the location of the default JVM and the runtime options currently being used by ArcGIS. This is shown in screenshot below which indicates that ArcGIS currently uses a JVM versioned 1.6.0_07 with a default minimum heap of 3MB, maximum heap of 64MB and thread stack size of 512KB.
ArcGIS Java Configuration Tool
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. First, disable the “Use Default” check box on the Configuration Tool. This will enable all the text fields in the “JVM Runtime Options” section of the tool. You can now directly change the heap size or the stack size by entering valid values in the appropriate fields or browse and choose a different version of the JVM installed on the computer to be used for running the extensions. The screenshot below shows an example configuration that has specified a JVM versioned 1.5.0_17 and 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.
ArcGIS Java Configuration Tool
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.

Enabling troubleshooting options

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.
ArcGIS Java 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.