Wednesday, June 25, 2014

Launch the Domino Designer from Eclipse to debug your custom Designer extensions.

Cameron Gregor asked me in a comment whether it is possible to launch the Domino Designer from eclipse in the same way like the Notes client and the answer is yes this is possible. In this post i will describe what you have to change in your existing notes launch config to start the Designer from eclipse. This enables you to debug Extensions for the designer or XPages. To follow the steps you need a working Notes plugin target and a launch config for the notes client. If you need help with this you can learn how to do this in my tutorial "How to configure Eclipse 4.3 to develop plugins for Notes Part 1 and Part2".

The goal is to have a full working Domino Designer, launched in Debug mode from eclipse.

Domino Designer launched in Debug mode from eclipse

The first step is go to your eclipse and open the "Debug Configurations" dialog.

Change Debug Configurations in Eclipse

In there duplicate your existing notes launch config.

Duplicate your IBM Notes Launch Configuration

Then change the Name and the "run a product" field to Domino Designer and

Change Run a product

Switch to the "Arguments" Tab and change the Program arguments to

-vm ${rcp.home}/../jvm/bin\j9vm\jvm.dll
-nl en_US

Save your changes with the "Apply" button. Then click the debug button to launch Designer. Be sure that you have no open instance of Notes/Designer because only one instance can be open at the same time.

Change program arguments to launch IBM Domino Designer from Eclipse

When everything works, you will get a designer window with a welcome screen. To close the welcome screen, choose "Close Perspective" from the Window menu.

Close Perspective in IBM Designer

Then you should see your normal Designer UI. Maybe you get many error message in the Problem view that some Java elements cannot be resolved. No problem we will fix this in the next step. 

AbstractCompilePage cannot be resolved

Open the Preferences of Designer and navigate to "Plug-in Development" -> Target Platform. Change the location from "NotesProgDir\framework\eclipse" to "NotesProgDir\framework\rcp\eclipse". Click Apply and "Ok". Eclipse will reload the target platform.

Change Target Platform of Eclipse

