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

$CSPACE_JEESERVER_HOME/bin/catalina.sh jpda start

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:

export JPDA_ADDRESS=8000
export JPDA_TRANSPORT=dt_socket

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.