PlanetNTF

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  "..frameworkrcpdeploy" 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.

One of the best things about Notes is that it can synchronize your settings on different devices. So you have for example the same settings on your Desktop and on your Laptop. This feature is called roaming. This works really great for all IBM provided Features, but when you have deployed your own or third party eclipse features to your Notes client the settings of them will not roam to your other clients as the IBM Features do. This is very annoying for your users. So i have analyzed the whole roaming process in the client and discovered, that IBM has already implemented an mechanism to activate the roaming feature for 3rd Party Plugins. I have not found any documentation for this on the internet, but it works without any problems.

So let's have a look how the roaming of Preferences in the Notes Standard client works. If roaming is enabled for your user you will have a "roamingdata.nsf" on your client and on the server. In this database there is one document for every plugin which contains the preferences. On the client start this database is replicated with the server and then the settings in your notes data/workspace folder gets updated with the settings in the documents in "roamingdata.nsf". When you end the client every setting you have changed will be updated in the corresponding document in "roamingdata.nsf" and all changed documents will be replicated to the server.

Follow this easy steps to enable the roaming of the settings for your own plugins:

The first step is to retrieve the existing configuration file for the roaming service from the "com.ibm.notes.roaming.provider" plugin. To do this copy the plugin from the "C:Program Files (x86)IBMLotusNotesframeworksharedeclipseplugins" to your desktop and change the extension of the plugin from ".jar" to ".zip" Then open this archive file and extract the roamingconfiguration.xml file in the configuration folder to a local folder. This file contains the complete configuration of the roaming service


You can edit this file with your preferred editor. I use Notespad++ because it is xml aware. Simply add an "roamingbundle" directive in this file for every plugin for which you want that notes should roam the settings.


If you do not know which plugins have settings have a look in the notes "..workspace.metadata.pluginsorg.eclipse.core.runtime.settings" folder. Every file in this folder is potential candidate for your list.

Then deploy your customized "roamingconfiguration.xml" file to every workstation for example with a windows group policy or other software distribution tool.

To tell Notes that it should use your customized file and not the built in file in the plugin simply add the "roaming.config.url=file://c:/Program Files (x86)/IBM/Lotus/Notes/roamingconfiguration.xml" to the com.ibm.rcp.roaming.service preferences. Be sure to update the path of the file to the correct path where you have deployed your configuration file. In my example i have used the Notes program directory. You can set this preferences with a desktop policy or you can set it in the plugin_customization.ini of your Notes installation.


If you like this How to or if you have problems with it, please leave a comment.