How to troubleshoot ArcGIS Java Extensions

---

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.

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:

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.

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.

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.

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

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.

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.

ArcGIS Server

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

5. Delete any previous log files generated by ArcGIS on the computer. (The location of ArcGIS log files is stated earlier in this tutorial.)
6. Start ArcGIS Server.
7. 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.
8. 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.

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