After reload all error message will be solved automatically in the background. Now you can try or debug your extensions in  Designer.


  1. Hi Ralf,

    I'm trying to build a little DDE Plugin-Extension (it's a dependency documenter that shows which script library inherits from which other script library) and I've been struggling the past few days to get the run configuration within Lotus Expeditor to point to DDE (I've been using a 'Client Services' Run Configuration instead of the Eclipse Application. I tried your method, in desperation, and it worked.

    I think you are the only resource for DDE Plugin development. René Winkelmeyer and Karsten Lehmann had loads of information from 3 - 4 years ago, but they aren't blogging about it anymore.

  2. Sorry, the last post is from me, Andrew Magerman. Since I'm there, I was wondering if you could help me find some documentation concerning the name of the plugins that are needed for Notes 9 dev. In previous versions one needed

    but I can't find these anymore. Can you help?

  3. Thank you for the compliment. Hm in my 9.0.1 installation i do still have the plugins you mentioned.

    Both are in the framework\shared\eclipse\plugins folder.

    1. Thanks Ralf. I was on the wrong tab (Extensions instead of Dependencies). Now I'm getting a billion java stack traces, and I've no idea as to which ones are the ones I can ignore and which ones are the correct ones. Sigh.

  4. Hi Ralf,

    Still running into problems for launching DDE directly from Eclipse.

    I did a fresh install using Luna (Eclipse 4.4). Would that eventually be the cause?

    I'm following Mikkel Heisterberg's install instructions. The normal Notes client is launching fine.

    The DDE is not launching, I'm getting loads of stack dumps:

    SEVERE An error occurred while automatically activating bundle
    SEVERE An error occurred while automatically activating bundle org.eclipse.core.resources

    SEVERE CLFAD####E: It appears that Domino Designer failed to successfully shut down in a previous session.
    java.lang.UnsatisfiedLinkError: njnotes (Not found in java.library.path)
    WARNING The workspace exited with unsaved changes in the previous session; refreshing workspace to recover changes.

    And this is without having defined any kind of plug-in project.

    I'm at my wit's end. It's been three days now I'm trying. At least now I've abandoned the idea of using Lotus Expeditor.

  5. Hi Andrew,

    i really recommend, that you will start with a fresh eclipse workspace and then follow my tutorials to start Notes from Eclipse and then when this works you make the changes for DDE. If you get a problem zip the workspace and send it to ralfDOTpetterATgmailDOTcom with the output you get when you try to launch. I will have a look what the problem is.

  6. Weird, I made a comment yesterday but it didn't register.

    I got the source of my problems: I finally understood the 'Main' Tab - Workspace Data tab of the run configuration: I now get that this part of the tag defines a 'temporary' workspace. Since I was naming the Run Configurations exactly the same, I was landing on an old, broken workspace. I set the path to be hardcoded and set the run configuration to clear the workspace before starting. Problem solved.

    Thanks for your kind assistance. It's been very frustrating, but I've learned a lot more. Do you know those rooms in fun fairs where there's a mirror behind you and at the back of you and you see many, many reflections. I felt like that as well. I'm doing some work in Eclipse, for another Eclipse implementation, and every single folder is either called rcp, workspace, framework, or eclipse. In which workspace am I right now?

  7. Hi Andrew!

    I am glad that it works now for you.

  8. Hi Ralf, I've just updated my Notes to FP8 and my launch config's for Notes and Designer no longer work.
    I assume it might be something to do with the new Java 8 runtime. There are a few error messages but the last SEVERE one is :
    "The bundle failed to start because the native operating system libraries"

    Any tips on what I might need to change to get a debug launch config going ?

  9. Have you upgraded the JVM definition in eclipse to java 8? And maybe you will have to change some settings in your launch config. I have not tried FP8, but i will try soon and if there is interest i will make a blog post.

    1. Hi Ralf, actually I can't really get it to work. ( I did recreate JVM's etc) I managed to launch it but then couldn't do much. menus weren't showing up etc.
      I will try again from a blank workspace but If you do get around to testing it with FP8 then please let me know what you find out!

    2. Ok i will analyze the problem and then post a solution.

    3. So i have found three possible problems.

      1. Be sure, that the Notes program directory is in the path of the operating system.
      2. Add the line "-Djava.library.path=c:\Progra~2\IBM\Notes" to your VM arguments in your launch configuration
      3. When you add a FP to an existing installation the plugins already exist will not be replaced, but the new Version will be added to the plugins directory. So when you create the target platform definition you have many plugins doubled. Remove all old plugins from your target definition. If you need help with this, i can send you my target definition file per mail.

      When i make the above three modifications the Designer with installed FP8 works without problems.

    4. Thanks Ralf I will give this a Try from a new workspace and see how it goes.
      The duplicate plugins seems to be strange problem because I thought OSGi would only load the latest versions?

    5. The problem is, that the developer at IBM has no idea how the versioning scheme of OSGI works. It is not enough to only change the qualifier when a plugin has been updated with an API change. Here is an excerpt from the OSGI documentation:

      "The semantics for the version parts are therefore defined as:
      — Packages with versions that have different major parts are not compatible both for providers as
      well as consumers. For example,
      are completely incompatible.
      — API consumers are compatible with exporters that have the same major number and an equal or
      higher minor version. API providers are compatible with exporters that have the same major and minor
      version number. For example,
      is backward compatible with
      for consumers but for providers it is
      incompatible. Consumers should therefore import
      and providers should import
      — A difference in the micro part does not signal any backward compatibility issues. The micro
      number is used to fix bugs that do not affect either consumers or providers of the API.
      — The qualifier is usually used to indicate a build identity, for example a time stamp. Different
      qualifiers do not signal any backward compatibility issues."

    6. Thanks Ralf, i didn't realise that I thought that the qualifier would be enough to ensure only the latest version is loaded

  10. Hi Ralf, I think you are right. I decided to re-do your tutorials and start from beginning, creating JRE and new launch configs and they both worked fine!
    Thanks for your quick response and please never delete your blog :)