Bob Balaban's Blog


    Bob Balaban


    Want to debug Java agents INSIDE Designer? You can! (sort of)

    Bob Balaban  July 7 2010 02:20:00 PM
    Greetings, Geeks!

    Here's a little something I stumbled upon last night: (using Designer 8.51) a way to actually debug Java agents *without exiting Domino Designer*!

    I'm pretty sure this is not documented, or actually, even supposed to be possible. But, here's the scoop.

    First, this only works if your agent is also set up to be a Java "application", i.e.,it has to have a main() method in it. To see how to do that, visit my previous posts on the "2-headed beast" technique.

    Assuming you've done that, open up the agent (.java) file in Designer. A new menu choice appears in the top menu bar: "Run". Click on that, and select "Debug Configurations". You are now going to set up a debug configuration that tells Eclipse (hidden down below the layers of Designer) how to launch and debug your Java code. You'll want to right-click and select "New" to create a new configuration. You can name it (but in my experimentation, I've found that Designer rarely, if ever, saves these, so you'll have to create the configuration anew each time). See Figure 1 for a screenshot of the dialog that comes up. You want to tell Eclipse that you've got a "Java Application" (that's why you need to be using the 2-headed beast, so that your code is both a Java "main" application AND a Domino agent).

    Figure 1: Image:Want to debug Java agents INSIDE Designer? You can! (sort of)

    You want the "project" to be your current NSF/NTF. Once that's set, you should be able to click "Search" for the "Application" choice and see your Java class name there.  I like to use the "stop in main" checkbox, so that the debugger automatically breakpoints the main() method. But it's not required, you can just set breakpoints yourself, wherever you want by double-clicking in the left-side gutter.

    The first time I tried that, I got an error saying that the program was not compiled to contain line numbers for the debuggerer. If you get that too, just go to the Project menu, select Properties. Click on "Java compiler" in the left on the left side of the dialog box, and change the following options (see Figure 2):
      - Compiler level to 1.5
      - select the "include line numbers" checkbox
      - select the "add variable attributes" checkbox

    Figure 2: Image:Want to debug Java agents INSIDE Designer? You can! (sort of)

    Click "Apply" and "OK". When it asks if you want to rebuild the code, you do.  Designer will usually save these settings, though I've found it confusing - apparently "project properties" can apply to the .java file, OR to the entire agent, and the UI doesn't really make the distinction obvious. Or maybe I'm wrong and just confused....

    So, once that's all set up, you can click the "Debug" button in the configuration dialog, and it will launch your agent. You'll probably be prompted to switch to the "Debug perspective", which I do recommend. For some reason, at least in my workspace, the debug navigation smarticons don't appear (step in, step over, etc). But you can still right-click in the stack-trace panel and get all the choices, the most common of which have FunctionKey shortcuts (F6 for "step over", and so on). It's just like real debugging!!

    Except, well, I couldn't figure out how to debug into a scriptlib. If you have supporting code out on your hard disk, you can add the folder and/or files to the "source code path" in the debug configuration dialog, or even specify it on the fly the first time you elect to step-in to the code. But scriptlibs are in the NSF/NTF, not on disk per se, and i couldn't figure out how to reference them. Anyone know how to do that?? It's worth a classic Looseleaf t-shirt (available in all sizes S to XXL, except for XL) to me to know!

    One other thing I had to play around with: how to get back to the "normal" Designer UI from the Eclipse debuggerer. Here's how I did it:
       - Click on the Window menu
       - Select "Open Perspective", then "Other"
       - Find "Domino Designer" in the big list, double-click on that

    A few caveats:
      - I'm pretty sure this is unsupported functionality, so it may disappear in some future release
      - I'm pretty sure this is unsupported functionality, so it's not guaranteed to always work
      - It's fun to play with, but I think for heavy debuggering I'm still going to just use standalone Eclipse
    Enjoy! Geek ya later!

    (Need expert application development architecture/coding help? Contact me at: bbalaban,
    Follow me on Twitter @LooseleafLLC
    This article ┬ęCopyright 2010 by Looseleaf Software LLC, all rights reserved. You may link to this page, but may not copy without prior approval.

    1Pierre  07/10/2010 11:03:55 PM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    I really do not understand why IBM is making it so complicated to move from LS to Java. They are not making any secrets about moving everything they can to Java but for Domino there are no incentives at all. If the junky LS debugger could be replaced by Eclipse, it would be the biggest single compelling reason to switch.

    2Bob Balaban  07/12/2010 2:45:54 PM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    @1 - Thanks for your comments, Pierre. It's a complicated question. I certainly agree that debugging Java inside Designer should be much, much easier, and that the current difficulty is limiting the adoption of Java by LotusScript developers.

    A somewhat bigger issue, however, is the one of LotusScript/Java inter-operability. Any organization that has been around for a while has most likely accumulated a lot of working, debugged, and sometimes mission-critical LotusScript code. They don't want to throw it away and re-code everything in Java, or XPages, or something else. Developing new assets in Java is all very well, but, apart from running agents through the object model, you cannot call between languages (let's ignore LS2J, it's not a realistic solution for production apps).

    No easy answers, unfortunately.

    3Kerr  07/14/2010 10:29:51 PM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    I always thought that IBM should have tried to get their hands on Sun's Semplice project, the VB to bytecode compiler. Probably the effort involved in writting their own from scratch is not worth it, but had they gone ahead with the the Sun purchase then it would have come along as part of the deal.

    With Semplice as a base, reworked as an LS version, we could have some interesting options. Certainly interoperability with other JVM languages would become trivial.

    4Bob Balaban  07/15/2010 6:18:04 PM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    @Kerr - Interesting idea! Not sure how much leverage a vb/java cross compiler would provide (LS bytecodes, unlike the language itself, were not modeled after compiled vb). If it works from sources, not bytecodes, then maybe something could be done.

    There was (I was told, at the time) an investigation into a bytecode cross-compiler for LS to Java. Apparently (as you'd expect) a lot of it would be straightforward, but there were some nasty problems that appeared intractable (or which nobody thought it was particularly important to solve?). Variants, for example. Many (or most) variant types could be mapped to Java Objects, but not all (variants containing scalars...). There were probably other issues, but it was long ago (1996 i think), and I don't remember the details.

    Still, could be a good business opportunity there if someone were to crack it - there is a LOT of LotusScript code out there today, and there must be some people willing to pay to have it converted to Java.

    5Kerr  07/15/2010 7:27:29 PM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    My understanding is that Semplice compiled VB source into JVM bytecode, so yeah we would be looking at dealing with LS source rather than compiled code. Is there much LS out there with missing source?

    6Tim Curtin  07/22/2010 12:29:55 PM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    Bob -

    I currently have a java applet, pulled into a notes application as an "Applet Resource", and then included on a form. I'm able to debug that using either external Eclipse or Domino by creating a "Remote Java Application" debug config, assigning a port on localhost that matches the port chosen in the menu item Tools/Java Debugging Preferences/Client Agents option under the Domino perspective.

    So far, it seems like that allows all of the normal debugging - setting breakpoints in code, single-stepping in and out of functions, etc. Its a bit clunky, but that may be my fault for not having the right code in the Source path under the debug config. (I had to manually add the path for the applet's source, for instance.)

    My question - I'm considering converting this applet to an agent, which I'll then trigger via a buttonpress on the notes form. Your method makes it sounds as though direct debugging might not be an option, and since I need information in documents in the notes database, I can't just run as a standalone java applet. Have you tried remote debugging for your agent? Does it work properly?

    Also, I have it on good authority from an STSM on the Domino design team that you can't use code in a Script Library in an applet. Sounds like that may not be as available for use as it seems, so you may just not be able to step into it at all. (That would be unfortunate, but not necessarily surprising.)

    7Bob Balaban  07/22/2010 1:39:11 PM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    @6 - Tim, I have never been successful at getting the remote debugger to work. Plus, it annoys me that it requires me to make a code change (add a Sleep()) which then has to be removed later.

    I haven't written an applet in years (thought nobody used them anymore), and historically there have been all kinds of problems getting them to work inside the Notes client. Sorry, can't help you there.

    If you convert your code to a 2-headed beast-flavored agent (see other posts in this blog), then you should be fine for standalone debugging.

    8Pierre  07/24/2010 7:41:19 AM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    I am still convinced that if IBM were to provide a very nice IDE/Debugger for Java and leave the LS there as is, people would naturally move to Java for their new code. No need to redo the existing LS code (I certainly have no intention for my code, I just want to be able to do with Domino what I could do with VB 10 years ago: "immediate" window is the main one, conditional break, etc...)

    9Pierre  07/24/2010 8:13:51 AM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    And while I am at describing my X-mas list for Notes Java, would be nice if those damned .recycle could be eliminated (like with Domingo)

    10FK  07/30/2010 8:36:14 AM  Perspective switch

    Once opened via Window/Open Perspective you can use CTRL+F8 shortcut to cycle through perspective history.

    11Matt Vargish  08/27/2010 1:05:04 PM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    Hi Bob,

    Just catching up on my blog reading and found this. Interesting stuff. I wrote up a similar approach to remote debugging a few weeks ago, and would have linked here if I'd been up-to-date! (I did however link your "2-Headed Beast").

    I was able to debug into Script Lib code -- because I was remote debugging, I found that if you open a Java Agent that imports a Java Script Lib, projects are created for both the Lib and the Agent, and creating the debug configuration for the Agent project seems to pick up the source for the Lib. Details here:

    { Link }

    12Bob Balaban  08/28/2010 7:06:25 AM  Want to debug Java agents INSIDE Designer? You can! (sort of)

    Thanks for your comments!