How to troubleshoot ArcGIS Java Extensions

This document was published with ArcGIS 9.3.1.
A 9.3 version also exists.
This topic applies to 9.3.1 and later versions.

Development licensing Deployment licensing
Engine Developer Kit Engine Runtime
Server Server

In this topic

About troubleshooting

This document explains three techniques for troubleshooting ArcGIS Java Extensions:

These techniques can be enabled using the ArcGIS Java Configuration Tool (henceforth Configuration Tool) which allows configuring the environment for running Java extensions within ArcGIS applications. This includes being able to specify a JVM and its runtime options (min heap, max heap, etc) to be used for running Java extensions and enabling the troubleshooting options mentioned above. The screenshot below shows the Configuration Tool showing all its capabilities. (To launch this tool double-click “JavaConfigTool.exe” under ARCGISHOME/bin.). The remainder of this topic will explain how to use each troubleshooting technique vis-à-vis the “Debugging Options” section of the Configuration Tool.

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.
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:
The screenshot below shows the log file reporting an error about an unsupported type defined by a Java Utility Object extension.

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.

ArcGIS Server

Extensions that run in ArcGIS Server cannot write to a console window because the notion of a console window does not exist in an ArcGIS Server environment. Extensions should instead write messages directly to ArcGIS Server’s log files located at ARCGISHOME/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.
  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.
    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.

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

See Also:

ArcGIS Java Configuration Tool