Are you a robot?
Enter the characters shown in the image.

Debugging the DocuShare Tomcat server using JPDA

Debugging the DocuShare Tomcat server using JPDA

Bart Thierens,ECM Consultant




1 July 2013


Sometimes it might be necessary to debug a (DocuShare) Tomcat instance.  What if you deployed a custom webapp or servlet on the default DocuShare Tomcat that interacts with the DocuShare and all of a sudden you get issues in a production environment?  The easiest way would be to debug your deployed code directly in production in a non-invasive way.  This can be achieved by using the Java Platform Debugger Architecture (JPDA).  This enables you to debug your code line by line from your IDE (ie. Eclipse) while it is deployed on a Tomcat server.  Sadly, it requires a non-standard way to set it up for DocuShare.

In a normal Tomcat setup (non-Windows service) you would edit the catalina.bat/ and startup.bat/ files to use the JPDA settings.

Example snippet from catalina.bat (Windows):

Example snippet from startup.bat (Windows):


The problem is that DocuShare doesn't call those bat files when it starts up the Tomcat server.  The Monitor does all the variable-handling internally and calls the Tomcat start-command itself.  This causes any changes to our .bat files to be ignored.

How to make it work

The trick is to make the Monitor start up Tomcat with all our JPDA options enabled.  This can be achieved by editing the DS_HOME/config/Monitor.xml file.

The Monitor.xml file describes all the servers/services that the DocuShare Monitor should start and control.  Parameters, classpaths and commands can be passed to the server through the config file.

To enable JPDA you need to change the following 2 settings for the Tomcat server (be careful not to change anything else - make a backup before you change anything):

  • StartJVMParams
  • StartAppParams

Add the following JPDA settings to the end of theStartJVMParams settings: 

-Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

Change the StartAppParams from 'start' to 'jpda start' (without the quotes).

Then restart your DocuShare server and your Tomcat should be debuggable through JPDA on port 8000.

Extra thoughts

  • Do not leave JPDA enabled on a production environment when no debugging is done!
  • Be very careful when editing Monitor.xml!  The slightest mistake can cause DocuShare to not start up incorrectly.  Always take a backup before you change anything.


Please contact us to help you with your digital journey

Are you a robot?
Enter the characters shown in the image.