Debugging Tools and Techniques

Enabling remote debugging in Tomcat

By enabling remote debugging for the Apache Tomcat servlet container and web server, typically in conjunction with a Java integrated development environment (IDE), you can trace the flow of data through the Services and/or Application layers of a CollectionSpace system. This can be extremely helpful for:

• Troubleshooting a small set of issues that may not be readily amenable to resolution using any other techniques.

• Understanding how CollectionSpace's code works, when writing your own code to extend CollectionSpace.

To enable remote debugging in Tomcat:

Start Tomcat via

You can optionally set options for the remote debugger via environment variables.

The values in the following example are believed to already be the defaults (at least for Linux and Mac OS X). Thus you may only need to set these values explicitly, by creating these two environment variables, if you wish to change them from their default values shown below. Otherwise, you can skip this step entirely.

E.g. for the 'bash' shell, you might enter the following in your .bashrc or .bash_profile file in your home directory:

In your IDE, attach the remote debugger to Tomcat using option values similar to these:
Port: 8000
Host: localhost
Transport: dt_socket

When you have finished debugging, it is advisable to shut down Tomcat and restart it without remote debugging enabled. This will improve performance and remove a potential security vulnerability. (See also the warning below.)

It is highly desirable to protect the remote debugger port (8000 or otherwise) on your machine from unauthorized remote access, by means of host-based firewall settings or otherwise.

Using tcpmon to interactively debug calls to the Services Layer

You can use the tcpmon utility to interactively debug calls to the Services Layer. This will allow you to see the actual HTTP headers and entity bodies being sent in requests, and the headers and entity bodies being received in responses.

For instance, you can use tcpmon to debug calls made to the Services Layer by:

• CollectionSpace's Application layer.

• Code written using the CollectionSpace Services Java Client Library, including the automated client tests of the services layer.

• Web browers, cURL, and any other arbitrary HTTP client software.

Set up tcpmon as a proxy for the CollectionSpace Services layer

1. Download tcpmon.

2. Start tcpmon.
   The exact method of doing this may vary by operating system. On Linux, for instance, you might right-click on the tcpmon-1.1.jar or tcpmon.jar icon and select "Open with "Java"" from the menu which appears. On Mac OS X, you might double-click the icon instead.

3. Edit the values in the "Create a New TCP Monitor Connection" section, at left, in the tcpmon window:

   • Set Local Port to some unused local port number, such as 8200 (for example).

   • Set Server Name to the IP address of the server on which the CollectionSpace Services layer is running. If the Services layer is running on your own host, leave that value at its default of 127.0.0.1 (localhost).

   • Set Server Port to 8180, the port at which the CollectionSpace Services layer will be listening by default, on that server.

4. Click "Add Monitor".

Example of tcpmon's main window. (This is an imported image, and the port numbers do not match those listed above.)

Change your client configuration to connect to tcpmon, rather than to the Services layer

If you are using the Application layer

If you are debugging calls sent by CollectionSpace's Application layer to its Services layer:

For the tenant (museum) to which you'll be connecting, edit the $CSPACE_JEESERVER_HOME/lib/tenants/{tenantname}/local-{tenantname}-settings.xml file, to change the port number for the services layer to which the app layer will be connecting, to the Local Port number you set up when configuring tcpmon, above. (In the above file path, {tenantname} is a placeholder for the name of your museum ("tenant").)

If you are using the Java Client Library

If you are debugging calls sent by many of CollectionSpace Services layer's client tests, or other code written using the Java Client Library in which those tests are written:

1. Save a backup copy of your current collectionspace-client.properties file. (In trunk of the services source code tree, this file can be found at services/client/src/main/resources/collectionspace-client.properties.)

2. Edit the url property in your collectionspace-client.properties file, to connect to localhost at the Local Port number you set up when configuring tcpmon, above.

   For example, if you set the Local Port to 8200, edit this property as follows:

   cspace.url=http://localhost:8200/cspace-services/

The following additional steps appear also to be necessary, at least when running client tests using the full Services layer source code tree:

1. Change to the services/client directory.

2. Run mvn clean install -DskipTests. (This will install your edited collectionspace-client.properties file into a JAR in your local Maven repository.)

If you are using another HTTP client, like cURL

Connect to the Services layer via localhost at the Local Port number you set up when configuring tcpmon, above.

Example:

Interactively debug your calls to the Services layer

At this point, when you make calls to the Services layer, each request / response pair will appear as a row in the scrolling list, near the top of the tcpmon window.

Click any row to view the HTTP headers and entity body of the request and the response, which will appear in the two sections of the window below.

Example of tcpmon's traffic monitoring window, showing the contents of a GET request to the Services layer in the middle pane and the response to that request in the lower pane:

Revert to your previous configuration

When you are done debugging, you may return to your previous configuration.

Quit tcpmon

1. In the tcpmon window, click "Stop Monitor".

2. Quit the tcpmon application.

Revert your changes to your client configuration

If you are using the Java Client Library

Switch to your backup copy of your collectionspace-client.properties file, or else revert your recent changes to that file.

If you are using another HTTP client, like cURL

Change the port number at which you are accessing the CollectionSpace services back to its default of 8180, instead of 8200 or whatever other local port you were using with tcpmon.