Remote Debug an IBM Notes client from Eclipse

Normally the easiest way to debug Notes plugins is to start the Notes client directly from eclipse. I have explained how to do this in my tutorial: "Configure Eclipse 4.3 to develop plugins for Notes Part 1 and Part2". But sometimes problems are specific to a special client environment or user configuration and can not be debugged in a test environment. Yesterday i had such a problem with a feature which works great, when i launched the client from eclipse, but fails when i start the client like a user will do.

Fortunately the JVM of the Notes client has a built in remote debugging facility. It can be activated with some small modifications in the JVM.properties configuration file:

Locate the JVM.properties of the Notes client installation you want to debug. You can find it in the  "..\framework\rcp\deploy" directory in your IBM Notes program path.

Open the file with an Editor with admin access rights or copy the file to the desktop before your open it in your favorite text editor.

Add the "vmarg.Xss1m=-Xss1m" directive to the beginning of the VM arguments. It will increase the stack size so that the increased need for storage in the stack while debugging will be provided.

Mark the "vmarg.Xnolinenumbers=-Xnolinenumbers" directive as a comment because when this performance optimization is active, eclipse is not able to set breakpoints.

Add the "vmarg.debug=-Xdebug" and "vmarg.Xrunjdwp=-Xrunjdwp:transport=dt_socket,server=y,address=8765" to the end of the VM arguments. The first will activate the debug functionality in the VM. The second makes the debugger listening on port 8765 and the server=y tells the jvm to stop the execution on startup and wait for a debugger to connect.

Save the modified jvm.properties file to the deploy folder of your Notes installation.

Then prepare a remote debug session in your eclipse IDE.

Please be sure that you choose the correct host and the port number you have chosen in the jvm.properties file. I you want to debug a remote host, be sure to deactivate or configure the windows firewall so that a connection to the port is possible.

Start the Notes client. and then click debug in Eclipse. The Notes client will start as soon as the Eclipse debugger is successfully connected to the jvm of notes. The execution of the JVM will stop on every breakpoint you have set in your code the same way as if you had started the client directly from eclipse.

If you liked this tutorial please share it on your favorite social network and if you have problems please leave a comment. Thanks in advance.