For Domino customers on v9 or 10, you might be familiar with debugging a Java agent remotely on IBM JVM using the following server ini’s and set Port 8000 in Debug Configuration from the Designer client:
This will work up to Domino v10 but not on Domino v11. In fact, doing so will cause it to crash! This article is going to help developers looking for a way to debug Java agents remotely on Domino v11. The pre-requisites are:
- Domino v11 or above on Windows Server 2016 / 2019.
- HCL Domino Console.
- Notes, Designer and Administrator Client v11 or above.
- Java agent to be debugged.
- Any Web Browser to run Java agent.
Domino v11 uses OpenJDK. With the above ini’s enabled, both the JVMs would attempt to bind to same port (8000) and the second process that attempts to bind to this port would fail and crash. To overcome this problem, the idea is to remove the Port 8000 from the Debug and attach it to some other random Port.
First, you will need to add the below ini’s to the server’s notes.ini.
Note that we are not binding the Debug to Port 8000 by omitting address=8000, as compared to ini which was set on earlier version of Domino.
The JVM will then pick a random port. To know the random Port number, simply quit and load http or run your Java agent from web browser and check the console from HCL Domino Console Program. You will need to restart http task after adding those ini’s to make it work.
Note down this Port number somewhere as you would need it in next step. (The server console in the Administrator Client doesn’t show the Port number information.)
You should land on the Debug Configuration window. Here you need to mention the Port number which you noted down from the HCL Domino Console in the earlier step and then select “Debug.”
You should see this message in Status bar which confirms Debug has connected on the Port number you mentioned.
You are now ready with the Debug configuration and set to debug your Java agent. You’ll need to set the breakpoints in your Java code to debug the same. You can set multiple breakpoints.
Once you have set the breakpoints in your code, run the agent from the web browser. You should see a Confirmation window on Designer client to open Debug perspective window. Select “Yes”.
The Designer perspective will change to Debug perspective which contains views for displaying the debug stack, variables and breakpoint management.
At this point, the usual Eclipse debugger features will become available (managing breakpoints, stepping, continuing, viewing variable values, etc).
The steps to debug a scheduled Java agent (AMGR) will remain the same. Instead of waiting until the agent is scheduled, run the agent from server console using “Tell amgr run” command. Get the Port number from HCL Domino Console Program by running Java agent using “Tell amgr run” command and then set the Port number in Debug configuration as we did in the earlier steps.
This completes the steps on how you can debug Java agent remotely on Domino v11. We hope you enjoyed reading this article and you have find it helpful.
Happy coding 🙂